Status: draft · Version 0.1 · Filed 2026-04-23
SPEC-033 v0.1 — Prism Platform Architecture
Status
draft — architectural concept. Captures the validated five-layer reference model and the universal agent coordination vision. Not an implementation spec — this is the north star document that all implementation specs (SPEC-020, SPEC-030, SPEC-032, etc.) derive from and must be consistent with.
1. Summary
Prism is a five-layer platform for AI-first development. Each layer has a single responsibility, a clear storage primitive, and a defined failure mode. Placing state in the wrong layer creates structural defects (proven by SPEC-032 bug investigation). This document codifies the architecture that Frank defined from the project’s inception and that has been validated through 32+ specs of iterative implementation.
2. The Five Layers
┌─────────────────────────────────────────────────────────────┐
│ AGENT SURFACE │
│ Claude Code · Claude Desktop · Codex · Cursor · Future │
│ (each agent talks through exactly one adapter) │
└──────────────────────────┬──────────────────────────────────┘
│
MCP / App Server / ACP adapters
│
┌──────────────────────────▼──────────────────────────────────┐
│ LAYER 4: MCP PRISM ORCHESTRATOR │
│ │
│ The intelligent boundary. Every agent interaction flows │
│ through this layer. Routes queries to the right backing │
│ store. Publishes events to Redis. Delivers signals to │
│ agents via their native protocol. │
│ │
│ Verbs: prism_start, prism_wrap, prism_todo, prism_spec, │
│ prism_remember, semantic_recall, prism_checkpoint, etc. │
│ │
│ Signal delivery (tiered): │
│ Tier 1: MCP push/channels (Claude Code native) │
│ Tier 2: App Server inject (Codex thread/inject_items) │
│ Tier 3: ACP / future protocol adapters │
│ Tier 4: Piggyback on next tool response (fallback) │
│ │
│ Runtime: Python MCP server process (1:1 per agent) │
│ + dedicated heartbeat thread (SPEC-032 §5.3) │
└───┬──────────┬──────────┬──────────┬────────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────────────────────────┐
│LAYER 1 │ │LAYER 2 │ │LAYER 3 │ │ LAYER 5: REDIS │
│POSTGRES│ │NEO4J │ │VECTOR │ │ │
│ │ │ │ │ │ │ Ephemeral coordination: │
│Durable │ │Tri- │ │Semantic│ │ - Session liveness (TTL) │
│domain │ │graph │ │search │ │ - Master election (SETNX) │
│state │ │knowledge│ │across │ │ - Heartbeat (EXPIRE) │
│ │ │repre- │ │sessions│ │ - Event bus (pub/sub) │
│Specs, │ │sentation│ │ │ │ - Peer discovery (SETS) │
│TODOs, │ │ │ │Embed- │ │ │
│deltas, │ │Canonical│ │dings │ │ The broadcast domain. │
│leases, │ │Semantic │ │for │ │ Prism's equivalent of │
│approvals│ │Temporal│ │recall │ │ the network in NetBIOS. │
│cap. │ │layers │ │ │ │ │
│tokens, │ │ │ │ │ │ Hard prerequisite — not │
│nudges │ │SPEC-020│ │ │ │ optional, not degradable. │
│ │ │ │ │ │ │ SPEC-032 │
└────────┘ └────────┘ └────────┘ └────────────────────────────┘
3. Layer Responsibilities
Layer 1: Postgres — Durable Domain State
Responsibility: Data that must survive restarts, has audit requirements, needs SQL queryability, or participates in transactional integrity constraints.
Contents: projects, specs, ADRs, plans, TODOs, session_deltas, retros, journals, leases (partial UNIQUE enforces single-holder), capability_tokens (revocation must outlive process), approval_requests (audit IS the point), nudges (durable obligations).
Failure mode: Postgres down = no domain data. Backend refuses to start.
Governing specs: Migrations 001-018, SPEC-024 (typed artifacts), SPEC-026 (intent queue), SPEC-029 (nudges), SPEC-030 §8-§9-§13 (leases, tokens, approvals).
Layer 2: Neo4j — Tri-Graph Knowledge Representation
Responsibility: Structured knowledge as entities, relationships, and temporal state transitions. The graph that makes Prism a knowledge system, not just a task tracker.
Contents: Three layers per SPEC-020 — Canonical (entities + typed relationships), Semantic (embeddings + similarity edges), Temporal (state transitions + point-in-time queries).
Future expansion: API surface graph (entity types: APIEndpoint, APIConsumer, Module; edge types: CALLS, IMPLEMENTS, DEPENDS_ON) for code reuse and refactoring support.
Failure mode: Neo4j down = no graph queries, no entity resolution. Semantic recall degrades to vector-only. Prism continues but with reduced knowledge fidelity.
Governing specs: SPEC-020 (tri-graph), SPEC-025 (auto-entity), SPEC-026 (UPDATE propagation).
Layer 3: Vector — Semantic Search
Responsibility: Embedding-based retrieval across all sessions and projects. The layer that lets agents find relevant context without knowing exact keywords.
Contents: Embeddings for session_deltas, specs, ADRs, plans, memories, journal entries. Indexed for cosine similarity search.
Failure mode: Vector search unavailable = semantic_recall falls back to lexical. Significant quality degradation but not a hard stop.
Governing specs: Integrated into semantic_recall verb. Embedding generation on write.
Layer 4: MCP Prism Orchestrator — The Intelligent Boundary
Responsibility: The ONLY layer agents interact with directly. Routes agent requests to the appropriate backing store(s). Publishes coordination events to Redis. Delivers signals to agents via their native protocol. Enforces methodology (wrap discipline, session status cards, rules_reminders).
Key principle: Agents never talk to Postgres, Neo4j, or Redis directly. The orchestrator mediates everything. This is what makes Prism agent-agnostic — the orchestrator presents the same verb surface regardless of which backing stores are involved in fulfilling the request.
Runtime model: One MCP server process per agent instance (1:1). Each process runs a dedicated heartbeat thread for Redis TTL refresh (SPEC-032 §5.3). Process lifecycle bound to agent session lifecycle.
Signal delivery: The orchestrator is evolving from “tool server” (request-response) to “universal agent coordination plane” (bidirectional). Signal delivery is tiered by agent capability:
| Tier | Mechanism | Agents | Latency |
|---|
| 1 | MCP push / channels | Claude Code (native) | Real-time |
| 2 | App Server injection | Codex (thread/inject_items via WebSocket) | Real-time |
| 3 | Protocol adapters | ACP-compatible editors (Zed, JetBrains), future agents | Real-time |
| 4 | Tool response piggyback | Any MCP client without push support | Next verb call |
subscribe(channel) + deliver(event). The adapter translates Prism events (MasterPreempted, ApprovalRequested, NudgePending, LeaseContention, CheckpointReminder) into the agent’s native injection mechanism.
Failure mode: MCP server process dies = agent loses Prism connectivity. Agent can still do local work but has no coordination, no memory, no methodology enforcement.
Governing specs: SPEC-021 (session bootstrap), SPEC-023 (wrap discipline), SPEC-031 (checkpoint), all verb contracts.
Layer 5: Redis — Ephemeral Coordination State
Responsibility: State that is inherently ephemeral — bounded by connection liveness and TTL. The broadcast domain for Prism’s NetBIOS-style coordination protocol. The anchor that all agents connect to for session awareness and event delivery.
Key principle: Redis is NOT a cache, NOT an optimization. It is the broadcast domain — Prism’s equivalent of the well-known network in NetBIOS. Without it, there is no coordination plane.
Contents: Session registrations (HASH + TTL), master election (SETNX), heartbeat refresh (EXPIRE), event bus (pub/sub), peer discovery (SETS). All keys carry full tenant:project scope even in local mode.
What Redis is NOT for: Anything with audit requirements, anything that must survive Redis restart, anything that needs SQL queryability. Those belong in Postgres (Layer 1).
Failure mode: Redis down = hard error on coordination features. Domain verbs (hitting Postgres) continue. The operator must fix Redis before multi-agent coordination works. Same posture as Postgres down for domain data.
Governing specs: SPEC-032 (Redis session plane).
4. The Dividing Principle
Every piece of state belongs in exactly one layer. The dividing principle is:
| Question | Answer → Layer |
|---|
| Must it survive a restart? | Yes → Postgres |
| Is it a knowledge relationship? | Yes → Neo4j |
| Does it need similarity search? | Yes → Vector |
| Is it bounded by connection liveness? | Yes → Redis |
| Is it an agent-facing verb or signal? | Yes → Orchestrator |
5. Deployment Modes
All five layers are present in every deployment mode. The provisioning differs but the architecture is identical:
| Layer | Local | LAN | Cloud |
|---|
| Postgres | Containerized (docker-compose.local.yml) | Containerized + ufw | Managed (RDS / Supabase) |
| Neo4j | Containerized | Containerized + ufw | Managed (Aura) |
| Vector | Embedded in Postgres (pgvector) or Neo4j | Same | Managed |
| Orchestrator | MCP server per agent | Same | Same |
| Redis | Containerized (SPEC-032 §8.2) | Containerized + ufw (§8.3) | Managed (Upstash / ElastiCache) (§8.4) |
6. Agent Interaction Model
Agent (Claude Code / Codex / Cursor / ...)
│
│ MCP tool call (prism_start, prism_todo, etc.)
▼
MCP Prism Orchestrator
│
├──→ Postgres (read/write domain state)
├──→ Neo4j (read/write graph)
├──→ Vector (read for recall, write embeddings on store)
└──→ Redis (read/write session state, publish events)
│
│ Signal delivery (push events back to agents)
▼
Agent receives signal via native mechanism
7. What This Document Is NOT
This is NOT an implementation spec. It does not specify schemas, migration scripts, API contracts, or acceptance criteria. Those belong in the layer-specific specs:
- Layer 1 schemas: migrations, SPEC-024, SPEC-026, SPEC-029
- Layer 2 graph: SPEC-020, SPEC-025
- Layer 4 orchestrator: SPEC-021, SPEC-023, SPEC-031, verb contracts
- Layer 5 Redis: SPEC-032
- Signal delivery: future spec (adapter architecture)
- API surface graph: future spec (tri-graph extension)
This document is the reference model that those specs must be consistent with. When a new spec is drafted, it should identify which layer(s) it touches and verify that state is placed in the correct layer per §4’s dividing principle.
8. Authorship
- Architecture: Frank — defined from project inception, validated through 32+ specs of implementation.
- Documentation: Lola (Claude Desktop, session 97e32dbf) 2026-04-23.
- Validation signal: SPEC-032 bug investigation proved the layer boundaries are load-bearing. Frank’s instinct (“why isn’t this a simple memory table?”) identified the missing layer before the formal root-cause analysis did.
Status: draft
