Goal
Decide how the system is split, where data lives, how parts talk to each other — and write down why.
Inputs → outputs
Inputs
- SRS and measurable NFRs
- Approved prototype
- Infrastructure constraints and running budget
Deliverables
- SDD / SAD: C4 diagrams (context, container, component), deployment view
- ERD + data dictionary
- OpenAPI 3.1 API spec
- ADR log
- Threat model + mitigations
Teams & roles
- Solution Architectureowns architecture, ADRs, design review
- Engineering (FE · BE · Mobile)detailed design, API contract
- Data & AIERD, data dictionary, migration strategy
- Application Security (AppSec)threat model and mitigations
- DevOps / SREdeployment view, operational constraints
- Client (Product Owner / sponsor)approves running cost, provides integration details
RACI matrix
R — does the work · A — accountable, final sign-off (exactly one A per activity) · C — consulted before · I — informed after.
| Activity | Arch | PM | Dev | QA | Sec | Ops | Infra | Data | Client |
|---|---|---|---|---|---|---|---|---|---|
| Architecture style & C4 diagrams | A | · | C | · | · | C | · | · | · |
| Database design (ERD, migrations) | A | · | R | · | · | · | · | R | · |
| API contract (OpenAPI) | A | · | R | C | · | · | · | · | · |
| Threat model (STRIDE) | R | · | C | · | A | · | · | · | · |
| ADRs & design review | A | I | C | · | C | · | · | · | · |
| Approve infrastructure & running cost | R | · | · | · | · | · | C | · | A |
Arch = Solution Architecture; PM = Project Management / Scrum Master; Dev = Engineering (FE · BE · Mobile); QA = Quality Assurance (QA/QC); Sec = Application Security (AppSec); Ops = DevOps / SRE; Infra = Infrastructure & Network; Data = Data & AI; Client = Client (Product Owner / sponsor)
Quality gate
Design review done; ERD and API contract frozen for the first sprint.
Entry criteria
- SRS approved
- NFRs are measurable
Exit criteria
- SDD has C4 levels 1–3 and a deployment view
- ERD, data dictionary and migration strategy complete
- OpenAPI for the first sprint frozen
- Threat-model mitigations are in the backlog
- Every hard-to-reverse decision has an ADR; design review minuted
Activities
- 1.Pick an architecture style (modular monolith, client–server, event-driven…) for the real scale, not the trend
- 2.Database design: ERD, normalisation, indexes, migration strategy
- 3.Write the API contract (OpenAPI) first so FE and BE can work in parallel
- 4.Threat-model sensitive data flows (STRIDE)
- 5.Record architecture decisions (ADRs) for anything hard to reverse
Checklist
Tick to self-review — 0/6. Ticks stay in this browser only and are not sent anywhere.
Document templates
Markdown (.md) files: open in any editor, or paste into Word / Google Docs. Each states its purpose, who fills it in and when.
Client involvement
- Confirm infrastructure constraints / monthly running cost
- Provide third-party integration details (sandbox keys, docs)
Tools
- PlantUML / Mermaid
- dbdiagram / DBeaver
- Swagger / Stoplight
- OWASP Threat Dragon
Reference standards
- ISO/IEC/IEEE 42010:2022
- Architecture description: viewpoints, views, stakeholders
- IEEE 1016-2009
- Software design description (SDD) structure
- OpenAPI Specification 3.1
- Machine-readable REST API description
- C4 model · ADR (M. Nygard)
- Four-level architecture diagrams + lightweight decision records
- STRIDE (Microsoft)
- Threat categories for threat modeling
Common pitfalls
- Microservices for a small system
- No ADRs → nobody remembers why a few months later
- APIs shaped by database tables instead of use cases
- Threat model done once and forgotten
Real example
cuongthai.com: AI calls are routed to models by TASK, not by module, and AI Code uses its own gateway. Every decision is recorded with its reason and measurement (cost inside the tool loop, which models really see images, which ignore token caps) — a living ADR that travels with the code.
Where to learn
Subjects and courses on cuongthai.com that teach this stage’s work.