Three-Tier Architecture (Core → Choco → MERIDIAN)

ELI5

IRIS is built like a three-story building. The ground floor (Tier 1) has everything you need to live — kitchen, bathroom, bedroom. You can live here alone. The second floor (Tier 2) adds a home office with a direct video line to your colleagues (MCP bridge to Claude). The third floor (Tier 3) connects your home to the neighbourhood council (MERIDIAN federation). Each floor is optional except the ground floor.

Technical Deep Dive

Tier 1: IRIS Core (Mandatory)

Tier 1 is the standalone sprite configuration engine. It has zero external dependencies and contains:

Data flow: Sprite YAML → SDK validation → Registry → Chain execution → Gate checks → Result

Tier 2: Choco Bridge (Optional)

MCP-native integration for AI clients. The iris-mcp-server (TypeScript, deployable to Cloudflare Workers) exposes four MCP tools:

1. create_sprite_in_iris — Create and optionally document a sprite
2. validate_sprite — Dry-run validation against iris.schema.json
3. create_council — Group sprites under governance
4. run_chain — Execute a chain synchronously

Key design principle: IRIS does not require Choco. The MCP server is a bridge, not a dependency. Sprite creation always happens in IRIS regardless of Choco availability.

Tier 3: MERIDIAN Federation (Advanced)

Bridges IRIS sprites into the MERIDIAN council ecosystem via the STRATT protocol. The iris-meridian-adapter provides:

• Sprite-to-MERIDIAN Council mapping (iris:// ↔ strat://)
• Blake3 fingerprint cross-verification against STRATT hash pipeline
• NFT-style capability token generation (time-limited, revocable)
• Cross-namespace resolution

Architecture Diagram

flowchart TB
  subgraph source_of_truth["iris-specs"]
    schema["JSON Schema / OpenAPI / Protobuf"]
  end
  subgraph tier3["Tier 3 — MERIDIAN"]
    meridian_adapter["gRPC Adapter iris-meridian-adapter"]
    stratt["STRATT Protocol"]
  end
  subgraph tier2["Tier 2 — Choco Bridge"]
    mcp_server["MCP Server iris-mcp-server"]
    choco["Choco Docs"]
  end
  subgraph tier1["Tier 1 — IRIS Core"]
    iris_api["FastAPI iris-service"]
    python_sdk["Python SDK"]
    ts_sdk["TypeScript SDK"]
    registry["In-Memory Registry"]
  end
  subgraph clients["Clients"]
    web["Next.js iris-web"]
    python_client["Python Scripts"]
    ts_client["Web Apps"]
    claude["Claude MCP"]
  end
  schema --> meridian_adapter
  schema --> mcp_server
  schema --> iris_api
  meridian_adapter --> iris_api
  stratt --> meridian_adapter
  mcp_server --> iris_api
  choco --> mcp_server
  python_sdk --> iris_api
  ts_sdk --> iris_api
  iris_api --> registry
  python_client --> python_sdk
  ts_client --> ts_sdk
  claude --> mcp_server
  web --> iris_api

Decision Drivers

The three-tier split was driven by four locked architectural decisions:

• DEC-004 (microservice repo architecture): Each tier can evolve independently with its own CI/CD
• DEC-001 (separate endpoints per sprite): Enables per-sprite scaling within Tier 1
• DEC-002 (synchronous chains with binding gates): Tier 1 guarantees deterministic execution
• DEC-005 (Blake3 fingerprinting): Cross-tier identity verification using STRATT-compatible hashes

Key Terms

• Tier 1 → The standalone IRIS Core: REST API, registries, chain execution, gate engine
• Tier 2 → MCP bridge for AI client integration (optional, non-blocking)
• Tier 3 → MERIDIAN federation for cross-system sprite governance (advanced)
• MCP → Model Context Protocol; stdio/SSE transport for tool exposure to AI assistants
• STRATT → The broader protocol family that MERIDIAN belongs to; shares Blake3 fingerprinting

Q&A

Q: Can I deploy Tier 1 without Docker? A: Yes. iris-service is a standard FastAPI app runnable with uvicorn app.main:app. The Docker Compose stack includes observability (Prometheus, Grafana, Jaeger, Loki, PostgreSQL) but these are optional.

Q: What happens if Tier 2 (MCP) goes down? A: Nothing. Tier 1 continues operating normally. Clients using the REST API or SDKs are unaffected. MCP is a convenience bridge for AI assistant integration.

Q: Does Tier 3 require STRATT to be running? A: Yes. The iris-meridian-adapter is a two-sided bridge. It requires both iris-service (Tier 1) and a MERIDIAN gRPC endpoint (STRATT ecosystem) to function.

Q: Why not put everything in a monorepo? A: DEC-004 explicitly rejected monorepos to enforce clean boundaries, independent versioning, and team-scoped ownership. iris-specs acts as the contract-driven source of truth that binds the repos together.

Examples

A three-tier architecture is like a food delivery platform:

• Tier 1 = The restaurant kitchen (cooks food, has everything needed standalone)
• Tier 2 = The delivery app (adds convenience but the kitchen works without it)
• Tier 3 = A franchise network (connects your restaurant to a global brand system)