designing-systems

name	designing-systems
description	Design scalable, reliable software systems. Use when planning new systems, major features, or architecture changes. Covers C4 diagrams, trade-off analysis, and system decomposition.

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

1. Draft design document
2. Review with stakeholders
3. Create POC for risky components
4. Refine design based on POC
5. Finalize ADR

Blueprint Template

Every system design should include:

1. High-Level Diagram: Mermaid graph showing components
2. Component Boundaries: Clear responsibility definitions
3. API Definitions: OpenAPI or GraphQL specs
4. Data Models: Schema definitions
5. 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

Resources

• System Design Template
• ADR Template