system-design（系统设计）

System Design

Overview

Select the simplest architecture that satisfies requirements. Introduce complexity only when evidence demands it.

Core principle: Every structural decision must be driven by a current requirement, not a speculative future one.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO STRUCTURAL COMPLEXITY WITHOUT AN ESTABLISHED REQUIREMENT

If you cannot point to a concrete, current requirement that demands the complexity, choose the simpler option.

When to Use

Always before:

• Selecting a database
• Designing an API
• Organizing a new project
• Introducing a caching layer
• Adding message queues or event systems
• Choosing authentication strategy
• Deciding on monolith vs services

Especially when:

• "We might need to scale" (might = do not add complexity)
• "What if we need X later?" (later = not now)
• Multiple valid approaches exist

The Entry Protocol

BEFORE making ANY structural decision:

1. IDENTIFY: What concrete requirement drives this choice?
2. COMPARE: What is the simplest option that satisfies it?
3. JUSTIFY: Why is anything more complex necessary?
   - If no justification: Use the simple option
   - If justified: Record the requirement driving complexity
4. DECIDE: Choose. Document. Move on.

Skip any step = over-engineering

Decision Frameworks

Monolith vs Services

digraph structure_decision {
    start [label="New project?", shape=diamond];
    team [label="Multiple teams\nown separate\ndomains?", shape=diamond];
    scale [label="Components need\nindependent\nscaling NOW?", shape=diamond];
    deploy [label="Components need\nindependent\ndeploy cycles?", shape=diamond];
    mono [label="MONOLITH\nSimplest path", shape=box, style=filled, fillcolor="#ccffcc"];
    services [label="SERVICES\nEstablished need", shape=box, style=filled, fillcolor="#ffcccc"];

    start -> mono [label="yes"];
    start -> team [label="existing"];
    team -> services [label="yes"];
    team -> scale [label="no"];
    scale -> services [label="yes"];
    scale -> deploy [label="no"];
    deploy -> services [label="yes"];
    deploy -> mono [label="no"];
}

Default: Monolith. Extract services only when a specific component demonstrates it requires independent scaling or deployment.

Database Selection

Default: PostgreSQL. It handles JSON, full-text search, and most workloads adequately. Switch only when PostgreSQL demonstrably cannot meet a requirement.

API Design

Default: REST. Adopt GraphQL only when clients genuinely need flexible queries. Adopt gRPC only for internal services where throughput is measured and proven insufficient with REST.

Authentication Strategy

Default: Session-based auth with httpOnly cookies. JWTs are not inherently more secure. Use them only when stateless authentication across domains is a concrete requirement.

Caching Strategy

BEFORE introducing a cache:

1. Is there actually a measured performance problem?
2. Can the database query be optimized instead?
3. Is the data read-heavy with infrequent writes?

Only if YES to 1, NO to 2, YES to 3: Introduce cache.

Default: No cache. Optimize queries first. Introduce caching only after measuring a bottleneck.

Event-Driven Architecture

BEFORE introducing a message queue:

1. Do you need asynchronous processing? (Email delivery, image processing)
2. Do producers and consumers need to scale independently?
3. Do you need guaranteed delivery across service boundaries?

If NO to all: Direct function calls are sufficient.

Default: Direct function calls. Queues add operational complexity. Introduce them only when async processing or decoupling is an established requirement.

File Organization Conventions

Organize by capability, not by layer:

# AVOID: organized by layer
src/
  controllers/
  models/
  services/
  validators/

# PREFER: organized by capability
src/
  users/
    user.controller.ts
    user.service.ts
    user.model.ts
    user.test.ts
  orders/
    order.controller.ts
    order.service.ts
    order.model.ts
    order.test.ts
  shared/
    database.ts
    auth.middleware.ts

Capability-based organization keeps related code together. Changing one capability touches one directory.

Cognitive Traps

Guardrails - HALT and Simplify

• Adding infrastructure for "future scale"
• Selecting technology because it is "modern" or "industry standard"
• Architecture diagram has more than 5 components for an MVP
• Multiple databases without distinct access patterns
• Message queues for synchronous workflows
• Microservices with a single team
• "Flexible" schemas without concrete varying fields
• Caching before measuring

All of these mean: Simplify. Use the boring, proven option.

Integration

Complements:

• godmode:performance-tuning — When structural choices affect performance
• godmode:security-protocol — Auth patterns and data flow security
• godmode:project-bootstrap — File organization and initial setup
• godmode:task-planning — Structural decisions during planning phase

The Bottom Line

Simplest architecture that works > "best" architecture that might be needed

PostgreSQL. REST. Monolith. Sessions. No cache. Direct calls. Start there. Introduce complexity only when you have evidence it is necessary.