System Design Thinking

Frameworks for thinking about architecture before writing code. Design decisions are expensive to change—think first, code second.

Core Philosophy

"The goal of software architecture is to minimize the human resources required to build and maintain the required system." — Robert C. Martin

Architecture is about:

1. Managing complexity - Breaking big problems into smaller ones
2. Enabling change - Making the system adaptable
3. Deferring decisions - Keeping options open as long as possible
4. Communicating intent - Making the system understandable

The Design Thinking Process

1. Understand Before Designing

See rules/start-with-requirements.md

Never design without understanding:

2. Identify the Core Problem

Before jumping to solutions, articulate:

We need to [capability]
For [users/systems]
So that [business value]
Constrained by [limitations]

Example:

We need to process payment transactions
For 10,000 concurrent users
So that customers can complete purchases
Constrained by:
- 99.99% availability requirement
- PCI compliance
- <200ms response time
- Existing PostgreSQL infrastructure

3. Explore the Solution Space

Don't commit to the first idea. Generate options:

4. Make and Document Decisions

See references/adr-template.md

Every significant decision needs:

• Context - Why are we making this decision?
• Options - What did we consider?
• Decision - What did we choose?
• Consequences - What are the trade-offs?

Trade-off Analysis

See references/trade-off-analysis.md for detailed frameworks.

The Iron Triangle

You can optimize for two, not all three:

        Speed
         /\
        /  \
       /    \
      /______\
   Scope    Quality

CAP Theorem

Distributed systems can guarantee only two of three:

In practice: Network partitions happen, so choose CP or AP:

• CP (Consistency + Partition tolerance): Banking, inventory
• AP (Availability + Partition tolerance): Social feeds, caching

Common Trade-offs

Architecture Patterns Quick Reference

See references/architecture-styles.md for detailed comparisons.

When to Use What

Start Simple

See rules/prefer-simple-architecture.md

Start here ──► Monolith ──► Modular Monolith ──► Microservices
                  │
                  └── Most projects never need to leave

The Monolith First rule: Unless you have proven scale requirements, start with a well-structured monolith.

System Decomposition

Finding Boundaries

See rules/define-boundaries-first.md

Good boundaries have:

• High cohesion - Related things together
• Low coupling - Minimal dependencies across boundaries
• Clear contracts - Well-defined interfaces
• Independent deployability - Can change without coordinating

Decomposition Strategies

Domain-Driven Design (Quick Reference)

Data Architecture

See references/data-architecture.md

Data Flow First

Before designing components, understand:

1. What data exists? - Entities, relationships, volumes
2. How does it flow? - Sources, transformations, destinations
3. Who owns it? - Single source of truth for each entity
4. How fresh must it be? - Real-time, near-real-time, batch

Storage Decisions

Data Consistency Patterns

Integration Patterns

See references/integration-patterns.md

Sync vs Async

When to Use What

Need immediate response? ──► Sync (REST/gRPC)
                │
                No
                │
                ▼
Can caller continue without result? ──► Async (Queue/Event)
                │
                No
                │
                ▼
Use async with callback/webhook

Scalability Thinking

See references/scalability-patterns.md

Scaling Strategies

Performance Budget

Before optimizing, set targets:

Page load: < 2s
API response: < 200ms (p99)
Background job: < 30s
Availability: 99.9% (8.76 hours downtime/year)

Design for Operations

See rules/consider-operations.md

Operability Checklist

Every system needs:

• Health checks - Is it running? Is it healthy?
• Logging - What happened? (Structured, searchable)
• Metrics - How is it performing? (Latency, errors, throughput)
• Alerting - When does it need attention?
• Deployment - How do we release changes safely?
• Rollback - How do we undo bad releases?
• Disaster recovery - What if everything fails?

The "3 AM Test"

Ask: "If this breaks at 3 AM, can someone fix it?"

• Are errors clear and actionable?
• Are runbooks documented?
• Can issues be diagnosed from logs/metrics?
• Can it be rolled back quickly?

Quick Reference Checklist

Before Designing

• Requirements understood (functional + non-functional)
• Constraints identified (budget, timeline, skills, compliance)
• Success criteria defined (measurable)
• Stakeholders aligned

During Design

• Multiple options explored
• Trade-offs explicitly stated
• Simplest solution that works chosen
• Boundaries clearly defined
• Data flow mapped
• Failure modes considered

After Design

• Decision documented (ADR)
• Operability addressed
• Migration path identified (if replacing existing)
• Team understands and agrees

Rules

Atomic decision heuristics. Each rule follows: Context → Heuristic → Why.

Reference Files

Deep dives on specific topics.