architect

Designs system architecture for new features. Defines data flow, component boundaries, threading/concurrency model, and key design decisions. Use when making architecture decisions, adding new systems, or evaluating design patterns.

System Architecture

System Diagram

Before proposing architecture, map the current system. Create or update a diagram like:

┌──────────────────────────────────────┐
│           Entry Point / UI           │
│  (routes, views, controllers)        │
├──────────────────────────────────────┤
│          Business Logic              │
│  (services, domain models, rules)    │
├──────────┬───────────┬───────────────┤
│ Module A │ Module B  │   Module C    │
├──────────┴───────────┴───────────────┤
│          Data Layer                  │
│  (repositories, APIs, persistence)   │
├──────────────────────────────────────┤
│        Infrastructure                │
│  (DB, cache, queues, external APIs)  │
└──────────────────────────────────────┘

Adapt to the actual project structure. The goal is a single visual that shows where new code lives.

Concurrency Model

Document how the system handles concurrent operations:

  • Which thread/process owns which state?
  • How do components communicate? (queues, events, shared memory, atomics?)
  • Where are the synchronization boundaries?
  • What is the locking strategy?

Key Principles

  1. Single source of truth for each piece of state. Never duplicate authoritative data.
  2. Separation of concerns - each module has one job. UI doesn't contain business logic. Data layer doesn't know about presentation.
  3. Dependency direction - dependencies point inward (UI → Business Logic → Data). Never the reverse.
  4. Explicit boundaries - module interfaces are well-defined. Internal implementation is hidden.

Anti-Patterns to Reject

  • God objects that know about everything
  • Circular dependencies between modules
  • Business logic in UI/controller layer
  • Over-engineering (DI frameworks, abstractions for single implementations, repository pattern for trivial storage)
  • Premature optimization of architecture before understanding the problem

Design Decision Template

When proposing architectural changes:

DECISION: [what]
CONTEXT: [why this is needed]
OPTIONS CONSIDERED:
  1. [option] - pros / cons
  2. [option] - pros / cons
CHOSEN: [which and why]
TRADE-OFFS: [what we give up]
REVERSIBILITY: [easy / moderate / hard to change later]