The Architecture X-Ray Challenge: Find One Surprise in Your Codebase

ArchSteer — Thu, 23 Jul 2026 15:34:21 +0000

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.

Originally published at archsteer.com. I build ArchSteer and welcome blunt feedback on the model.

DEV Community: ArchSteer

The Architecture X-Ray Challenge: Find One Surprise in Your Codebase

The challenge

What it does and does not do

Why this matters more with coding agents

Participate