architecture-review

Architecture Review

Review architecture quality, design consistency, extension seams, and pattern adherence.

Scope

1. Indirection pressure (primary focus)

Flag layers that add no architectural value:

• runtime import cycles across split modules
• pass-through facades that only rename or re-export
• alias/wrapper layers without independent policy or invariants
• DI bags exceeding practical seam or testing needs
• singleton imports in library modules that should accept injected params — an application reading its own central store is idiomatic and not this finding
• facade-for-facade chains

Default: if a layer carries no policy, invariants, or boundary isolation, remove it.

2. Extension blockers

• hard-coded behavior where project docs or an existing sibling seam establish a policy/config point
• new features requiring edits across many unrelated modules
• private coupling preventing additive providers or plugins
• extension seams with no current use adding maintenance cost

3. Boundary and contract integrity

• contracts and schemas as source of truth
• renamed contract terms stay aligned across the boundary; partial renames count as drift
• dependency direction consistency
• design-pattern consistency for extension seams
• logic that reads another module's state more than its own; judge one function body at a time — how much of it traverses that module — not by whether the reference was injected or passed in
• chained access (a.getB().getC()) reaching past a stated contract into internals the caller doesn't own
• modules reaching into each other's internals instead of through a stated contract

4. Cohesion and responsibility

• oversized or multi-responsibility files — for a file, size alone isn't the finding, so name the second responsibility or don't report it
• SRP violations: mixing unrelated concerns
• at function scale length is a finding on its own: a body past ~50 lines, one needing section comments to navigate, or one that computes a result and then formats it for presentation. An exhaustive match or switch whose length is entirely its arms is not this — there is no substructure to lift out
• duplication wants a name once it is a substantial block repeated twice or a small one repeated three times, in one file or across modules — size and copy count trade off against each other, so a two-line body appearing seven times counts. Leave what is duplicated on purpose: boundary-local copies keeping two modules independent, and conditionally-compiled twins that merging would defeat