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

| Requirement | Select | Rationale | |-------------|--------|-----------| | Structured data, relationships, transactions | PostgreSQL | ACID guarantees, mature, covers 90% of use cases | | Document-oriented, genuinely variable schema per record | MongoDB | Only when schema truly differs per document | | Key-value, caching, session storage | Redis | In-memory speed, built-in TTL | | Full-text search at volume | Elasticsearch | Purpose-built for search workloads | | Time-series data (metrics, logs) | TimescaleDB / InfluxDB | Optimized for time-indexed writes | | Graph traversal is the primary query model | Neo4j | Only when traversal IS the product | | Embedded, zero-config, single-user | SQLite | Simplest possible, no server needed |

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

API Design

| Context | Select | Rationale | |---------|--------|-----------| | CRUD operations, public-facing API | REST | Universal, cacheable, well-understood | | Complex nested data, client-controlled shape | GraphQL | Eliminates over/under-fetching | | Internal service-to-service, high throughput | gRPC | Binary protocol, generated stubs, streaming | | Real-time bidirectional communication | WebSockets | Persistent connection, low latency | | Simple webhooks, event notification | REST callbacks | Stateless, easy to troubleshoot |

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

| Context | Select | Rationale | |---------|--------|-----------| | Standard web application | Session-based (cookies) | Simple, secure, server-controlled revocation | | SPA + API on different origins | JWT (short-lived) + refresh tokens | Stateless API auth across domains | | Third-party login | OAuth 2.0 / OIDC | Delegated authentication standard | | Machine-to-machine | API keys + HMAC | Simple, auditable | | Multi-tenant SaaS | OIDC + tenant-scoped tokens | Isolation per tenant |

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.

| Layer | Mechanism | Use When | |-------|-----------|----------| | Application | In-memory (LRU) | Single instance, small dataset | | Distributed | Redis / Memcached | Multi-instance, shared state | | HTTP | CDN / reverse proxy | Static assets, public pages | | Database | Query cache / materialized views | Expensive aggregations |

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.

| Need | Mechanism | Rationale | |------|-----------|-----------| | Simple task queue | Redis + BullMQ / Celery | Lightweight, familiar | | Event streaming, replay | Kafka | High throughput, log-based | | Cloud-native messaging | SQS / Cloud Pub/Sub | Managed, serverless | | Complex routing | RabbitMQ | Flexible routing, mature |

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

| Rationalization | Truth | |-----------------|-------| | "We might need microservices later" | Extract when needed. Monolith-first is faster to build and debug. | | "NoSQL is more flexible" | PostgreSQL handles JSON. Schema flexibility usually means schema confusion. | | "GraphQL is the modern choice" | REST is simpler for CRUD. Modern does not mean appropriate. | | "JWTs are more secure" | JWTs are harder to revoke. Sessions are simpler and server-controlled. | | "We need a cache for performance" | Have you optimized your queries? Measure first. | | "Event-driven is more scalable" | Direct calls are simpler. Scaling concerns are future concerns. | | "This architecture handles future growth" | The future is unpredictable. Solve current problems. |

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NoobyGains
• Source: NoobyGains/godmode
• License: MIT

Install and usage instructions live in the source repository linked above.