design-architecture

name	design-architecture
description	Phase 2 system architecture — define components, boundaries, data flow, and stack, recording the choice as an ADR with a trade-off matrix plus a machine-readable Stack block. Always research the current latest LTS/stable versions before deciding; pin to them. Use when: designing a new system, choosing a stack/framework/version, defining component boundaries, recording an architecture decision.

Input: docs/requirements.md. Output: docs/design/architecture.md.

Delegate craft depth to the expert. For component/boundary design, scalability patterns, and ADR authoring, load the vendored architecture-designer (also feeds design-detailed); see ../../resources/expert-skills-map.md. This skill keeps the trade-off-matrix + ADR gate.

One-Liner

Pick the architecture by comparing options against the requirements in a trade-off matrix, research the current latest LTS version of each chosen technology, then record the decision as an ADR plus a machine-readable Stack block — so the why and the exact versions survive, not just the what.

Core Philosophy

An unrecorded architecture decision gets re-litigated every time someone new reads the code. Compare real options against the actual NFRs; don't default to the trendiest stack — and don't pick versions from memory. Persona sets how much is surfaced (../../resources/persona-mode.md); defaults and version rules live in ../../resources/stack-defaults.md.

Workflow

Phase 1 — Components & flow

Define components + responsibilities, the boundaries between them, and the data flow. Gate: every requirement maps to a component that owns it.

Phase 2 — Choose the stack (trade-off matrix)

List 1–2 viable options; score against the requirements/NFRs.

• Non-Technical: take the conventional default for the app type from the default-stack table in stack-defaults.md (Rule 1), choose it, and log the rationale — do not ask.
• Developer: present the default + one alternative as the matrix and get approval.

Gate (Developer): user approved the choice. Non-Technical: a conventional default is chosen and logged (not asked).

Phase 2.5 — Research the version (latest LTS — REQUIRED, do this before recording)

Delegate to design-stack-research: it makes one web-research call per chosen technology, reads the official source, and writes the dedicated artifact docs/design/stack-versions.md (version + channel + fetched source URL + as-of date). Then pin the Stack block below FROM that artifact — copy its researched versions, do not recall them. If the runtime has no web access, design-stack-research STOPs and asks the user. Gate: docs/design/stack-versions.md exists with a researched version + source URL for every chosen technology, and the Stack block pins match it.

Phase 3 — Record the ADR + machine-readable Stack block

Write the decision + rationale + rejected alternatives and the Stack block to docs/design/architecture.md. The Stack block is the single machine-readable source of truth that plan-skeleton / plan-tasks / dev-* read (Rule 3) and the stack-decision-gate enforces. Gate: the ADR names what was chosen, why, and what was rejected; the Stack block names language + pinned versions + the LTS/research marker, with no placeholders.

Output contract

## Trade-off matrix
| Option | Fit to NFRs | Complexity | Cost | Team familiarity | Verdict |
|---|---|---|---|---|---|
| A: <stack> | … | … | … | … | chosen |
| B: <stack> | … | … | … | … | rejected: <reason> |

## ADR-001: <decision title>
- Status: accepted
- Context: <forces from requirements/NFRs>
- Decision: <what we chose>
- Consequences: <trade-offs accepted, follow-ups>
- Rejected: <option B> because <reason>

## Stack (machine-readable)
<!-- Pinned to latest LTS/stable; versions researched from official sources, not recalled. -->
- source_dir: <system-name>/   # app scaffolds into this subfolder (slug of the system name), NOT the repo root
- language: TypeScript
- runtime: Node.js 22.x (LTS "Jod"; verified current as of <date>, source nodejs.org/about/releases)
- framework: Next.js 15.x
- database: PostgreSQL 17
- package-manager: pnpm 9.x
- test-runner: Vitest 2.x
- convention: resources/conventions/typescript-node.md   # or: expert  when no conventions file
- lts-research: 

Handoff

Feeds design-database / design-api / design-detailed. The Stack block's convention: line resolves the craft source per stack-defaults.md Rule 2: a ../../resources/conventions/<lang>.md guide when one exists, else the mapped vendored expert. plan-skeleton pins manifests to the researched versions.