Architecture Design
Purpose
Define the system's shape: modules and their boundaries, how data flows, where integrations sit, and how cross-cutting concerns are handled — consistent with the approved applications and stack. Satisfies Gate 3.
When to Use
- After Gate 2 (applications + stack approved), before phase/task generation.
- When a feature needs a design decision within an existing architecture.
- Not for a trivial change fully covered by existing patterns.
Inputs
- Approved applications and stack (
../../projects/current/).
- Requirement baseline and audit findings.
Discovery Questions
- What are the core domains/bounded contexts?
- Which integrations (auth, payments, third-party APIs) are required?
- What are the consistency, availability, and scale expectations?
- What cross-cutting concerns need a single approach (auth, config, logging, errors)?
Responsibilities
- Define module/service boundaries and responsibilities.
- Define data flow and ownership between modules/apps.
- Identify integration points and their contracts.
- Decide cross-cutting concerns: auth, configuration, error handling, logging.
- Keep the design proportional to the request.
- Feed
repository-architecture for the on-disk layout.
Required Workflow
- Read approved apps/stack + requirements.
- Identify domains and boundaries.
- Define data flow and contracts.
- Decide cross-cutting approaches.
- Record the architecture (Gate 3) in
../../projects/current/ / ../../knowledge/.
- Hand off to
repository-architecture and phase generation.
Decision Rules
- Boundaries follow domains and change-rate, not convenience.
- Prefer the simplest architecture that meets the requirements; add complexity only when justified.
- Contracts between apps/modules are explicit before parallel work begins.
- Security-relevant flows (auth, PII, payments) get first-class treatment (
security-review).
Rules
- Consistent with the approved stack — no new stack decisions here.
- Record decisions and rejected alternatives (the "why").
- No code; this is design.
Anti-Patterns
- Over-engineering (microservices/event buses for a small app).
- Under-defining contracts, then parallelizing into conflicts.
- Architecture that contradicts the approved stack.
Validation Checklist
Definition of Done
A recorded architecture consistent with the approved stack — boundaries, data flow, integrations, and cross-cutting concerns — sufficient to generate phases, tasks, and the repository layout.
Related Skills
stack-recommendation, repository-architecture, task-planning, security-review, testing-strategy, project-orchestrator.
Related Knowledge
../../knowledge/ (architecture decision records, domain model).
Related References
../../references/<architecture-topic>/ when a pattern needs grounding.
Context Loading Guidance
- Requires: approved apps/stack, requirement baseline.
- Does not require: full source, unrelated references, implementation skills.
- May load:
repository-architecture, security-review for sensitive flows.
- Stop when: the architecture is recorded and passes Gate 3.
Token Efficiency Guidance
Work from summaries of apps/stack/requirements. Capture the design as concise decisions + a diagram-in-text; avoid restating stack rationale already recorded.
1---2name: architecture-design3description: Use after the stack is approved to define module boundaries, data flow, integration points, and cross-cutting concerns (auth, config, error handling). Produces the architecture that phases and tasks are generated from. Proportional to the request.4---56# Architecture Design78## Purpose910Define the system's shape: modules and their boundaries, how data flows, where integrations sit, and how cross-cutting concerns are handled — consistent with the approved applications and stack. Satisfies Gate 3.1112## When to Use1314- After Gate 2 (applications + stack approved), before phase/task generation.15- When a feature needs a design decision within an existing architecture.16- **Not** for a trivial change fully covered by existing patterns.1718## Inputs1920- Approved applications and stack (`../../projects/current/`).21- Requirement baseline and audit findings.2223## Discovery Questions2425- What are the core domains/bounded contexts?26- Which integrations (auth, payments, third-party APIs) are required?27- What are the consistency, availability, and scale expectations?28- What cross-cutting concerns need a single approach (auth, config, logging, errors)?2930## Responsibilities3132- Define **module/service boundaries** and responsibilities.33- Define **data flow** and ownership between modules/apps.34- Identify **integration points** and their contracts.35- Decide **cross-cutting concerns**: auth, configuration, error handling, logging.36- Keep the design **proportional** to the request.37- Feed `repository-architecture` for the on-disk layout.3839## Required Workflow40411. Read approved apps/stack + requirements.422. Identify domains and boundaries.433. Define data flow and contracts.444. Decide cross-cutting approaches.455. Record the architecture (Gate 3) in `../../projects/current/` / `../../knowledge/`.466. Hand off to `repository-architecture` and phase generation.4748## Decision Rules4950- Boundaries follow domains and change-rate, not convenience.51- Prefer the simplest architecture that meets the requirements; add complexity only when justified.52- Contracts between apps/modules are explicit before parallel work begins.53- Security-relevant flows (auth, PII, payments) get first-class treatment (`security-review`).5455## Rules5657- Consistent with the approved stack — no new stack decisions here.58- Record decisions and rejected alternatives (the "why").59- No code; this is design.6061## Anti-Patterns6263- Over-engineering (microservices/event buses for a small app).64- Under-defining contracts, then parallelizing into conflicts.65- Architecture that contradicts the approved stack.6667## Validation Checklist6869- [ ] Module/service boundaries defined.70- [ ] Data flow and ownership defined.71- [ ] Integration points + contracts identified.72- [ ] Cross-cutting concerns decided.73- [ ] Proportional to the request.74- [ ] Decisions + alternatives recorded (Gate 3).7576## Definition of Done7778A recorded architecture consistent with the approved stack — boundaries, data flow, integrations, and cross-cutting concerns — sufficient to generate phases, tasks, and the repository layout.7980## Related Skills8182`stack-recommendation`, `repository-architecture`, `task-planning`, `security-review`, `testing-strategy`, `project-orchestrator`.8384## Related Knowledge8586`../../knowledge/` (architecture decision records, domain model).8788## Related References8990`../../references/<architecture-topic>/` when a pattern needs grounding.9192## Context Loading Guidance9394- **Requires:** approved apps/stack, requirement baseline.95- **Does not require:** full source, unrelated references, implementation skills.96- **May load:** `repository-architecture`, `security-review` for sensitive flows.97- **Stop when:** the architecture is recorded and passes Gate 3.9899## Token Efficiency Guidance100101Work from summaries of apps/stack/requirements. Capture the design as concise decisions + a diagram-in-text; avoid restating stack rationale already recorded.
ahtishamshahzad