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 the approved behavior scenarios (
../../system/GHERKIN_RULES.md), apps/stack, and requirements.
- Identify domains and boundaries from the behavior: every scenario's preconditions, failures, and edge cases need a home — an offline scenario demands local persistence, sync, retries, idempotency, and conflict handling; a duplicate-request scenario demands an idempotency mechanism.
- 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.4metadata:5 source: https://skillmd.com/skills/ahtishamshahzad/architecture-design6---78# Architecture Design910## Purpose1112Define 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.1314## When to Use1516- After Gate 2 (applications + stack approved), before phase/task generation.17- When a feature needs a design decision within an existing architecture.18- **Not** for a trivial change fully covered by existing patterns.1920## Inputs2122- Approved applications and stack (`../../projects/current/`).23- Requirement baseline and audit findings.2425## Discovery Questions2627- What are the core domains/bounded contexts?28- Which integrations (auth, payments, third-party APIs) are required?29- What are the consistency, availability, and scale expectations?30- What cross-cutting concerns need a single approach (auth, config, logging, errors)?3132## Responsibilities3334- Define **module/service boundaries** and responsibilities.35- Define **data flow** and ownership between modules/apps.36- Identify **integration points** and their contracts.37- Decide **cross-cutting concerns**: auth, configuration, error handling, logging.38- Keep the design **proportional** to the request.39- Feed `repository-architecture` for the on-disk layout.4041## Required Workflow42431. Read the approved behavior scenarios (`../../system/GHERKIN_RULES.md`), apps/stack, and requirements.442. Identify domains and boundaries **from the behavior**: every scenario's preconditions, failures, and edge cases need a home — an offline scenario demands local persistence, sync, retries, idempotency, and conflict handling; a duplicate-request scenario demands an idempotency mechanism.453. Define data flow and contracts.464. Decide cross-cutting approaches.475. Record the architecture (Gate 3) in `../../projects/current/` / `../../knowledge/`.486. Hand off to `repository-architecture` and phase generation.4950## Decision Rules5152- Boundaries follow domains and change-rate, not convenience.53- Prefer the simplest architecture that meets the requirements; add complexity only when justified.54- Contracts between apps/modules are explicit before parallel work begins.55- Security-relevant flows (auth, PII, payments) get first-class treatment (`security-review`).5657## Rules5859- Consistent with the approved stack — no new stack decisions here.60- Record decisions and rejected alternatives (the "why").61- No code; this is design.6263## Anti-Patterns6465- Over-engineering (microservices/event buses for a small app).66- Under-defining contracts, then parallelizing into conflicts.67- Architecture that contradicts the approved stack.6869## Validation Checklist7071- [ ] Module/service boundaries defined.72- [ ] Data flow and ownership defined.73- [ ] Integration points + contracts identified.74- [ ] Cross-cutting concerns decided.75- [ ] Proportional to the request.76- [ ] Decisions + alternatives recorded (Gate 3).7778## Definition of Done7980A recorded architecture consistent with the approved stack — boundaries, data flow, integrations, and cross-cutting concerns — sufficient to generate phases, tasks, and the repository layout.8182## Related Skills8384`stack-recommendation`, `repository-architecture`, `task-planning`, `security-review`, `testing-strategy`, `project-orchestrator`.8586## Related Knowledge8788`../../knowledge/` (architecture decision records, domain model).8990## Related References9192`../../references/<architecture-topic>/` when a pattern needs grounding.9394## Context Loading Guidance9596- **Requires:** approved apps/stack, requirement baseline.97- **Does not require:** full source, unrelated references, implementation skills.98- **May load:** `repository-architecture`, `security-review` for sensitive flows.99- **Stop when:** the architecture is recorded and passes Gate 3.100101## Token Efficiency Guidance102103Work from summaries of apps/stack/requirements. Capture the design as concise decisions + a diagram-in-text; avoid restating stack rationale already recorded.