architect

name

architect

description

Design scalable system architectures and make technology decisions. Covers microservices vs monolith analysis, event-driven architecture, CQRS, domain-driven design, system design methodology, scalability planning, technology selection frameworks, architecture decision records, C4 diagrams, and infrastructure patterns. Use when designing systems, making architectural decisions, or planning for scale.

System Architecture & Design

Architecture Decision Process

Step 1: Understand Requirements

Functional: What does it DO?
Non-Functional:
  - Expected users (100? 10K? 1M+?)
  - Latency requirements (< 100ms? < 1s?)
  - Availability target (99.9%? 99.99%?)
  - Data sensitivity (PII? Financial? Public?)
  - Compliance (GDPR, SOC2, HIPAA?)
  - Budget constraints

Step 2: Architecture Selection

Pattern	Best When	Avoid When
Monolith	Team < 10, MVP, simple domain	> 50 developers, complex domain
Modular Monolith	Growing team, separation needed	Need independent deployment
Microservices	Large teams, independent scaling	Small team, simple domain
Serverless	Event-driven, variable load	Consistent high-throughput
Event-Driven	Async workflows, loose coupling	Strong consistency needed

Step 3: Document Decision (ADR)

# ADR-001: Choose Modular Monolith Architecture

## Status: Accepted

## Context
We have a team of 5 engineers building a SaaS dashboard.
Expected users: 10K in year 1, 100K in year 3.

## Decision
Start with a modular monolith with clear domain boundaries.

## Consequences
- Faster development velocity initially
- Can extract services later if needed
- Must maintain module boundaries with linting rules
- Single deployment simplifies DevOps

Architecture Patterns

Modular Monolith

src/
├── modules/
│   ├── auth/                # Auth domain
│   │   ├── routes.ts
│   │   ├── service.ts
│   │   ├── repository.ts
│   │   └── types.ts
│   ├── billing/             # Billing domain
│   │   ├── routes.ts
│   │   ├── service.ts
│   │   └── events.ts        # Publishes billing events
│   └── notifications/       # Notifications domain
│       ├── service.ts
│       └── listeners.ts     # Subscribes to billing events
├── shared/                  # Shared kernel
│   ├── database.ts
│   ├── event-bus.ts
│   └── types.ts
└── index.ts

Rule: Modules communicate through events or shared interfaces — NEVER direct imports of another module's internals.

Event-Driven Architecture

// Event bus (in-process for monolith)
type EventHandler = (data: unknown) => Promise<void>;

class EventBus {
  private handlers = new Map<string, EventHandler[]>();

  on(event: string, handler: EventHandler) {
    const existing = this.handlers.get(event) || [];
    this.handlers.set(event, [...existing, handler]);
  }

  async emit(event: string, data: unknown) {
    const handlers = this.handlers.get(event) || [];
    await Promise.allSettled(handlers.map((h) => h(data)));
  }
}

// Usage
eventBus.on("user.created", async (data) => {
  await sendWelcomeEmail(data.email);
  await createDefaultWorkspace(data.userId);
  await trackAnalytics("signup", data);
});

await eventBus.emit("user.created", { userId: user.id, email: user.email });

CQRS (Command Query Responsibility Segregation)

// Commands (writes) — go through domain logic
class CreateOrderCommand {
  constructor(public userId: string, public items: OrderItem[]) {}
}

async function handleCreateOrder(cmd: CreateOrderCommand) {
  const order = OrderAggregate.create(cmd.userId, cmd.items);
  await orderRepository.save(order);
  await eventBus.emit("order.created", order.toEvent());
}

// Queries (reads) — optimized read models
async function getOrderSummary(userId: string) {
  return db.query(`
    SELECT o.id, o.total, o.status, COUNT(oi.id) as item_count
    FROM orders o JOIN order_items oi ON oi.order_id = o.id
    WHERE o.user_id = $1 GROUP BY o.id ORDER BY o.created_at DESC
  `, [userId]);
}

Scalability Patterns

Horizontal Scaling Checklist

- [ ] Stateless application servers (no in-memory session state)
- [ ] Database connection pooling
- [ ] Centralized session store (Redis)
- [ ] Shared file storage (S3, not local disk)
- [ ] Load balancer with health checks
- [ ] Background job queue (BullMQ, Celery)
- [ ] CDN for static assets
- [ ] Database read replicas for read-heavy workloads

Caching Layers

Browser Cache → CDN → Application Cache (Redis) → Database
   (hours)      (min)        (seconds)           (source of truth)

Database Scaling

1. Optimize queries (indexes, query plans)     → handles 10x load
2. Read replicas                                → handles 50x reads
3. Connection pooling (PgBouncer)              → handles 100x connections
4. Application-level caching                    → handles 100x reads
5. Sharding (last resort)                       → handles 1000x data

System Design Template

When asked to design a system, follow this structure:

1. Clarify requirements (functional + non-functional)
2. Estimate scale (users, requests/sec, storage)
3. Define API contract (endpoints, request/response)
4. Design data model (entities, relationships)
5. Draw high-level architecture (components, data flow)
6. Deep dive into critical components
7. Address bottlenecks and failure points
8. Discuss trade-offs and alternatives

C4 Diagram Levels

Level 1: System Context — How the system fits in the world
Level 2: Container — Major technology choices (web app, API, database)
Level 3: Component — Key components within each container
Level 4: Code — Class/function level (only for critical parts)

Rules

• Start simple, add complexity only when proven necessary
• Choose boring technology for critical infrastructure
• Design for the next 10x, not 100x — you'll rewrite by then
• Every cross-service call is a potential failure point
• Prefer async communication between services
• Document ALL architectural decisions in ADRs