system-architecture git:20260703.877e272A

Immutable. This exact content is served forever at /api/v1/blob/7a5540826ec3123a.

---
name: system-architecture
description: "Use when designing a system, choosing an architecture pattern, making a technology decision, or doing capacity/scalability planning — BEFORE drilling into framework-specific mechanics. A lean MAP over three reference docs: pattern selection (monolith → modular monolith → microservices → event-driven → CQRS → event sourcing → hexagonal → clean → API gateway, with trade-offs), the how-to system-design workflows (system-design-interview approach, capacity planning, API design, DB schema design, scalability assessment, migration planning), and the technology-choice frameworks (database, caching, message queue, auth, frontend framework, cloud provider, API style). Trigger on: 'design the system', 'choose an architecture pattern', 'which pattern fits', 'tech decision', 'SQL or NoSQL', 'REST vs GraphQL vs gRPC', 'capacity/scalability planning', 'plan the migration'. This is general system-design knowledge; for Phoenix bounded-context/Ecto/authz/Oban specifics use the architecture-phx skill."
---

TASKLANG
TYPE SKILL

IDENTITY "System Architecture"
  > General-purpose system-design knowledge for the planning step that comes
  > BEFORE technology-specific mechanics: pick the right architecture PATTERN,
  > make the load-bearing TECHNOLOGY decisions, and run the system-design
  > WORKFLOWS (capacity, API, schema, scalability, migration). This skill is a
  > lean MAP — the substance lives in three reference docs under references/.
  > Read the map, then open the one reference that matches the question.

!!! References FIRST — this SKILL.md only routes; the answers live in references/.
!!! This is technology-AGNOSTIC system design. For Phoenix/Ecto/Oban/can?/3
!!! specifics (bounded contexts, schema tables, the verify gate), use the
!!! architecture-phx skill — system-architecture supports the PLANNING that
!!! precedes those mechanics.

---

## When to use this skill

KNOWLEDGE
  USE_WHEN
    - "Choosing an architecture pattern for a new system or a milestone (and weighing its trade-offs)."
    - "Making a technology decision — database, cache, message queue, auth, frontend framework, cloud provider, API style."
    - "Running a system-design workflow — capacity planning, API design, schema design, scalability assessment, migration planning."
    - "Doing the PLAN-FIRST step of a design: settle pattern + data/access model + boundaries before drilling into framework mechanics."
  NOT_FOR
    - "Phoenix-specific bounded-context / Ecto schema / Oban / can?/3 policy design — that is the architecture-phx skill."
    - "Writing or verifying implementation code — this skill informs design decisions, it does not produce code."

---

## Core knowledge (the map)

KNOWLEDGE
  METHOD
    - "PLAN before mechanics: a design starts by choosing a PATTERN, settling the DATA + ACCESS model, and naming the BOUNDARIES — then drills into technology-specific implementation."
    - "Every pattern and technology choice is a TRADE-OFF, not a default. Start simple (a monolith / modular monolith) and adopt complexity (microservices, CQRS, event sourcing) only when a concrete force — scale, team autonomy, independent deploy, audit/replay — demands it."
    - "Right-size the decision to the requirements you actually have: estimate scale FIRST (capacity-planning workflow), then let the numbers drive the pattern and the technology choices."
    - "Make decisions with a framework, not a hunch: each technology choice in tech_decision_guide.md carries a decision matrix + a 'when to use each' so the choice is defensible."

---

## References (open the one that matches the question)

> Three reference docs. Read the map above, then open exactly one.

MAP references
  "references/architecture_patterns.md"     -> PATTERN SELECTION. Open when choosing/comparing an architecture pattern. Monolith, Modular Monolith, Microservices, Event-Driven, CQRS, Event Sourcing, Hexagonal, Clean Architecture, API Gateway — each with its forces, trade-offs, and a pattern-selection quick reference.
  "references/system_design_workflows.md"   -> HOW-TO WORKFLOWS. Open when you need a step-by-step design procedure: the system-design-interview approach, capacity planning, API design, database schema design, scalability assessment, and migration planning.
  "references/tech_decision_guide.md"        -> TECHNOLOGY CHOICE. Open when picking a specific technology: database (SQL vs NoSQL + type), caching strategy, message queue, authentication strategy (JWT vs sessions, OAuth flows), frontend framework (SSR vs SPA vs SSG), cloud provider, and API style (REST vs GraphQL vs gRPC).

---

## How it fits the squad

KNOWLEDGE
  FITS
    - "Supporting knowledge for the architect-phx agent's DESIGN mode (phase 2): consulted during the PLAN-FIRST step (pattern selection + tech decisions + the system-design workflows) BEFORE the Phoenix-specific technical sub-steps."
    - "Does NOT replace architecture-phx: that skill owns the Phoenix bounded-context/Ecto/Oban/can?/3 policy mechanics and the verify gate; this skill informs the architectural choices that feed them."