← All posts

Engineering · 2026.10.10 · 5 min

Writing My Own Module Dependency Scanner: An Architecture Map Plus Layering Rules in CI

My 18 backend packages had several dependency cycles tracked only by memory, so I wrote a compile-free scanner for a clickable architecture map and CI layering rules, then cleared 23 violations in one day.

Reading
Theme
Size
Width

I wanted an architecture map I could click through from a layered overview down into submodules, then into the code itself, with a clear definition of which modules may depend on which. At the time the repo had no dependency rules at all. The backend's 18 packages had several cycles, lending and subscription for example, and the only thing keeping track of them was memory.

What I ended up with is a scanner I wrote myself. It doesn't compile anything, it reads the source directly, it works for both frontend and backend, and its rules run in CI. With the layers ordered to match the existing code there were only 23 violations. I cleared all of them the same day, and only 2 actually needed dependency injection.

Why I wrote my own

I looked at cargo-modules, dependency-cruiser, and ESLint's boundaries rules. Each one covers only one side of the stack, their rule formats don't connect to a map, and the backend tool needs a compile first.

So I wrote a tool that uses nothing but Node's built-in modules. For Rust it recognizes paths like crate:: and super::, plus access through State. For TypeScript it recognizes import, export … from, and import(). The whole check takes about half a second.

The map is a single HTML file with roughly 9 MB of embedded source, and it stays out of version control. It's derived from the source, and committing it would add a 9 MB diff to every PR.

The rule: depend only downward

Units are arranged in rows from top to bottom. A unit may only depend on units in the rows below it. Units in the same row can't depend on each other, and nothing depends upward. Inside a single package there's one more rule: controller → service → repository → entity, and dependencies only go forward along that chain.

Exceptions live in two lists. allow holds exceptions that exist by design, and debt holds existing violations. If any entry in either list doesn't match a real dependency, the check fails. So when a dependency gets removed and the list isn't updated, CI flags it, and the lists never pile up stale entries.

Backend CI gets one extra check step, and the frontend check hooks into npm run lint. A new reverse dependency gets blocked at the PR.

Illustration: units are arranged in rows and may depend only on rows below; same-row and upward dependencies are not allowed, and inside one package controller, service, repository, and entity depend only forward. Exceptions live in allow and debt lists, and an entry that matches no real dependency fails the check.

Layers ordered to match the existing code

An idealized layering would have produced over a hundred violations to clean up at once, a list so long nobody would read it. So I ordered the layers to match the current code, picking the order with the fewest violations. Block new violations first, then clean up gradually.

For example, subscription sits below lending, because the lending engine reads plan limits and subscription status in 10 places, while the only thing going the other way is the performance fee calculation reading lending data. With that ordering, the backend's 700 files and 4,744 references had only 22 violations, and the frontend had 1. The layering roughly matches the existing code, and the cycles are concentrated in a handful of files.

Diagram: the lending engine reads plan limits and subscription status in 10 places, while the only reverse dependency is the performance fee calculation, so subscription sits below lending. An idealized layering would have produced over a hundred violations; matching the current code left 23, with 22 across the backend's 700 files and 4,744 references and 1 on the frontend.

The layer order was sorted by an agent based on violation counts, and I haven't reviewed it entry by entry. If I disagree with something later, I just edit the rules file.

23 violations, mostly fixed by moving files

I tried fixes in this order: move the file first, change the layering if that doesn't work, and inject only as a last resort.

Most were files sitting in the wrong layer, and moving them was enough. 2FA step-up verification moved to auth, for instance, and the Telegram binding endpoint moved to notification. Two groups were cases where the layers had been drawn too coarsely. The performance fee and apikey services and controllers genuinely need to read and write lending data, so they went above lending, while their entities and repositories stayed below.

Only 2 places really needed injection: lending triggering performance fee settlement, and the notification center reading active announcements. In both cases the two sides genuinely need each other. The approach is to define a trait in the lower layer, implement it in the upper layer, and pass it in at startup. Injection comes last because once it's in place, the lower-layer code no longer shows who it's actually calling, and anyone reading it has to jump one more hop.

After the cleanup, debt is empty. Behavior and API URLs are unchanged, all 2,793 tests pass, and the backend went to PROD the same day.

Flow chart of fixing 23 violations in order: most were fixed by moving files, such as 2FA step-up verification to auth and the Telegram binding endpoint to notification; 2 groups changed layers, with performance fee and apikey services and controllers moving above lending; only 2 places needed injection. Afterwards debt is empty, all 2,793 tests pass, and the backend shipped to PROD the same day.

Limitations

The scanner doesn't understand semantics. Items re-exported through pub use are only attributed to the file that re-exports them, and paths that only appear after macro expansion aren't recognized at all. That's the cost of skipping compilation. Keep these two blind spots in mind when reading the rules and the map.

#Module Dependencies#Rust#TypeScript#Software Architecture

Letters

Loading comments…

Next

Engineering

Should You Change Strategy While Losing? Writing the Review Process as Code

I wrote 'reassess if losses persist' as preset triggers and a fixed decision order; the first automatic trigger caught two bugs in the review code, and none of 13 risk-reduction variants passed the preset bar.