Skip to content

ARCHITECTURE-PATTERNS — 10 Architectural Patterns

Status: live · Version: 1.0.0 · Camada: 19

Purpose

Catalog of architectural patterns the framework implements. Documenting them explicitly makes architecture conversations precise — "our pipeline is a Choreographed Saga" beats "pipeline of 7 steps".

The 10 patterns

1. Actor Model

  • 57 agents are actors with private state, communicating via capsules (messages)
  • Reference: each Layer-4 specialist
  • Files: docs/reference/registries/_agents-registry.yaml, AGENT-MANIFEST template

2. EDA (Event-Driven Architecture)

  • EVENT-BUS-SPEC (C13) decouples producers from consumers
  • All system actions emit typed events
  • Files: EVENT-BUS-SPEC.md, TRIGGER-CATALOG.md

3. Saga (Choreographed)

  • The 7-phase pipeline (C7) is a saga: each phase is a step; failures roll back via REFLEX-ENGINE
  • Files: PIPELINE-VALIDATION.md

4. Sidecar

  • PIXEL-AGENTS run alongside main flow, observing but not interfering
  • Files: PIXEL-AGENTS.md template

5. Bulkhead

  • CIRCUIT-BREAKER (C9) isolates failure per-agent
  • Files: CIRCUIT-BREAKER.md

6. Strangler Fig

  • Legacy migration pattern (DEPRECATED-SKILLS-REGISTRY) — incrementally replaces old
  • Files: DEPRECATED-SKILLS-REGISTRY.md, SKILL-VERSIONING.md

7. CQRS-light

  • Read paths (registries) separated from write paths (mutators) for WORLD-STATE
  • Files: WORLD-STATE.md, WORLD-STATE-CONSISTENCY.md

8. Hexagonal (Ports/Adapters)

  • TOOL-REGISTRY defines ports; agents adapt
  • Files: TOOL-REGISTRY.md

9. State Machine

  • Capsule lifecycle (proposed → executing → completed) is a state machine
  • Files: handoff-capsule.schema.json, PIPELINE-VALIDATION.md

10. Backpressure

  • Hormone signals (insulin) and TOKEN-BUDGET-PROTOCOL implement backpressure
  • Files: HORMONE-SIGNALS.md, TOKEN-BUDGET-PROTOCOL.md

Cross-pattern mapping

Actor Model ──────── EDA ─────── Event Bus
     │                │             │
     ▼                ▼             ▼
57 Agents       EVENT_CATALOG   38 PX Agents (Sidecar)
     │                │             │
     ▼                ▼             ▼
WORLD-STATE     Saga (Pipeline) Bulkhead (CBs)
     │                │             │
     ▼                ▼             ▼
Backpressure    Dead Letter     Health Check
(Baroreceptor)  Queue (HDR)     Trilogy

How to use this catalog

  1. Adding a new component: identify pattern it follows; document.
  2. Code review: verify code doesn't violate pattern (e.g., PX that mutates state = Sidecar violation).
  3. Explaining to stakeholders: precise vocabulary.
  4. Onboarding agents: first architectural reading.

Cross-references

  • BLUEPRINT (C1 template) — should reference applicable patterns
  • ADR (C2 template) — pattern choice typically deserves an ADR
  • PROJECT-STRUCTURE (C3 template) — implements patterns via folder layout
  • All major specs reference their pattern