Designing Systems
Workflows
- Requirements: Gather functional and non-functional requirements
- Diagrams: Create C4 diagrams (Context, Container)
- Data: Define data model and storage strategy
- API: Define interfaces and contracts
- Risks: Identify single points of failure
- Document: Save to
./artifacts/adr_[topic].md
Feedback Loops
- Draft design document
- Review with stakeholders
- Create POC for risky components
- Refine design based on POC
- Finalize ADR
Blueprint Template
Every system design should include:
- High-Level Diagram: Mermaid graph showing components
- Component Boundaries: Clear responsibility definitions
- API Definitions: OpenAPI or GraphQL specs
- Data Models: Schema definitions
- Trade-off Analysis: Rationale for key decisions
C4 Model Levels
Level 1: Context
Who uses the system? What external systems does it interact with?
Level 2: Container
What are the major deployable units? (APIs, databases, queues)
Level 3: Component
What are the major building blocks within each container?
Level 4: Code
Class/function level (usually not needed in architecture docs)
Trade-off Analysis
For major decisions, explicitly document:
| Decision | Option A | Option B |
|---|---|---|
| Pros | ... | ... |
| Cons | ... | ... |
| When to Choose | ... | ... |
Non-Functional Requirements
Always consider:
- Scalability: Expected load, growth rate
- Availability: SLA targets, failure modes
- Latency: P50, P95, P99 requirements
- Security: Authentication, authorization, data protection
- Cost: Infrastructure, operational overhead