This was probably inevitable. The only question was whether I was going to admit it early enough.
By mid-April, A11Y Cat’s runtime had become too large and too central to keep pretending one file could comfortably own everything.
The repo itself says this later in docs/ENTERPRISE_READINESS_GAP.md: scan-engine.js remains a maintainability and regression-risk hotspot. That is one of the more credible documents in the project because it does not flatter the architecture. It names the concentration problem directly.
The solution starts arriving in stages. There is an earlier modularization move around runtime bridge and UI modules, but the clearest turning point is 2a32f40, “Decompose scan engine runtime modules.” That commit creates explicit modules for assistant UI, panel state, route monitor, ticket dialog, manual review UI, clipboard actions, panel render, scan orchestration, and more, plus docs and decomposition tests.
I do not think this means the architecture was suddenly clean. In fact, the next few commits are about dependency wiring, initialization order, and finishing extractions. That part of the history is reassuring. It looks like a real refactor: valuable, but full of sharp edges you only hit once the pieces are actually separate.
The seam docs are useful here too. docs/runtime-modules.md and docs/SUBSYSTEM_SEAMS.md are not generic architecture essays. They read more like guardrails for future maintainers and reviewers: here is where settings contracts live, here is where export contracts live, here is where trust classification needs to stay consistent, here is where comparison provenance flows. That is what architecture docs look like when they are written to reduce future breakage.
I think this phase is especially important because it shows the builder responding to scale honestly. The project did not start modular. It became modular because the runtime had become too broad and too risky to leave monolithic.
That is a normal kind of growth if the repo is healthy enough to admit it.
Visual evidence
The runtime decomposition is architectural, not directly visual. There is no reliable screenshot that isolates the seam-cutting work itself, so I am not forcing one into the post.
What I was really learning here
I was learning that once a runtime gets broad enough, modularization stops being optional cleanup and starts being part of quality control. If too much lives in one place, unrelated changes get too easy to break.
Evidence
- Commits:
f935c84– earlier scan-engine ownership modularization2a32f40– runtime modules decomposition9a4c5d7– further extraction finished4078dd0,f369f9b,7bece19– dependency and init-order fixes after extraction
- Files:
../../src/runtime/modules/../../docs/runtime-modules.md../../docs/SUBSYSTEM_SEAMS.md../../tests/node/runtime-decomposition.test.js../../docs/ENTERPRISE_READINESS_GAP.md
