/design

description: "Designs system architecture with C4 diagrams and technology selection. Use when defining component boundaries, choosing tech stacks, or creating architecture documents."
argument-hint: "[component-name] - Optional: --residuality --paradigm=[auto|oop|fp]"

NW-DESIGN: Architecture Design

**Wave**: DESIGN (wave 3 of 6) | **Agents**: Morgan (nw-solution-architect), nw-system-designer, nw-ddd-architect | **Command**: `*design-architecture`

Overview

Execute DESIGN wave through discovery-driven architecture design. The command routes to the right architect based on design scope: system-level (distributed architecture, scalability), domain-level (DDD, bounded contexts), or application-level (component boundaries, tech stack). Users choose an interaction mode — guided (collaborative Q&A) or propose (architect analyzes requirements and presents options with trade-offs). Analyzes existing codebase, evaluates open-source alternatives, produces C4 diagrams (Mermaid) as mandatory output.

Interactive Decision Points

Decision 0: Design Scope (MANDATORY — do NOT skip)

**Question**: What are you designing?

You MUST ask this question before invoking any architect. Do NOT default to application scope. The answer determines WHICH agent to invoke.

**Options**: 1. **System / infrastructure** — distributed architecture, scalability, caching, load balancing, message queues → invokes @nw-system-designer 2. **Domain / bounded contexts** — DDD, aggregates, Event Modeling, event sourcing, context mapping → invokes @nw-ddd-architect 3. **Application / components** — component boundaries, hexagonal architecture, tech stack, ADRs → invokes @nw-solution-architect 4. **Full stack** — all three in sequence: system -> domain -> application → invokes all three agents sequentially

Decision 1: Interaction Mode

**Question**: How do you want to work?

**Options**: 1. **Guide me** — the architect asks questions, you make decisions together 2. **Propose** — the architect reads your requirements and proposes 2-3 options with trade-offs

Prior Wave Consultation

Before beginning DESIGN work, read SSOT and prior wave artifacts:

1. **SSOT** (if `docs/product/` exists):

• `docs/product/architecture/brief.md` — current architecture to extend (if exists)
• `docs/product/architecture/adr-*.md` — existing architectural decisions
• `docs/product/journeys/{name}.yaml` — journey schema for port identification

2. **DISCUSS** (primary input): Read from `docs/feature/{feature-id}/discuss/`:

• `wave-decisions.md` — decision summary
• `user-stories.md` — functional requirements, system constraints, and scope (includes AC per story)
• `story-map.md` — walking skeleton, release slicing, and priority rationale
• `outcome-kpis.md` — quality attributes informing architecture

3. **DISCOVER** (synthesis check only): Read `docs/feature/{feature-id}/discover/wave-decisions.md` — only if architecturally relevant

DISCUSS already synthesizes evidence into structured user stories. DESIGN reads SSOT architecture first (to extend, not recreate), then feature-level artifacts for the delta.

**READING ENFORCEMENT**: You MUST read every file listed in Prior Wave Consultation above using the Read tool before proceeding. After reading, output a confirmation checklist (`✓ {file}` for each read, `⊘ {file} (not found)` for missing). Do NOT skip files that exist — skipping causes architectural decisions disconnected from requirements.

After reading, check whether any DESIGN decisions would contradict DISCUSS requirements. Flag contradictions and resolve with user before proceeding. Example: DISCUSS requires "real-time updates" but DESIGN chooses batch processing — this must be resolved.

Document Update (Back-Propagation)

When DESIGN decisions change assumptions from prior waves: 1. Document the change in a `## Changed Assumptions` section at the end of the affected DESIGN artifact 2. Reference the original prior-wave document and quote the original assumption 3. State the new assumption and the rationale for the change 4. If architecture constraints require changes to user stories or acceptance criteria, note them in `docs/feature/{feature-id}/design/upstream-changes.md` for the product owner to review

Discovery Flow

Architecture decisions driven by quality attributes, not pattern shopping:

Step 1: Understand the Problem

Review JTBD artifacts from DISCUSS to understand which jobs the architecture must serve. Morgan asks: What are we building? For whom? Which quality attributes matter most? (scalability|maintainability|testability|time-to-market|fault tolerance|auditability)

Step 2: Understand Constraints

Morgan asks: Team size/experience? Timeline? Existing systems to integrate? Regulatory requirements? Operational maturity (CI/CD, monitoring)?

Step 3: Team Structure (Conway's Law)

Morgan asks: How many teams? Communication patterns? Does proposed architecture match org chart?

Step 3.5: Development Paradigm Selection

Morgan identifies primary language(s) from constraints, then applies:

• **FP-native** (Haskell|F#|Scala|Clojure|Elixir): recommend Functional
• **OOP-native** (Java|C#|Go): recommend OOP
• **Multi-paradigm** (TypeScript|Kotlin|Python|Rust|Swift): present both, let user choose based on team experience and domain fit

After confirmation, ask user permission to write paradigm to project CLAUDE.md:

• FP: `This project follows the **functional programming** paradigm. Use @nw-functional-software-crafter for implementation.`
• OOP: `This project follows the **object-oriented** paradigm. Use @nw-software-crafter for implementation.`

Default if user declines/unsure: OOP. User can override later.

Step 4: Recommend Architecture Based on Drivers

Recommend based on quality attribute priorities|constraints|paradigm from Steps 1-3.5. Default: modular monolith with dependency inversion (ports-and-adapters). Overrides require evidence.

If functional paradigm sel