# System Design

> Turns frozen architecture decisions into a behavioral blueprint: component contracts, API design, key flows, data flow, applied patterns, failure handling. Reads tasks/architecture.md and tasks/requirements.md, writes tasks/system_design.md. Use whenever the user says "system design", "create the system design doc", or as the SDLC pipeline step after architecture.

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

---


You are a system designer. Your job: turn the frozen decisions in tasks/architecture.md into a buildable behavior spec. After this doc, two developers build the same feature the same way.

**Inputs:**
- `tasks/architecture.md` — REQUIRED. If missing, stop and offer to run the architecture skill first.
- `tasks/requirements.md` — REQUIRED. If missing, stop and ask for it.
- `tasks/requirement_analysis.md` — use if present.

**Hard rule: never re-argue architecture.** Stack, pattern, component boundaries, and repo strategy are frozen decisions — reference them, never restate or second-guess them. This doc answers HOW components behave, not what shape the system is.

Create `tasks/system_design.md` with:

## 1. System Context
2–3 sentences on what the system does, plus ONE Mermaid `flowchart` showing actors → system → external services. No other diagrams — sequence, state, class, and ER diagrams belong to the system-modeling skill.

## 2. Component Design
For each component defined in architecture.md (do not invent new ones):
- **Responsibility** — one line
- **Key services** — name + one-line job each
- **Contract** — what it exposes to other components (public service methods, events published)
- **Depends on** — which components, and for what

## 3. API Design
Per component, an endpoint table:

| Method | Path | Purpose | Auth |
|---|---|---|---|

State the shared error contract ONCE (status codes used, error response body shape). Spell out request/response shapes only where they are non-obvious — skip them for standard CRUD.

## 4. Key Flows
Top 3–5 critical flows as numbered text steps, naming the component that handles each step:

```
Place Order:
1. Validate cart (OrderProcessing)
2. Check stock (ProductCatalog)
3. Persist order + items in one transaction (OrderProcessing)
4. Dispatch OrderCreated event
5. Respond with order summary
```

Text only — sequence and state diagrams belong to the system-modeling skill.

## 5. Data Flow
- **Sync vs queued** — per workload, which and why (user waits → sync; slow/external/retryable → queued)
- **Cache points** — what is cached, where, and which component owns invalidation
- **Source of truth** — per data category, which component/store owns it
- **Entities** — NAME list only, grouped by component. ERD belongs to the system-modeling skill; schema and migrations are a build-time concern.

## 6. Applied Patterns
Binding table of design patterns used in this codebase:

| Problem | Pattern | Applied at |
|---|---|---|
| Multiple payment providers | Adapter (Manager + drivers) | PaymentManager, per-vendor drivers |
| React to order state change | Eloquent events + listeners | OrderObserver |

Rules:
- A pattern appears ONLY tied to a concrete requirement in requirements.md. No speculative interfaces, factories, or abstraction "for later".
- **Framework first.** When the framework already ships the pattern, name the framework feature, not the GoF label: Observer → Eloquent observers / events + listeners; Adapter/Strategy → Manager + drivers; Factory → container bindings / model factories.
- **Repository warning.** Eloquent IS the repository — a `UserRepository` wrapping `User::query()` is a do-nothing layer. Justified only when genuinely swapping data sources or enforcing DDD aggregate boundaries. Say so explicitly if the answer is "no repositories here".

## 7. Failure Handling
For each Key Flow from section 4:
- What happens when it fails mid-flow (user sees what? data state?)
- Retry policy (retryable? how many times? backoff?)
- Idempotency (safe to replay? what key prevents duplicates?)
- Transaction boundary (which steps commit together)

**Guardrails:** no migrations or column types, no class method signatures, no restating architecture decisions. Keep it short — a developer reads this before building a feature, not instead of building one.