System Architecture

System Architecture

Design the shape of the solution before anyone builds it: what the pieces are, how they fit, and where the seams go. Aim for deep modules, not a sprawl of shallow ones.

When to use

• You have approved requirements and the work is non-trivial — a new subsystem, several components, real integration.
• Skip for a small feature; its structure lives in writing-plans' interface map, not a separate design.

Procedure

1. Components and boundaries. Name each module by what it does and what it deliberately doesn't. A module earns its place if removing it would spread its complexity across the callers; if complexity merely relocates, it's shallow — merge it.
2. Data flow. Trace the request/response and event paths end to end. Each should be followable from entry to effect.
3. External services. Map every third party (payments, mail, realtime, storage). For each, state the testability strategy: how you trace the data path through it, and how you behave — and test — when it's unavailable.
4. Seams. Put boundaries where you'd swap an implementation, and inject across them. Don't add a port for a hypothetical seam — two real adapters justify one; one doesn't.
5. Decide the load-bearing choices deliberately. For each significant, hard-to-reverse structural decision, weigh the real options and record the result as an ADR — architecture-decisions owns how to weigh them.
6. Name things in the domain's language, not generic "service / manager / handler". The vocabulary is itself a design decision.
7. Write the architecture section of the shared design document .augments/designs/{{YYYY-MM-DD}}-{{topic}}.md (the standard designs location; another path only if the user has set one).

Common mistakes

• Shallow modules — an interface as wide as the implementation behind it.
• Untested external-service paths — "it'll work in prod" is not a design.
• Designing for hypothetical futures (a port with one adapter, "for extensibility").
• Generic vocabulary that hides the domain.

For a high-stakes design, once the document is compiled, dispatch design-review.md — a fresh subagent that checks the whole design before anyone builds against it.

The module-design terms used here (deep module, seam, adapter, leverage) are defined once in refactor-architecture's vocabulary.md — both skills use them with the same meaning.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NjoyimPeguy
• Source: NjoyimPeguy/augments
• License: MIT

Install and usage instructions live in the source repository linked above.