blackroad-os-docs/docs/meta/vision/architecture.md

BlackRoad OS — Architecture Overview

Version: 1.0 Last Updated: 2025-11-30 Status: Active

---

System Overview

BlackRoad OS is a distributed AI orchestration platform built on three core layers:

┌─────────────────────────────────────────────────────────────────┐
│                      PORTAL LAYER                                │
│   Lucidia │ RoadWork │ RoadView │ RoadGlitch │ RoadWorld │ BackRoad │
├─────────────────────────────────────────────────────────────────┤
│                    GOVERNANCE LAYER                              │
│        Policies │ Ledger │ Intents │ Claims │ Delegations        │
├─────────────────────────────────────────────────────────────────┤
│                   INTEGRATION LAYER                              │
│              MCP │ Tools │ Connectors │ APIs                     │
├─────────────────────────────────────────────────────────────────┤
│                  INFRASTRUCTURE LAYER                            │
│        Cloudflare │ Railway │ Self-hosted LLMs │ Edge            │
└─────────────────────────────────────────────────────────────────┘

---

Core Architecture Principles

1. Edge-First Design

All latency-sensitive operations happen at the edge via Cloudflare Workers. This includes:

• Request routing
• Authentication/authorization
• Policy evaluation
• Caching

2. Event-Driven Orchestration

The system is built around events, not request/response cycles:

• Every significant action produces a ledger event
• Agents react to events, not direct calls
• Async by default, sync when necessary

3. Governance as Infrastructure

Governance isn't a feature — it's the foundation:

• Every tool call passes through policy evaluation
• Every action is logged to an immutable ledger
• Every permission is explicit and auditable

4. Composable Agents

Agents are small, focused, and composable:

• Single responsibility per agent
• Standard communication protocol
• Orchestrator (Cece) coordinates complex workflows

---

Layer Details

Infrastructure Layer

The foundation that runs everything.

Component	Technology	Purpose
Edge Compute	Cloudflare Workers	Request routing, auth, caching
Key-Value Store	Cloudflare KV	Governance objects, config
SQL Database	Cloudflare D1 / Railway Postgres	Structured data, analytics
Object Storage	Cloudflare R2	Files, media, backups
Backend Services	Railway	APIs, schedulers, workers
LLM Inference	Self-hosted Mistral + Claude API	AI operations
Message Queue	Railway Redis	Job queues, pub/sub

Deployment Topology

                    ┌──────────────┐
                    │   Internet   │
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  Cloudflare  │
                    │   (Edge)     │
                    ├──────────────┤
                    │ Workers (KV) │
                    │ Pages (UI)   │
                    │ R2 (Storage) │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌───▼────┐ ┌─────▼─────┐
       │   Railway   │ │ LLM    │ │  External │
       │  (Backend)  │ │ Cluster│ │   APIs    │
       ├─────────────┤ └────────┘ └───────────┘
       │ API Gateway │
       │ Operator    │
       │ Agents      │
       │ Postgres    │
       │ Redis       │
       └─────────────┘

Integration Layer

Connects BlackRoad to external systems via Model Context Protocol (MCP).

MCP Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP HOST (Cece)                       │
├─────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │ Gmail   │  │ Drive   │  │ Notion  │  │ Stripe  │    │
│  │ Server  │  │ Server  │  │ Server  │  │ Server  │    │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘    │
│       │            │            │            │          │
│  ┌────▼────────────▼────────────▼────────────▼────┐    │
│  │              Tool Registry                      │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Supported Integrations

Category	Tools
Communication	Gmail, Slack, Discord
Documents	Google Drive, Notion, Dropbox
Development	GitHub, Linear, Jira
Finance	Stripe, QuickBooks
Infrastructure	Cloudflare, Railway, Vercel
Data	Postgres, Redis, Pinecone

Governance Layer

The brain that ensures safe, auditable operations.

Core Objects

┌─────────────────────────────────────────────────────────┐
│                   GOVERNANCE MODEL                       │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   INTENT ──────► AGENT ──────► TOOL CALL                │
│      │             │              │                      │
│      │             │              ▼                      │
│      │             │         POLICY CHECK                │
│      │             │              │                      │
│      │             │              ▼                      │
│      └─────────────┴────────► LEDGER EVENT              │
│                                                          │
└─────────────────────────────────────────────────────────┘

Object Definitions

Object	Purpose	Key Pattern
POLICY	Rules that allow/deny/modify actions	policy:{scope}:{id}
LEDGER	Immutable audit trail	ledger:{intent_id}:{event_id}
AGENT	Registry of workers	agent:{agent_id}
INTENT	Tasks and workflow state	intent:{intent_id}
CLAIM	Identity assertions	claim:{subject}:{id}
DELEGATION	Scoped permissions	delegation:{delegator}:{id}

Policy Evaluation Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Request    │────►│   Policy     │────►│   Decision   │
│   Context    │     │   Engine     │     │   Result     │
└──────────────┘     └──────────────┘     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │   Actions:   │
                     │   - allow    │
                     │   - deny     │
                     │   - require_ │
                     │     approval │
                     │   - transform│
                     └──────────────┘

Portal Layer

User-facing applications built on the platform.

Portal	Domain	Key Features
Lucidia	Personal AI	Persistent memory, preference learning, multi-modal
RoadWork	Education	Adaptive curriculum, progress tracking, certification
RoadView	Media	Video/image generation, editing, publishing
RoadGlitch	Gaming	Procedural content, AI NPCs, adaptive difficulty
RoadWorld	Navigation	Context-aware routing, AR overlays, local knowledge
BackRoad	Privacy	Encryption, anonymization, secure communication

---

Agent Architecture

Agent Hierarchy

┌─────────────────────────────────────────────────────────┐
│                    CECE (Governor)                       │
│              Lucidia-class Orchestrator                  │
├─────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │ Planner │  │ Builder │  │ Scribe  │  │Guardian │    │
│  │  Agent  │  │  Agent  │  │  Agent  │  │  Agent  │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
├─────────────────────────────────────────────────────────┤
│                   Worker Agents                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │  Email  │  │  Code   │  │  Data   │  │  Media  │    │
│  │ Handler │  │ Writer  │  │ Analyst │  │ Creator │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
└─────────────────────────────────────────────────────────┘

Agent Classes

Class	Role	Examples
Lucidia	Governance & orchestration	Cece
Worker	Specialized tasks	EmailHandler, CodeWriter
System	Infrastructure operations	Scheduler, Monitor
Integration	External tool bridges	GmailServer, StripeServer

Agent Communication

Agents communicate via structured messages:

{
  "message_id": "msg-20251130-abc123",
  "from": "cece.governor.v1",
  "to": "email.handler.v1",
  "intent_id": "int-20251130-xyz789",
  "action": "draft_email",
  "payload": {
    "recipient": "investor@example.com",
    "subject": "Follow-up on our meeting",
    "context": "..."
  },
  "constraints": {
    "require_approval": true,
    "max_tokens": 500
  }
}

---

Data Flow

Request Lifecycle

1. User Request
   │
   ▼
2. Edge Router (Cloudflare Worker)
   │
   ├──► Auth Check (Claims)
   │
   ▼
3. Intent Creation
   │
   ▼
4. Cece Planning
   │
   ├──► Tool Selection
   ├──► Policy Pre-check
   │
   ▼
5. Agent Execution
   │
   ├──► Tool Call
   ├──► Policy Evaluation
   ├──► Ledger Write
   │
   ▼
6. Result Aggregation
   │
   ▼
7. Response to User

Event Flow

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  Tool   │───►│ Policy  │───►│ Ledger  │───►│  Index  │
│  Call   │    │  Check  │    │  Write  │    │ Update  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
                    │
                    ▼
              ┌─────────┐
              │ Webhook │
              │ Notify  │
              └─────────┘

---

Security Model

Authentication

• Users: OAuth 2.0 / OpenID Connect
• Agents: API keys with scoped permissions
• Services: mTLS between internal services

Authorization

┌─────────────────────────────────────────────────────────┐
│                 AUTHORIZATION STACK                      │
├─────────────────────────────────────────────────────────┤
│  1. Claims     - Who are you?                           │
│  2. Delegations - What can you do?                      │
│  3. Policies   - What's allowed in this context?        │
│  4. Audit      - What did you do?                       │
└─────────────────────────────────────────────────────────┘

Data Classification

Level	Description	Examples
Public	No restrictions	Marketing content
Internal	Org-only access	Design docs
Confidential	Role-based access	User data
Restricted	Named individual access	Secrets, PII

---

Scalability

Horizontal Scaling

Component	Scaling Strategy
Edge Workers	Auto-scaled by Cloudflare
API Gateway	Railway auto-scaling
Agent Workers	Queue-based scaling
Database	Read replicas + connection pooling

Performance Targets

Metric	Target
Edge latency (P99)	< 50ms
API latency (P99)	< 200ms
Agent task completion	< 30s
Ledger write	< 100ms

---

Repository Structure

Repo	Purpose
blackroad-os-core	Desktop UI, auth, identity
blackroad-os-api	API gateway, REST endpoints
blackroad-os-operator	Job scheduler, background workers
blackroad-os-agents	Agent implementations
blackroad-os-infra	IaC, deployment configs
blackroad-os-docs	Documentation (this repo)
blackroad-os-web	Web frontend
blackroad-os-prism-console	Admin dashboard
lucidia-core	AI reasoning engines

---

References

• Cece Agent Mode
• Governance Roadmap
• KV Schema
• API Design