/architecting-software

name: architecting-software
description: Designs software architecture from a confirmed PRD. Use when a PRD exists and architecture must be designed before implementation, when writing ADRs, choosing an architecture style, or selecting technology and databases.

Architecting Software

Translates a confirmed PRD ("what to build") into system structure ("how to build it") — systematically, driver-first, without the documented failure modes of AI-generated architecture.

**Position:** managing-product (PRD.md) → architecting-software (ARCHITECTURE.md + ADRs) → decomposing-work (ROADMAP.md).

**Inputs:** a confirmed PRD.md; team size and composition (if absent and not inferable, flag for human input before Step 3 — it is an architectural driver); technology constraints from the PRD; existing systems to integrate with, or "greenfield".

**Outputs:** `ARCHITECTURE.md` in the project root (codemap-centric structure per `references/architecture-template.md`); when complexity warrants, one ADR per significant decision in `docs/decisions/NNNN-title.md` (MADR minimal format per `references/adr-template.md`).

**Not covered:** requirements gathering (managing-product), task decomposition (downstream), code generation, CI/CD design, detailed API specification.

Scale-Adaptive Depth

Same process at every tier; only output depth differs. Calibrate to the project — do not produce a 200-line architecture document for a 3-file bug fix. When in doubt, start light and add detail only where it prevents downstream ambiguity.

| Tier | ARCHITECTURE.md depth | ADRs | |------|----------------------|------| | **Quick** | 10-20 lines. Overview + key decisions only. Skip codemap if the project is navigable directly. | None | | **Standard** | Codemap + key decisions. Component boundaries and primary patterns. | Only for genuinely significant decisions | | **Thorough** | Full template — overview, codemap, cross-cutting concerns, invariants, key decisions, dependencies, open questions | One per significant decision |

Workflow

Step 1: Extract Requirements into Three Buckets

Sort every PRD requirement — select no patterns yet:

• **Functional** — what the system must do. Drives component responsibilities; rarely determines structure alone.
• **Quality attributes** — how well it must perform. Look in success criteria, constraints, acceptance criteria, performance/security statements. Translate vague statements: "fast" → "P95 under X ms for the [action] workflow"; "secure" → what is protected, from whom, under what threat model; "scales" → what load, over what timeframe.
• **Constraints** — budget, timeline, team skills, technology mandates, regulatory requirements, existing systems.

Log ambiguous requirements as open questions for human resolution before proceeding.

Step 2: Identify and Rank Architectural Drivers

Find the 3–7 requirements that force structural decisions: anything that affects many components, creates irreconcilable conflict with another requirement, cannot be met with standard patterns without deliberate choice, or carries significant business risk if unmet.

**Scale calibration first:**

| Signal | Simple | Moderate | Complex | |---|---|---|---| | User types | 1 | 2 | 3+ | | External integrations | 0–1 | 2–3 | 4+ | | Explicit quality attribute requirements | None | 1–2 | 3+ | | Team size | 1–5 | 6–20 | 20+ | | Compliance requirements | None | Light | Regulated |

Simple → focused ARCHITECTURE.md, ADRs only for genuinely non-obvious decisions. Moderate → ADRs for meaningful trade-offs. Complex → full documentation, ADR per significant decision.

**Rank drivers** by business impact if unmet and difficulty of satisfying given other constraints; primary drivers are high on both. Document the ranked list with brief justification before Step 3.

Step 3: Make Structural Decisions in Constraint Order

Select a pattern for each of five dimensions, in sequence — each decision constrains the next. Every selection must trace to a named driver; if no driver justifies the more complex option, the simpler default wins.

3a. Deployment Model

| Signal | Serverless | Containers/VMs | |---|---|---| | Traffic pattern | Variable, spiky | Predictable, sustained | | Request duration | Short (under 15 min) | Any, including long-running | | Cold start tolerance | Acceptable | Low latency required always | | Ops maturity | Low — managed infra preferred | Medium–high | | Cost model preference | Pay-per-request (cheap at low scale) | Provisioned compute (cheap at high scale) | | Vendor lock-in tolerance | High | Low |

**Default:** containers for sustained workloads; serverless for event-driven background jobs. Most production systems blend both.

3b. Deployment Topology

| Signal | Monolith | Modular Monolith | Microservices | |---|---|---|---| | Team size | 1–5 | 5–50 | 50+ | | Domain clarity | Unknown or emerging | Moderately understood | Well-understood, stable bounded contexts | | Scaling requirements | Uniform, modest | Mostly uniform | Highly variable per domain | | Operational maturity | Low | Medium | High — mature CI/CD, observability | | Data isolation requirement | Low | Medium | High — compliance or ownership |

**Default: modular monolith.** Move to microservices only on organisational signals: deployment coordination is a bottleneck, teams step on each other's code, or domains have dramatically differing scaling needs. Microservices are an organisational scaling pattern first — never speculative.

**Conway's Law check:** state what team structure this architecture requires; if it conflicts with known team constraints, revise the structure.

3c. Internal Code Organisation

Structure inside a service or monolith — independent of deployment topology.

| Signal | Layered | Hexagonal | Clean | |---|---|---|---| | Project complexity | Simple–medium | Medium–complex | Complex | | Team experience | Beginner–intermediate | Intermediate–advanced | Advanced | | Expected lifesp