Architecture Overview
How to Use
- Every section links to a document that contains the authoritative decision or design for that concern.
- Every significant decision must link to at least one ADR.
- Keep this README as the single navigation entry point for the architecture folder.
- Add new sections only when a domain concern is not yet covered.
1. Core Architecture
Files in core/:
- Architecture Solution Design: System context, selected pattern, component design, data flow, and high-level trade-offs.
- Architecture Styles: Architecture style evaluation, bounded context map, and evolution strategy.
- Technology Stack: Component-level technology choices with rationale and trade-offs.
2. Diagrams
Files in diagrams/: architecture diagrams embedded as Mermaid in markdown — C4 models, flows, deployment, security.
- Sequence Diagrams: Key interaction flows with detailed explanations.
- For large or complex diagrams you may also keep source files (e.g.
.drawio) next to the exported images.
3. Database
Files in database/:
- Database Domain Overview: Database architecture domain with schema design guidance and best-practice checklists.
- Database Design: Entities, relationships, ERD, constraints, and access patterns.
4. Interfaces and Data Contracts
Files in contracts/:
- Contract Design Standards: Naming, versioning, error handling, and format conventions for the project's contract type(s) — REST, CLI, gRPC, events, or a library/SDK.
- Contract Catalog: Catalog of interfaces/operations and shared schemas.
5. Security
Files in security/:
- Security Architecture: Authentication, authorization, data protection, OWASP controls, and secrets management.
- Threat Model: STRIDE-based threat enumeration, risk matrix, and mitigation plan.
6. Deployment and Operations
Files in ops/:
- Deployment Architecture: Platform model, compute, networking, scaling, and disaster recovery.
- CI/CD Pipeline: Branching strategy, pipeline stages, migration strategy, rollback, and secrets handling.
- Monitoring and Observability: SLIs, dashboards, alerting rules, and release health checks.
Decision Records
Decisions live outside this folder — architecture documents link to them instead of restating rationale.
- ADRs: Architecture Decision Records with context, decision, and trade-offs.
- Start with the ADR Template for all new decisions.
7. Architecture Domain → Requirements Coverage
This matrix confirms every Must-priority requirement is addressed by at least one architecture domain. Update whenever ADRs or requirements change.
| Architecture Domain | Must FR(s) Covered | Must NFR(s) Covered | Key ADR(s) |
|---|---|---|---|
| Core Architecture | [FR-xxx] | [NFR-Xnn] | [ADR-xxx] |
| Database | [FR-xxx] | [NFR-Xnn] | [ADR-xxx] |
| Interfaces and Data Contracts | [FR-xxx] | [NFR-Xnn] | [ADR-xxx] |
| Security | [FR-xxx] | [NFR-Xnn] | [ADR-xxx] |
| Deployment and Operations | [FR-xxx] | [NFR-Xnn] | [ADR-xxx] |
Rule: Any Must FR or NFR with no domain coverage is an architecture gap — create an ADR before phase sign-off.