Architecture Patterns

Domain skill for system design, structural evaluation, and architecture decisions.

Iron Law

DESIGN ARCHITECTURE FROM FUNCTIONALITY, NOT TO FUNCTIONALITY. If you can't trace a component to a user flow, delete it.

Architecture serves user flows. Not the other way around.

Prerequisite: Map Flows First

Before designing ANYTHING, enumerate flows. Track each design activity as a task:

TaskCreate("Map user/admin/system flows", "Enumerate all flows before designing components")
TaskCreate("Coupling analysis", "Check imports, circular deps, god objects, hidden coupling")
TaskCreate("Design proposal", "Components, responsibilities, dependencies, data flow")
TaskCreate("Decision documentation", "Context, options, trade-offs, decision, consequences")

1. User flows — what does the user do, step by step?
2. Admin flows — what does the operator/admin do?
3. System flows — what happens automatically (cron, webhooks, events)?

Each flow is a sequence: trigger → steps → outcome. Every component must serve at least one flow.

TaskUpdate("Map user/admin/system flows", status: "completed") after all flows enumerated.

C4 Model Views

Navigate the right level of abstraction:

Rule: Start at the highest relevant level. Zoom in only when needed. Most design discussions happen at Components level.

Coupling Analysis

TaskUpdate("Coupling analysis", status: "in_progress")

Check actual dependencies, not assumed ones:

# Find imports and dependencies
grep -rn "import\|require\|from " --include="*.{ts,js,tsx,jsx,py,rb}" -l
# Check for circular dependencies
# Look for A imports B AND B imports A patterns

Red flags:

• Circular dependencies — A→B→C→A. Break the cycle with interfaces or events.
• God objects — One module imported by >50% of files. Split by responsibility.
• Hidden coupling — Shared mutable state, global variables, implicit ordering.
• Shotgun surgery — One feature change requires edits in 5+ unrelated files.

Dependency Direction

Dependencies should flow ONE direction:

UI → Application → Domain → Infrastructure
        ↓
    External APIs

• Domain depends on nothing
• Application depends on domain
• UI/Infrastructure depends on application and domain
• Never: Domain → UI, Domain → Infrastructure

API Design Principles

• Align endpoints with documented user flows, not internal structure
• One endpoint per user action (not per database table)
• Version APIs when breaking changes are unavoidable
• Validate at the boundary — trust internal code

TaskUpdate("Coupling analysis", status: "completed")

Failure Modes and Non-Goals

Architecture decisions are incomplete without an explicit fence. Every design proposal MUST capture failure modes and non-goals alongside the happy-path component diagram. A design that only describes the success path is a design that will fail under the first unexpected condition.

Non-Goals (What This Design Does NOT Do)

Non-goals are scope fences. They prevent the design from sprawling into adjacent problems and prevent reviewers from rejecting the design because it "doesn't handle X" when X was never its job. Capture non-goals as a bulleted list in the decision record:

• What this design explicitly does NOT cover (features, flows, or actors out of scope)
• What it does NOT guarantee (consistency levels, durability, isolation, ordering)
• What it does NOT replace (existing components that stay untouched)
• What it does NOT optimize for (latency, throughput, cost, developer ergonomics — pick what matters and name what is deprioritized)

Non-goals must be written as declarative negations, not hedges. "Does not support multi-region writes" is a non-goal. "May eventually support multi-region writes" is a hedge and is not useful.

Failure Modes (How This Design Behaves Under Failure)

Every component in the design must have documented behavior for at least these failure modes:

Record each failure mode's expected behavior in the decision record. If the design has no answer for a failure mode, that is a gap to close before proceeding — not a detail to defer to implementation.

Integration With the Decision Record

Extend the Decision Framework table (below) with two new fields when documenting architectural decisions:

• Non-goals — bulleted list of what this decision does NOT do
• Failure modes — table of failure mode → expected behavior for each component touched

These fields are NOT optional. A decision record missing them is incomplete and should not ship.

Why This Belongs at Design Time

Failure modes discovered at implementation time force backtracking: the author has to redesign mid-build to handle a case the design ignored. Failure modes discovered at verify time force fix-forward loops or rework. Failure modes captured at design time become test cases, verification commands, and explicit non-goals that prevent scope creep. The cost of capturing them early is minutes; the cost of discovering them late is days.

Decision Framework

TaskUpdate("Decision documentation", status: "in_progress")

For each architectural decision, document:

TaskUpdate("Decision documentation", status: "completed") Use TaskList to confirm all design activities resolved before proceeding to implementation.

Existing Pattern Check

Before proposing new architecture, check what exists:

# What patterns does the codebase already use?
ls -la src/ app/ lib/
grep -r "class \|module \|interface " --include="*.{ts,js,py,rb}" | head -20
git log --oneline --all -- "src/*/index.*" | head -10

Rule: Follow existing patterns unless there's a documented reason to diverge. Consistency beats novelty.

Anti-Patterns

Rationalization Prevention