Designing Systems

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:

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

ADR: [Decision Title]

Status

[Proposed | Accepted | Rejected | Deprecated | Superseded]

Context

[What is the issue we're addressing? What forces are at play?]

Decision

[What is the change we're proposing or have agreed to implement?]

Rationale

[Why is this the best choice among the alternatives?]

Alternatives Considered

Alternative 1: [Name]

• Pros: ...
• Cons: ...
• Why Not: ...

Alternative 2: [Name]

• Pros: ...
• Cons: ...
• Why Not: ...

Consequences

Positive

• [Benefit 1]
• [Benefit 2]

Negative

• [Trade-off 1]
• [Trade-off 2]

Risks

• [Risk 1]: [Mitigation]

References

• [Link to related documents]
• [Link to external resources]

System Design: [System Name]

Meta

Executive Summary

[2-3 sentences describing what this system does and why it's needed]

Architecture Overview

graph TB
    Client[Client App] --> API[API Gateway]
    API --> Auth[Auth Service]
    API --> Core[Core Service]
    Core --> DB[(Database)]
    Core --> Cache[(Redis)]

Key Decisions & Trade-offs

Components

[Component 1]

• Responsibility: [What it does]
• Technology: [Stack]
• Scaling: [How it scales]

[Component 2]

...

API Design

Endpoints

Data Model

CREATE TABLE resources (
  id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Non-Functional Requirements

Implementation Plan

1. [ ] Phase 1: Core service MVP 2. [ ] Phase 2: Authentication integration 3. [ ] Phase 3: Caching layer 4. [ ] Phase 4: Monitoring and alerting

Open Questions

• [ ] [Question 1]
• [ ] [Question 2]