System Design

# System Design

> Walk the user through system design with The Method. The **architect drives** the entire process. The Product Manager supplies raw business input and ratifies decisions — they do not own volatility analysis, decomposition, or the architecture. This command produces a validated, layered, volatility-based architecture captured as **typed artifacts committed to `.aiarch/state/project.json`** (git-as-DB); the Structurizr DSL and any markdown are render-on-read of those typed slots, never the source of truth.

archistrator is a single Go-server repo; canonical state is the typed JSON aggregate in `.aiarch/state/project.json`. Each Phase-1 artifact is produced as a typed model and committed into its slot, then staged for the human review gate (`StageArtifactForReview` → `CommitArtifact`/`RejectArtifact`), and the phase advances via `AdvancePhase`. There are no `methodpoc/designs/<product>/*.md` files.

**Skill reference:** Invoke `the-method` skill before starting. This command orchestrates the system-design sub-skills in canonical order:

1. [[the-method-business-alignment]]
2. [[the-method-requirements-analysis]]
3. [[the-method-volatility-identification]]
4. [[the-method-core-use-cases]]
5. [[the-method-architecture]] (merged decomposition + DSL + call-chain validation)
6. [[the-method-operational-concepts]]
7. [[the-method-system-design-standard-check]]

## Division of labor (do not get this wrong)

Per Löwy, the architect owns system design. The PM is a collaborator on customer-facing inputs and a ratifier on business-alignment outputs — nothing more.

| Activity | Architect | Product Manager |
|---|---|---|
| Vision / Objectives / Mission | **Drives drafting** (ch. 5) | Supplies raw business context. Ratifies. *Cannot own objectives* (ch. 5: "you must not allow the engineering or marketing people to own the conversation") |
| Glossary | **Owns** (Who/What/How/Where, ch. 3) | Supplies domain terms from customer language |
| Scrub solutions-masquerading-as-requirements | **Drives the dialogue** (ch. 2) | Supplies raw requirement text |
| Identify volatilities | **Owns entirely.** Two axes, design factoring, longevity, design-for-competitors (ch. 2) | Supplies customer/business context as input |
| Volatilities List | **Owns** | (input only) |
| Core use cases | **Decides** which are core (ch. 4) | Co-discovers with architect; resolves customer conflicts |
| Layered decomposition | **Owns** (Four Questions, cardinality, naming, layering rules — ch. 3) | (none) |
| Operational concepts | **Owns** (ch. 5) | Provides business justification when asked |
| Call chain validation | **Owns** (ch. 4) | (none) |

## Usage

/system-design

## Prerequisites

The project's research corpus in `.aiarch/state/project.json` must hold at least one research input (competitor analysis, customer interviews, business briefs, market analysis, prior system docs). If not, stop and tell the user to populate it.

## Workflow

### Step 1 — Business alignment (Architect drives; PM ratifies)

Invoke [[the-method-business-alignment]] via `system-architect`:

> Read the research corpus in `.aiarch/state/project.json`. Drive the
> Vision → Objectives → Mission chain (Löwy ch. 5, "Business Alignment"):
>
> 1. **Vision** — distill to ONE sentence. "Terse and explicit, like a legal statement." Example (TradeMe): *"A platform for building applications to support the TradeMe marketplace."*
> 2. **Business Objectives** — numbered list, business perspective only. NO technology objectives. NO specific feature requirements. NO marketing language. (Ch. 5: "you must not allow the engineering or marketing people to own the conversation.")
> 3. **Mission Statement** — how you will achieve the vision/objectives, expressed in terms of **components** not features. Example (TradeMe): *"Design and build a collection of software components that the development team can assemble into applications and features."*
>
> Maintain **bidirectional traceability**: every objective must trace to vision; mission must support all objectives.
>
> Produce the typed `MissionStatement` model and commit it to
> `.aiarch/state/project.json` → `.mission`.

Then ask the **Product Manager** (or the user directly) to **ratify** — does this capture the business intent? Iterate until ratified.

### Step 2 — Requirements analysis: glossary + scrubbed requirements (Architect owns)

Invoke [[the-method-requirements-analysis]] via `system-architect`. This single skill covers BOTH the glossary (Four Questions) and the scrubbing of solutions-masquerading-as-requirements.

> Build the glossary by answering the Four Questions across the domain
> (ch. 3 "What's in a Name", ch. 5 "TradeMe Glossary"):
>
> - **Who** uses or interacts with the system?
> - **What** does the system do (workflows, use cases)?
> - **How** does it perform business activities?
> - **Where** does it store state?
>
> Every distinct domain noun/verb gets a one-line definition. Use customer
> language. Produce the typed `Glossary` model and commit it to
> `.aiarch/state/project.json` → `.glossary`.
>
> Then, for each requirement statement, ask Löwy's interrogation (ch. 2,
> "Solutions Masquerading As Requirements"):
>
>   1. Is this a solution or a true requirement?
>   2. Are there other possible solutions?
>   3. If so, what is the real requirement and the underlying volatility?
>   4. Is the volatility itself a true requirement, or another solution?
>
> Examples from the book:
>   - "Send email" → strip to "notify users" (transport is volatility)
>   - "Cooking" → strip to "feeding" → "well-being"
>   - "We need a queue" → strip to "user must receive events in order"
>
> Produce the typed `ScrubbedRequirements` model (before/after for each
> item) and commit it to `.aiarch/state/project.json` → `.scrubbedRequirements`.
> The architect proposes; the PM ratifies because they know the customer's
> actual need.

PM reviews glossary for missing or misnamed terms and rati