Architecture review — {{repo name}}

...

`: - **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline"). - **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`). - **Files** — monospaced list, `font-mono text-sm`. - **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below. - **Problem** — one sentence. What hurts. - **Solution** — one sentence. What changes. - **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers". - **ADR callout** (if applicable) — one line in an amber-tinted box. No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram. ## Diagram patterns Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point. ### Mermaid graph (the workhorse for dependencies / call flow) Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1." ```html

    flowchart LR
      A[OrderHandler] --> B[OrderValidator]
      B --> C[OrderRepo]
      C -.leak.-> D[PricingClient]
      classDef leak stroke:#dc2626,stroke-width:2px;
      class C,D leak

``` ### Hand-built boxes-and-arrows (when Mermaid's layout fights you) Modules as `

`s with borders and labels. Arrows as inline SVG `` or `` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight. ### Cross-section (good for layered shallowness) Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility. ### Mass diagram (good for "interface as wide as implementation") Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep). ### Call-graph collapse Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it. ## Style guidance - Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate). - Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings. - Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling. - Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI. - The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering. ## Top recommendation section One larger card. Candidate name, one sentence on why, anchor link to its card. That's it. ## Tone Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift. **Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality. **Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module). **Phrasings that fit the style:** - "Order intake module is shallow — interface nearly matches the implementation." - "Pricing leaks across the seam." - "Deepen: one interface, one place to test." - "Two adapters justify the seam: HTTP in prod, in-memory in tests." **Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place. No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one. ````