Most teams have an architecture diagram. Fewer have a diagram they trust.
The codebase is the only completely current record of the system, but reading it file by file is a poor way to see boundaries, dependency direction, data access, and how the shape has changed over time.
So this week I am running a deliberately simple experiment:
Run an architecture X-ray on one repository and find one thing you did not know.
The challenge
You need Python 3.10 or newer:
pipx install archsteer
cd your-repo
archsteer xray
Open .archsteer/report.html, then look for one surprise:
- a dependency crossing a boundary you thought was clean;
- a module that owns much more of the system than its name suggests;
- data access in an unexpected layer;
- an external call site nobody remembered;
- a legacy architecture still living inside the current one; or
- a structural change that should have produced an ADR.
Share the finding, open an issue if the model is wrong, or keep the result private. All three outcomes are useful.
What it does and does not do
ArchSteer statically reads the repository and emits a code-derived model, living architecture documentation, diagrams, an evolution feed, and draft ADRs for boundary-altering changes. It runs locally, does not execute the target code, does not upload the repository, and requires no account.
The model is heuristic. It is supposed to be an always-current starting point that an architect can curate, not a formal proof that the system behaves a certain way. A confidently wrong boundary is exactly the kind of result I want reported.
Current language support covers Python, TypeScript/JavaScript, Java Spring, and Salesforce Apex.
Why this matters more with coding agents
Coding agents learn the local pattern from the files around an edit. In a half-migrated codebase, legacy examples outnumber target examples, so an agent can produce perfectly plausible code that pushes the architecture backward.
An accurate current model makes a control loop possible:
- derive the architecture the code actually implements;
- declare one target invariant;
- put the relevant invariant into the coding agent's file-scoped context;
- check the resulting code; and
- block only net-new violations, so delivery continues while debt ratchets down.
The challenge starts with step one because it should provide value before a team writes any rules.
Participate
Run:
pipx install archsteer && archsteer xray
Then share one surprising finding and link to ArchSteer on GitHub, or file the most specific example you can where the model got your architecture wrong. ArchSteer is free and MIT licensed.