blackroad-operating-system/codex-docs/docs/architecture.md

Architecture Overview

BlackRoad OS is built on a 7-layer architecture that spans from DNS/CDN at the bottom to user-facing applications at the top.

The 7-Layer Stack

Layer 1: DNS & CDN

Purpose: Domain management, SSL, DDoS protection

• Provider: Cloudflare
• Domains: 10+ domains (blackroad.systems, blackroadai.com, lucidia.earth, etc.)
• Features: DNS routing, SSL termination, caching, DDoS protection

Layer 2: Compute & Infrastructure

Purpose: Application hosting and execution

• Railway: Production backend (FastAPI, PostgreSQL, Redis)
• DigitalOcean: Future RoadChain nodes
• Cloudflare Workers: Edge functions (future)

Layer 3: Data & State

Purpose: Persistence, caching, and blockchain

• PostgreSQL: Primary relational database (Railway managed)
• Redis: Caching and session storage
• RoadChain: Tamper-evident audit ledger
• Vault: Compliance and encrypted storage

Layer 4: Orchestration & Intelligence

Purpose: AI, job scheduling, and workflow automation

• Lucidia Layer: Multi-model AI orchestration (Phase 2)
• Prism Layer: Job queue, event log, metrics
• Operator Engine: Scheduled agents and workflows

Layer 5: API Gateway & Routing

Purpose: HTTP API and WebSocket endpoints

• FastAPI Backend: REST API + WebSocket
• Routes: 30+ API routers for different services
• Features: Authentication, CORS, rate limiting

Layer 6: Application Layer

Purpose: User-facing applications

• Pocket OS: Windows 95-style web interface
• Prism Console: Admin dashboard
• Native Apps: RoadStudio, CloudWay, Lucidia Chat, etc.

Layer 7: User Experience

Purpose: Branded domains and landing pages

• blackroad.systems: Corporate website
• os.blackroad.systems: Main OS interface
• prism.blackroad.systems: Admin console
• lucidia.earth: AI narrative experiences

Request Flow

Here's how a user request flows through the system:

User Browser
    ↓
Cloudflare DNS (Layer 1)
    ↓
Cloudflare CDN/SSL (Layer 1)
    ↓
Railway Load Balancer (Layer 2)
    ↓
FastAPI Backend (Layer 5)
    ↓
Business Logic (Layer 4: Operator, Prism, Lucidia)
    ↓
Database/Redis/RoadChain (Layer 3)
    ↓
Response → Browser

Module Architecture

Backend API

backend/
├── app/
│   ├── main.py           # FastAPI app
│   ├── routers/          # API endpoints
│   ├── models/           # Database models
│   ├── services/         # Business logic
│   └── utils/            # Helpers
└── static/               # Frontend assets

Core OS Runtime

core_os/
├── models.py             # UserSession, Window, OSState
├── state.py              # State management
└── adapters/
    └── api_client.py     # Backend communication

Operator Engine

operator_engine/
├── jobs.py               # Job definitions
├── scheduler.py          # Scheduling logic
└── server.py             # Optional HTTP API

Web Client (Pocket OS)

backend/static/
├── index.html            # Main UI
└── js/
    ├── core-os-client.js # Core OS integration
    ├── apps.js           # Applications
    └── auth.js           # Authentication

Prism Console

prism-console/
├── index.html            # Admin UI
└── static/
    ├── css/prism.css     # Styles
    └── js/prism.js       # Console logic

Technology Stack

Backend

• FastAPI 0.104.1 - Modern async web framework
• SQLAlchemy 2.0.23 - ORM
• PostgreSQL - Database
• Redis 5.0.1 - Caching
• Uvicorn 0.24.0 - ASGI server

Frontend

• Vanilla JavaScript - No framework
• HTML5 / CSS3 - Modern web standards
• Zero dependencies - No build process

Infrastructure

• Railway - Backend hosting
• Cloudflare - DNS, CDN, SSL
• GitHub Actions - CI/CD
• Docker - Containerization

Design Principles

1. Agent-First: Humans orchestrate, agents execute
2. Memory-Conscious: Everything is logged and retrievable
3. Ledger-Aware: Critical actions are provable and tamper-evident
4. Zero-Dependency Frontend: Vanilla JS with no build process
5. Cloud-Native: Infrastructure as software

Scalability

Current Capacity

• Single Railway instance
• PostgreSQL (managed)
• Redis (managed)

Future Scaling

• Horizontal scaling via Railway
• Database read replicas
• Redis clustering
• Cloudflare Workers for edge compute
• RoadChain distributed nodes

Security

• HTTPS Everywhere: Cloudflare SSL
• JWT Authentication: Token-based auth
• Input Validation: Pydantic models
• SQL Injection Protection: ORM queries
• CORS Configuration: Restricted origins
• Rate Limiting: API throttling (future)

Monitoring

• Health Checks: /health endpoint
• Logging: Structured logging
• Error Tracking: Sentry integration
• Metrics: Prometheus (future)
• Observability: Prism Console

Next: Component Deep Dive

See Components for detailed information about each module.