architecture-design

name

architecture-design

description

Use when the user needs to make system-level structural decisions: service decomposition, module boundaries, technology selection, data storage choices, API contract design, or deployment topology. Can be used AFTER brainstorming to formalize decisions, or ALONGSIDE domain skills (rm-hero-architect, ros2-development) which provide domain knowledge while this skill provides structural framework. NOT for open-ended idea exploration alone (use brainstorming) or domain algorithm design alone (use domain skills). Triggers on 'design the architecture', 'how should we structure this', 'what tech stack', 'service boundaries', or ADR documentation needs.

Architecture Design

Systematic architecture design grounded in code facts — not textbook theory. Forces multi-option comparison, quantified NFR analysis, and ADR documentation. Prevents over-engineering and resume-driven development.

Announce at start: "Using the architecture-design skill."

Scope — How This Skill Relates to Others

This skill is a structural framework, not a knowledge silo. It works best when combined with domain skills that provide specialized knowledge.

Complementary Usage Patterns

User asks open-ended question ("How to improve X?")
  └→ brainstorming (explores problem space)
       └→ brainstorming loads domain skill as knowledge source
            e.g., rm-hero-architect provides ballistics/EKF/perception knowledge
       └→ If structural decisions emerge → architecture-design formalizes them

User asks structural question ("How should we organize the ROS2 nodes?")
  └→ architecture-design (structural framework)
       └→ Loads embedded-systems-guide.md (ROS2 section) for domain patterns
       └→ Domain skills (rm-hero-architect, ros2-development) can be consulted for specifics

Routing Table

User Intent	This Skill?	Relationship
"Design the architecture for X"	Yes	Primary — may consult domain skills for specifics
"How should we structure this system?"	Yes	Primary
"What database/framework/protocol?"	Yes	Primary
"What are some ideas for improving X?"	No	brainstorming is primary — domain skills feed knowledge
"How to improve auto-aim accuracy?"	No	brainstorming + rm-hero-architect for domain knowledge
"Review this code"	No	code-reviewer
"Write the implementation plan"	No	writing-plans — decisions already made
Brainstorming identified a structural decision	Yes	Called as follow-up after brainstorming

PROBE → DESIGN → VALIDATE → EMIT

digraph flow {
    rankdir=TB; node [shape=box, style=rounded];
    probe [label="PROBE\nUnderstand context"];
    design [label="DESIGN\nGenerate & compare options"];
    validate [label="VALIDATE\nStress-test decisions"];
    emit [label="EMIT\nProduce deliverables"];
    probe -> design -> validate -> emit;
    validate -> design [label="gaps found" style=dashed];
}

---

Phase 1: PROBE — Understand Before Designing

Never design in a vacuum. Gather facts before generating options.

Step 0: Codebase Scan (for existing projects)

Analyze the project to understand what already exists. This skill is fully self-contained — no external tools required.

Scan these in order (stop early if you have enough context):

1. Build manifest — Read package.json / go.mod / Cargo.toml / CMakeLists.txt / pyproject.toml / pom.xml → tech stack, dependencies, language
2. Directory structure — Read top-level dirs (src/, lib/, services/, apps/, packages/) → module boundaries, monorepo detection
3. Deployment config — Read .github/workflows/, Dockerfile, docker-compose.yml, k8s/, serverless.yml → deployment model
4. README / docs — Read README.md, docs/architecture/ → stated architecture, existing ADRs
5. Existing analysis (optional bonus) — If .nexus-map/INDEX.md exists, read it for pre-computed systems, dependencies, and hotspots. This file is produced by the nexus-mapper skill but is NOT required — skip if absent.

Output a Context Summary:

• Project type: web-backend | web-frontend | fullstack | mobile | embedded | robotics | data-pipeline | cli | monorepo | greenfield
• Tech stack: languages, frameworks, build tools
• Current architecture: identified patterns, pain points
• Deployment model: cloud/edge/on-prem, containerized, serverless

Step 1: Requirements Gathering

Collect from user — but infer first, ask second. Use Step 0 findings to pre-fill what you can, state your assumptions explicitly, then only ask about critical gaps:

• Functional scope: core features, explicit non-goals
• Data profile: volume, growth rate, read/write ratio
• Performance budget: latency targets (P50/P99), throughput, concurrency
• Team constraints: size, expertise, ops capability
• Timeline: MVP deadline, iteration cadence

GATE: Critical info still missing after inference → STOP, ask only for the gaps you cannot infer.

Step 2: Constraint Classification

Type	Examples	Negotiable?
Hard	Compliance (GDPR, HIPAA), existing system compatibility, deployment platform	No
Soft	Tech preferences, timeline, budget	Yes — document trade-offs

GATE: Requirements incomplete → STOP, ask for missing items.

---

Phase 2: DESIGN — Generate Options

Step 3: Load Domain-Specific Guidance

Based on project type from Step 0, load the relevant reference:

Project Type	Load
web-backend	pattern-catalog.md + api-design-guide.md + data-modeling-guide.md
web-frontend	frontend-architecture-guide.md
fullstack	pattern-catalog.md + api-design-guide.md + data-modeling-guide.md + frontend-architecture-guide.md
mobile	mobile-architecture-guide.md + api-design-guide.md
embedded	embedded-systems-guide.md + api-design-guide.md (for CAN/MQTT protocols)
robotics	embedded-systems-guide.md (ROS2 section) + api-design-guide.md (DDS/ROS2 topics) + pattern-catalog.md
data-pipeline	pattern-catalog.md + data-modeling-guide.md
cli	pattern-catalog.md (CLI patterns section)
monorepo	Identify sub-project types per workspace, load guides for each. Monorepo-level checklist: (1) workspace boundaries — each package has clear public API, (2) dependency graph — no circular deps between packages, enforce with tooling, (3) affected-target CI — only build/test changed packages + dependents, (4) ownership — CODEOWNERS per package, (5) versioning — independent (per-package) vs lockstep, (6) shared config — linting/tsconfig/build at root, overrides per package
greenfield	All relevant based on user description

Always load: nfr-checklist.md (select domain-appropriate checks)

Step 4: Generate Candidate Architectures

Produce at least 2 options. Each must include:

• Architecture pattern name + rationale
• Component breakdown with responsibilities
• Key technology choices with justification
• Deployment topology sketch
• Estimated complexity (services, dependencies, new-to-team tech)

GATE: Only 1 option → STOP, generate at least one alternative.

Step 5: Trade-off Analysis

Compare options using nfr-checklist.md. Every claim must be quantified:

• ❌ "High performance" → ✅ "P99 < 50ms at 1000 QPS"
• ❌ "Scalable" → ✅ "Horizontal scale to 10 instances, stateless workers"
• ❌ "Simple" → ✅ "1 service, 2 external deps, team has 3yr experience"

---

Phase 3: VALIDATE — Stress-Test

Step 6: Evidence Gate

Before recording any decision, verify claims have backing:

Decision Type	Required Evidence
One-way door (DB, public API, core arch)	POC, benchmark, or production data from similar system
Two-way door (internal impl, tooling)	Quick spike or team experience is sufficient
Performance claim	Must reference benchmark numbers, not assumptions
"We'll need this at scale"	Must show current trajectory data, not speculation

GATE: One-way door decision without POC/benchmark/reference data → STOP, gather evidence first.

Step 7: Anti-Pattern Scan

Anti-Pattern	Signal	Fix
Over-engineering	Simple needs, complex solution	YAGNI — start with simplest option
Distributed monolith	Microservices sharing DB or sync chains	Re-examine boundaries or stay monolith
Resume-driven	Selection reason is "want to learn"	Selection must serve requirements
Ops-blind	No deployment/monitoring plan	Architecture must include ops story
Speculative scaling	"Might need this someday" driving design	Design for current needs, mark extension points

Step 8: Record Decisions

Use decision-framework.md template. One ADR per key decision.

GATE: No ADR produced → STOP, decisions must be documented before implementation. GATE: NFR not quantified → STOP, "high performance" is not a metric.

---

Phase 4: EMIT — Produce Deliverables

Scale-Appropriate Outputs

Scale	Required	Optional
Small (solo/hackathon)	ADR + module diagram	—
Medium (team/startup)	ADR + system context (C4 L1) + module dependencies	Container diagram, API contracts
Large (enterprise)	ADR + full C4 (L1-L2) + NFR scorecard + module deps	Data model, API contracts, deployment diagram
Refactor/Migration	All of above + migration plan	Strangler fig phases, traffic cutover strategy, rollback points, staged acceptance criteria

Output path: docs/architecture/

docs/architecture/
├── ADR-001-<decision-title>.md     # Always required
├── system-context.md               # C4 Level 1 (medium+)
├── container-diagram.md            # C4 Level 2 (large)
├── module-dependencies.md          # Module dependency graph
├── api-contracts/                  # API definitions (if applicable)
├── data-model.md                   # Data model (if applicable)
└── migration-plan.md               # Migration/refactor plan (if applicable)

---

Resources

Load on demand based on project type:

• decision-framework.md — ADR templates and decision methodology
• pattern-catalog.md — Backend architecture pattern selection matrix
• nfr-checklist.md — Non-functional requirements checklist (multi-domain)
• api-design-guide.md — API contract design (REST, gRPC, GraphQL, event-driven)
• data-modeling-guide.md — Storage selection, indexing, caching, migration
• frontend-architecture-guide.md — Frontend architecture (rendering, state, micro-frontends)
• mobile-architecture-guide.md — Mobile architecture (cross-platform, offline-first, performance)
• embedded-systems-guide.md — Embedded/real-time systems (RTOS, HAL, protocols, safety)