4c9413f204
- Add manifesto with core principles and six portal vision - Add vision & mission with 5-year roadmap and success metrics - Add architecture overview with system diagrams - Add Cece agent mode system prompt for governance layer - Add governance roadmap with KV schema and sprint plan - Add master implementation roadmap tracking 50 tasks 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
393 lines
16 KiB
Markdown
393 lines
16 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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/cece-agent-mode.md)
|
|
- [Governance Roadmap](../governance/governance-roadmap.md)
|
|
- [KV Schema](../reference/kv-schema.md)
|
|
- [API Design](../reference/api-design.md)
|