architecture-review

Run npx madge --circular --extensions ts,tsx,js,jsx on your source directory to list circular dependency chains. You can also use madge --orphans to find unreferenced modules that may indicate dead code.

Recommend replacement only when the existing structure provably blocks the goal, adapting it costs more than replacing it, and a staged migration with rollback exists. Otherwise adapt in place behind an existing seam, which is the lowest-risk default.

An ADR is a markdown document capturing the context, decision, alternatives, and consequences of a significant architectural choice. Write one when a decision like a database or framework selection is made or proposed, not for trivial or purely operational choices.

Use ripgrep to count local imports per module and sort by frequency to find god-module candidates, then combine with git log churn over the last six months. Files with both high fan-in and high churn are the highest refactor risk.

Skip it when the task is unrelated to core operations, requires production deploys or secret disclosure, or when you first need a structural map from a repo-diagnostics pass. A narrower existing project instruction may also already cover the need.