Architecture¶

High-level map of the framework. Pair this with the specs for the deep dives.

Mental model¶

┌───────────────────────────────────────────────────────────────────────────┐
│                              CONSTITUTION                                  │
│  21 absolute rules (Rule 35 = Spec-Driven Development) + 12 contextual    │
│  Enforced at every pipeline run, every memory write, every skill call.    │
└───────────────────────────────────────────────────────────────────────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        ▼                           ▼                           ▼
┌──────────────┐           ┌──────────────┐           ┌──────────────┐
│  GOVERNANCE  │           │   RUNTIME    │           │   CONTENT    │
│ _framework/  │           │     src/     │           │   <area>/    │
│              │           │              │           │              │
│ specs (122)  │           │ 13 modules   │           │ 684 SKILLs   │
│ templates(44)│           │ B-N (live)   │           │ 39 areas     │
│ contracts (5)│           │ A (docs)     │           │ 64 sub-areas │
│ registries   │           │              │           │              │
└──────────────┘           └──────────────┘           └──────────────┘

Layered architecture (Camadas 1-19)¶

The framework is organized into 19 conceptual layers. Each layer either has a template (governance), a spec (contract), and/or a runtime module (src/).

#	Camada	Status	Runtime path
1	Strategic	template	—
2	Decision (ADRs/RFCs)	template	—
3	Planning (BLUEPRINT/PRD/STRUCTURE)	template	—
4	Execution	template	—
5	Knowledge	template	—
6	Operational	template	—
7	Pipeline	runtime ✅	`src/pipeline/`
8	AI Infra	runtime ✅	`src/ai/`
9	Privacy + Metrics	runtime ✅	`src/privacy/`, `src/ai/metrics.py`
10	Meta-Learning + Skills	runtime ✅	`src/meta_learning/`, `src/skills/`
11	Agent Expansion	runtime ✅	`src/agent_expansion/`
12	Autonomy	runtime ✅	`src/autonomy/`
13	Event-driven	spec	(see EVENT-BUS-SPEC.md)
14	Growth	runtime ✅	`src/growth/`
15	Body Systems	runtime ✅	`src/body/`
16	Anti-Obsolescence	runtime ✅	`src/anti_obsolescence/`
17	Regulatory	runtime ✅	`src/regulatory/`
18	Cognitive	runtime ✅	`src/cognitive/`
19	Scalability + Lifecycle	runtime ✅	`src/scalability/`, `src/growth/lifecycle.py`

The 7-phase pipeline (Camada 7)¶

Every capsule (unit of work) flows through 7 phases:

0 RECEPTION       Validate capsule integrity, deadline, budget, locks.
1 REALITY_ANCHOR  Confirm all referenced artifacts exist (UBT-000).
2 PLANNING        Verify spec is approved (Rule 35 — SDD).
3 GATES           Run 21 absolute constitutional rules.
4 EXECUTION       Acquire locks → invoke skills → produce artifacts.
5 REVIEW          Independent reviewer (reviewer ≠ producer, Rule 15).
6 HANDOFF         Final checkpoint + capsule emission.

Phases 4↔5 can cycle up to 3 times on CHANGES_REQUESTED (Rule 12 — max review cycles).

Cross-cutting concerns¶

Concern	Module(s)	Rule(s) enforced
Truthfulness	`pipeline.phases.phase_1_reality_anchor`	Lex Canon (Regra Zero)
Spec approval	`pipeline.gates.check_spec_approved`	Rule 35
Budget cap	`pipeline.token_budget`	Rule 16
Resource locks	`pipeline.resource_locks`	Rule 17
Reviewer independence	`pipeline.verification`	Rule 15
PII classification	`privacy.pii_detector` + `privacy.classifier`	Rules 21, 22, 23
Audit chain	`privacy.audit_chain` (HMAC-signed)	Rule 24
Circuit breaker	`ai.circuit_breaker`	— (bulkhead pattern)
Backpressure	`body.hormones` + `scalability.backpressure`	—

Skills, agents, orchestrators¶

Layer 1: Cortex (1 global orchestrator, haiku-4-5, always on)
Layer 2: 10 domain orchestrators (frontend, backend, ai_ml, devops, security, …)
Layer 3: Task orchestrator (ephemeral, spawned per story)
Layer 4: 20 specialists (frontend-specialist, backend-node-specialist, planner-opus, …)
Layer 5: 5 workers (code-writer, file-operator, api-caller, test-runner, git-worker)

The routing flow: intent → ROUTING-COMPASS → domain orch → task orch → specialist → worker → skill.

auditor-haiku runs after every artifact for constitutional compliance.

Storage at v1.0¶

Filesystem-first (JSON / YAML / JSONL). Concrete migration paths:

What	v1.0	v1.5+
Memory stores	JSONL under `_framework/memory/`	Postgres + pgvector
Locks	JSON under `_framework/locks/`	Postgres advisory locks
Audit chain	JSONL HMAC-chained	append-only Postgres + WORM bucket
Continuations	YAML under `_framework/continuations/`	Postgres
RAG index	In-memory TF-overlap	Chroma / pgvector
Metrics	JSONL	Prometheus / OpenTelemetry

The public Python API does not change across these migrations — only the backends.

Visual: end-to-end flow¶

sequenceDiagram
    participant User as Você (humano)
    participant Claude as Claude Code (VS Code)
    participant Bridge as src.bridge.Recorder
    participant Bus as EventBus
    participant Stores as Memory + Audit + Metrics
    participant Dashboard as Dashboard (FastAPI)
    participant Browser as Browser/Webview

    User->>Claude: "Implementar JWT auth"
    Claude->>Bridge: start_capsule(intent=build_feature, specialist=backend-python)
    Bridge->>Bus: publish capsule.received
    Bridge->>Stores: AuditChain.append (HMAC-signed)
    Bus-->>Dashboard: subscriber fires
    Dashboard-->>Browser: WS frame {type: event}

    Claude->>Claude: (works in VS Code, edits files)
    Claude->>Bridge: record_artifact(cap_X, src/auth.py)
    Bridge->>Stores: AuditChain.append, ProceduralStore.record
    Bus-->>Dashboard: heartbeat event
    Dashboard-->>Browser: WS frame {currentStory updated}

    Claude->>Bridge: complete_capsule(cap_X, success)
    Bridge->>Bus: publish capsule.completed
    Bridge->>Stores: EpisodicStore.record + dopamine bump
    Bus-->>Dashboard: subscriber fires
    Dashboard-->>Browser: WS frame {capsule done, hormones update}

Visual: layer map¶

graph TB
    subgraph "Layer 1-3 — Strategic"
        Cortex[Cortex Layer 1<br/>intent classification]
        Domain[Domain Layer 2<br/>specialist dispatch]
        Task[Task Layer 3<br/>inlined in Domain v1.x]
    end
    subgraph "Layer 4-5 — Execution"
        Specialist[Specialist Layer 4<br/>30 PROMPT.md profiles]
        Skill[Skill Layer 5<br/>684 SKILL.md + tool-use]
    end
    subgraph "Layer 6-12 — Runtime"
        Pipeline[Pipeline 7-phase saga]
        Memory[Episodic + Procedural + Semantic]
        Privacy[Audit + PII + RBAC]
        AI[Anthropic SDK + Circuit + Embeddings]
    end
    subgraph "Layer 13-19 — Organism"
        Auto[Autonomy: WorldState + Reflex]
        Body[Body: Hormones + Thermostat]
        Cognitive[Cognitive: Mirror + Intuition + ToM]
        Scale[Scalability: Federation + HDR Queue]
    end
    subgraph "Bridge + Observability"
        Bridge[Bridge: Recorder + CLI]
        Dashboard[Dashboard: FastAPI + WebSocket]
        Tracing[OpenTelemetry → Jaeger]
    end
    Cortex --> Domain --> Specialist --> Skill
    Skill --> Pipeline
    Pipeline --> Memory
    Pipeline --> Privacy
    Pipeline --> AI
    Auto -.-> Pipeline
    Body -.-> Pipeline
    Cognitive -.-> Memory
    Scale -.-> Pipeline
    Bridge --> Pipeline
    Bridge --> Memory
    Bridge --> Privacy
    Pipeline --> Dashboard
    Memory --> Dashboard
    Privacy --> Dashboard
    Pipeline --> Tracing

Visual: production deployment¶

graph LR
    User[User Browser/VS Code] -->|HTTPS| Caddy[Caddy<br/>auto-TLS<br/>port 443]
    Caddy -->|reverse proxy| Dashboard[Dashboard<br/>FastAPI<br/>port 8000]
    Dashboard --> Redis[Redis<br/>federation pub/sub]
    Dashboard --> OTel[OTel Collector<br/>port 4317]
    OTel --> Jaeger[Jaeger UI<br/>port 16686]
    OTel --> Prom[Prometheus<br/>scrape :8889]
    Dashboard --> Disk[(/data volume<br/>_framework/)]
    Disk --> Backup[backup_framework.py<br/>nightly cron]
    Backup --> S3[S3 Object Lock<br/>COMPLIANCE mode]