# Architecture Design

> 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.

- Skill: `ahtishamshahzad/architecture-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ahtishamshahzad/architecture-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahtishamshahzad/architecture-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ahtishamshahzad (https://skillmd.com/u/ahtishamshahzad)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ahtishamshahzad/architecture-design

---


# 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

1. Read approved apps/stack + requirements.
2. Identify domains and boundaries.
3. Define data flow and contracts.
4. Decide cross-cutting approaches.
5. Record the architecture (Gate 3) in `../../projects/current/` / `../../knowledge/`.
6. 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

- [ ] Module/service boundaries defined.
- [ ] Data flow and ownership defined.
- [ ] Integration points + contracts identified.
- [ ] Cross-cutting concerns decided.
- [ ] Proportional to the request.
- [ ] Decisions + alternatives recorded (Gate 3).

## 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.