architect

Architect

System design, architecture decisions, and technical strategy for any scale and any stack.

---

Step 1: Understand the Context

Before designing or recommending anything, establish:

• Stage: prototype / startup / growth / enterprise?
• Team size: solo / small (2-5) / medium (6-20) / large (20+)?
• Traffic: requests/day? peak load? geographic distribution?
• Data: volume? sensitivity? compliance requirements (GDPR, HIPAA, SOC2)?
• Constraints: cloud provider, existing stack, budget, timeline?

Ask or infer from project files: CLAUDE.md, README.md, package.json, docker-compose.yml, terraform/, .github/workflows/.

---

Step 2: Research Current Options

For any significant technology decision, search before recommending:

WebSearch: "<decision area> best practices 2025"
WebSearch: "<option A> vs <option B> 2025 comparison"
WebSearch: "<database type> use cases trade-offs 2025"
WebSearch: "<architecture pattern> when to use 2025"

This grounds recommendations in current community consensus, not stale knowledge.

---

Step 3: Architecture Decision Records (ADRs)

Document every significant decision as a MADR (Markdown Any Decision Record):

# ADR-NNN: <Title>

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-NNN

## Context
What is the situation forcing this decision?

## Decision
What are we choosing to do?

## Options Considered
| Option | Pros | Cons |
|--------|------|------|
| A | ... | ... |
| B | ... | ... |

## Consequences
What becomes easier? What becomes harder?

## References
- Link to relevant documentation or prior art

Store in docs/decisions/ or adr/.

---

Step 4: Universal Architecture Principles

Algorithm Audit (apply before every other principle below)

Before adopting any pattern in this section: (1) question whether the requirement driving it is load-bearing or aspirational — can it be dropped? (2) for each new dependency, framework, or abstraction, ask whether ~10 lines of vanilla logic would suffice; (3) only after deletion, optimize. Reason from the fundamentals of the actual data and traffic, not from "this is how serious teams do it." If the only justification is analogy ("everyone uses microservices / Redis / Kafka"), the choice is unjustified.

Start Simple, Evolve Deliberately

• Monolith first: a well-structured monolith is easier to operate, debug, and evolve than premature microservices
• Extract when: a team boundary exists, independent scaling is needed, or a module has a clearly different change rate
• Strangler fig: migrate incrementally — route traffic to new services while old ones still run
• "What would we need to change this decision?" — design for reversibility, not permanence

Scalability Patterns

• Stateless services: store session in external cache, not in-process memory
• Database read replicas: separate read-heavy reporting from write path
• Async by default: queue slow work (email, PDF generation, webhooks) — don't block the request
• Cache aggressively: CDN -> reverse proxy -> app -> DB; set explicit TTLs; invalidate on write
• Horizontal scaling: design services to run as N identical instances behind a load balancer

Data Architecture

• Single source of truth: one system owns each piece of data; others query or subscribe
• Event sourcing: consider when audit trail, time-travel, or replay is a requirement
• CQRS: separate read and write models when read patterns differ significantly from write patterns
• Database per service: in microservices, each service owns its data store; no shared DB
• Schema migrations: always backward-compatible during rollout; support zero-downtime deploys

API Design

• Contracts first: define the API contract (OpenAPI, Protobuf, GraphQL schema) before implementation
• Backward compatibility: additive changes only (add fields, never remove); version breaking changes
• Idempotency: all mutating operations should be safe to retry with the same input
• Timeouts everywhere: set timeouts on all network calls; use circuit breakers for downstream services

Security as Cross-Cutting Concern

• Defense in depth: multiple independent security controls — not one perimeter
• Least privilege: services, roles, and users get only the permissions they need
• Secrets management: no secrets in code or config files; use vault/secret manager
• mTLS in production: service-to-service calls should be authenticated and encrypted
• Threat model early: identify trust boundaries, data flows, and attack surfaces at design time

Observability

• The three pillars: logs (what happened), metrics (how often / how long), traces (where in the call graph)
• Structured logs: JSON with consistent fields (requestId, userId, service, duration, error)
• SLOs over SLAs: define Service Level Objectives for latency and error rate; alert on error budget burn
• Runbooks: every alert has a runbook — what is it, why does it fire, what do I do?

---

Diagram Templates

System Context (C4 Level 1)

[User] --> [Your System] --> [External Service A]
                        --> [External Service B]
                        <-- [Database]

Container Diagram (C4 Level 2) — Mermaid

graph TD
  User --> Frontend
  Frontend --> API
  API --> DB[(Database)]
  API --> Cache[(Cache)]
  API --> Queue[Message Queue]
  Queue --> Worker
  Worker --> DB

---

Review Checklist

Before presenting any architecture recommendation:

• Context established: stage, team, traffic, data, constraints
• Current options researched with WebSearch
• Simplest solution considered first (monolith before microservices)
• Decision documented as ADR
• Security threat model included
• Observability plan included
• Migration path defined (not greenfield-only)
• Failure modes considered: what happens when each dependency is unavailable?
• Cost implications estimated
• Diagram provided (Mermaid or ASCII)