ArchiLens reads a Git repository, builds a module dependency graph from real imports, draws C4-style diagrams, checks architecture rules, and posts an architecture diff on pull requests. I had tested it on its own codebase for months. Then I installed it from PyPI as a stranger would and pointed it at seven projects I didn't write: Flask, FastAPI, Django, Express, NestJS, Spring PetClinic and gin.

Each run was the same four commands:

archilens init archilens analyze --repo . archilens check --repo . archilens diff --base <previous release> --head <latest release> --ai 

Nothing I'd call an edge case broke. The first command broke.

1. init made every Go project invisible

archilens init writes a starter .archilens.yml. It was an annotated example, and one of its lines was live config:

languages: ["python", "typescript", "java"] 

On gin, analyze found 0 files, wrote empty diagrams, and check happily passed four rules against nothing. Every Go, Rust and C# user who followed the README hit this on their first command. The same template also put a fictional PostgreSQL, Redis, Stripe and SendGrid on everyone's system-context diagram.

Now init runs a quick static discovery first. It writes the languages and modules it actually found, keeps active only the settings that hold for any repository, and turns the examples into comments built from your real module paths.

2. Example apps drowned out the product

The module diagram is supposed to show a project's architecture. For three of the seven, it mostly showed demo code:

Project The product Modules before After
Express lib 27 (26 example apps) 2
FastAPI fastapi 100 (about 80 doc snippets) 7
NestJS packages/* 83 (incl. 28 integration-test apps) 9

Root-level examples/, samples/, demo/, docs/ and benchmarks/ are now excluded by default. The rule is root-only on purpose: every Spring Initializr project keeps its code in the Java package com/example/demo, and a broader pattern would have deleted it.

3. A crash that only happens on Windows with redirected output

FastAPI, NestJS and Django are big enough to show a progress spinner. On Windows, with output redirected to a file (as on a Windows CI runner), the legacy cp1252 code page can't encode the spinner character, and the whole analysis died with UnicodeEncodeError. My first benchmark run hid it because I had forced UTF-8 output. Characters the console can't show now print as ?.

4. Django's module diagram was a wall of labels

Django 6.1 has 17 modules and 111 dependencies between them. Each arrow had an "N imports" label, so Mermaid shrank the modules to tiny boxes under the text.

Now line width shows the import count, from 1px for one import to 4px for the heaviest. My first version used fixed steps (1 / 2–3 / 4–7 / 8+), and on Django 33 of the 40 lines landed in the top step, so the widths said nothing. The scale is now relative to the heaviest dependency, on a log scale. Beyond 40 dependencies, every module keeps its strongest one, the rest of the slots go to the heaviest, and a collapsible table lists all of them.

The part that worked: the AI review

AI is optional and off by default. With a key, the PR comment opens with a review of the change's architectural impact. On Django 6.0 to 6.1 it named the real headline changes (fetch modes, bit aggregates moving from contrib.postgres into core, a new mailers subsystem, UUID7) and raised specific things to check:

Value no longer inherits SQLiteNumericMixin. Verify that SQLite numeric casting for Value expressions is still handled elsewhere.

On FastAPI and Express it said plainly that the architecture didn't change. That one request used 8,475 input and 598 output tokens. Reviews are cached by content, and every comment says what it used.

An ArchiLens comment on a pull request

A second round, on kinds of project I hadn't tried

After those fixes I tried types of project instead of famous repositories, and three more gaps showed up:

  • Vue and Svelte projects came out nearly empty. .vue and .svelte files weren't read at all, and neither were .mjs or .cjs. They are now, through their <script> blocks.
  • The system-context diagram was one box unless you wrote the external systems by hand. The parser already saw import psycopg2 and threw it away. Now a catalog of more than 40 systems maps third-party imports to what the code talks to. On Django it finds PostgreSQL, MySQL, Oracle, Redis, Memcached and SMTP, with no config and no AI.
  • Express had no component diagram, because that level drew classes and Express has none. A file of functions is now a component, and the imports between files are the arrows.

What I'd tell anyone building a dev tool

Run your own onboarding on code you didn't write. Seven repositories found four bugs that months of dogfooding hadn't, and the worst one was in the very first command.

[I built ArchiLens with Claude Code as a pair programmer, and the testing above was done the same way.]

ArchiLens is MIT-licensed: pip install archilens, or add it to a workflow from the GitHub Marketplace. The code is at github.com/saurabh-oss/archilens.