# 🗺️ BlackRoad OS Repository Map

**Version**: 2.5
**Date**: 2025-11-18
**Purpose**: Complete module-by-module breakdown showing how components connect

---

## Repository Structure

```
BlackRoad-Operating-System/          # Canonical OS monorepo
├── backend/                          # FastAPI backend + static UI
│   ├── app/                          # Core application
│   │   ├── main.py                   # FastAPI app, router registration
│   │   ├── config.py                 # Settings (Pydantic)
│   │   ├── database.py               # SQLAlchemy async sessions
│   │   ├── redis_client.py           # Redis connection pool
│   │   ├── models/                   # Database models (SQLAlchemy)
│   │   ├── routers/                  # API endpoint routers (33+)
│   │   ├── services/                 # Business logic layer
│   │   └── utils/                    # Shared utilities
│   ├── static/                       # Frontend UI (canonical)
│   │   ├── index.html                # Main OS interface
│   │   ├── prism/                    # Prism Console UI
│   │   ├── js/                       # JavaScript modules
│   │   └── assets/                   # CSS, images, fonts
│   ├── tests/                        # Backend test suite
│   ├── requirements.txt              # Python dependencies
│   └── Dockerfile                    # Container definition
│
├── agents/                           # 200+ AI agent ecosystem
│   ├── base/                         # Core agent framework
│   ├── categories/                   # 10 agent categories
│   └── tests/                        # Agent tests
│
├── sdk/                              # Client SDKs
│   ├── python/                       # Python SDK
│   └── typescript/                   # TypeScript SDK
│
├── codex-docs/                       # MkDocs documentation
│   ├── mkdocs.yml                    # Docs configuration
│   ├── docs/                         # Markdown documentation
│   └── DEPLOY_DOCS.md                # Deployment guide
│
├── infra/                            # Infrastructure configs
│   ├── cloudflare/                   # DNS, Workers
│   ├── railway/                      # Railway deployment
│   └── env/                          # Environment variables
│
├── .github/                          # GitHub automation
│   ├── workflows/                    # CI/CD pipelines
│   └── CODEOWNERS                    # Code ownership
│
├── docs/                             # Legacy docs (consolidating to codex-docs/)
├── scripts/                          # Utility scripts
├── ops/                              # Operations tools
└── [Root documentation files]
    ├── README.md                     # Project overview
    ├── CLAUDE.md                     # AI assistant guide
    ├── MASTER_ORCHESTRATION_PLAN.md  # Infrastructure blueprint
    ├── PHASE2_5_SUMMARY_FOR_ALEXA.md # Phase 2.5 summary
    └── DEPLOYMENT_NOTES.md           # Production deployment guide
```

---

## Module Connections & Data Flow

### 1. Request Flow (User → Backend → Database)

```
┌─────────────────────────────────────────────────────────────┐
│ USER BROWSER                                                 │
│ - Visits: https://blackroad.systems                         │
│ - Loads: backend/static/index.html                          │
│ - Executes: JavaScript (OS boot)                            │
└─────────────────────────────────────────────────────────────┘
                            ↓ HTTP Request
┌─────────────────────────────────────────────────────────────┐
│ CLOUDFLARE CDN                                               │
│ - DNS resolution                                             │
│ - SSL termination                                            │
│ - Static asset caching                                       │
│ - DDoS protection                                            │
└─────────────────────────────────────────────────────────────┘
                            ↓ Proxy
┌─────────────────────────────────────────────────────────────┐
│ RAILWAY → FastAPI Backend (backend/app/main.py)             │
│                                                              │
│ Request Handling:                                            │
│ 1. CORS Middleware (app/main.py:78)                         │
│ 2. Timing Middleware (app/main.py:89)                       │
│ 3. Router Matching                                           │
│                                                              │
│ Routes:                                                      │
│ • GET / → StaticFiles(backend/static/)                      │
│ • GET /prism → StaticFiles(backend/static/prism/)           │
│ • GET /api/docs → OpenAPI documentation                     │
│ • GET /health → Health check endpoint                       │
│ • POST /api/auth/login → auth.router                        │
│ • GET /api/prism/jobs → prism.router (future)               │
│ • [30+ other API routes]                                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ ROUTER LAYER (backend/app/routers/)                         │
│                                                              │
│ Example: POST /api/auth/login                               │
│ 1. routers/auth.py:login()                                  │
│ 2. Validate request (Pydantic schema)                       │
│ 3. Call service layer                                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ SERVICE LAYER (backend/app/services/)                       │
│                                                              │
│ Example: services/auth.py                                    │
│ 1. authenticate_user(email, password)                        │
│ 2. Query database via models                                │
│ 3. Verify password hash                                     │
│ 4. Generate JWT token                                       │
│ 5. Store session in Redis                                   │
│ 6. Return user data + token                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ DATA LAYER                                                   │
│                                                              │
│ PostgreSQL (Railway managed):                                │
│ • app/database.py → async session                           │
│ • app/models/ → SQLAlchemy ORM                              │
│ • Tables: users, wallets, blocks, etc.                      │
│                                                              │
│ Redis (Railway managed):                                     │
│ • app/redis_client.py → connection pool                     │
│ • Usage: sessions, caching, WebSocket state                 │
└─────────────────────────────────────────────────────────────┘
                            ↓ Response
┌─────────────────────────────────────────────────────────────┐
│ BROWSER (JavaScript)                                         │
│ - Receives JSON response                                    │
│ - Updates OS UI (DOM manipulation)                          │
│ - Stores token in localStorage                              │
│ - Makes subsequent API calls with auth header               │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. Frontend Architecture (Vanilla JavaScript)

### Main OS (backend/static/)

```
static/
├── index.html                        # OS entry point
│   └── Loads:
│       ├── css/os.css                # OS styling
│       ├── js/os.js                  # Core OS runtime
│       ├── js/components.js          # UI component library
│       ├── js/registry.js            # App registry
│       └── js/apps/*.js              # Individual apps
│
├── js/
│   ├── os.js                         # Core OS
│   │   ├── window.OS object          # Global OS namespace
│   │   ├── Event bus                 # Inter-app communication
│   │   ├── Window manager            # Draggable windows
│   │   └── State management          # Local storage
│   │
│   ├── components.js                 # UI Components
│   │   ├── Button()                  # Button component
│   │   ├── Card()                    # Card component
│   │   ├── Modal()                   # Modal dialog
│   │   └── [12+ other components]
│   │
│   ├── registry.js                   # App Registry
│   │   ├── List of all apps          # Icon, name, category
│   │   └── App initialization        # Load on demand
│   │
│   └── apps/                         # Application Modules
│       ├── prism.js                  # Prism Console app
│       ├── lucidia.js                # AI chat app
│       ├── miners.js                 # Mining app
│       ├── dashboard.js              # Dashboard app
│       └── [20+ other apps]
│
└── assets/
    ├── css/                          # Stylesheets
    │   ├── os.css                    # Main OS styles
    │   ├── win95.css                 # Windows 95 theme
    │   └── components.css            # Component styles
    │
    └── images/                       # Icons, logos, backgrounds
```

### Prism Console (backend/static/prism/)

```
prism/
├── index.html                        # Prism entry point (served at /prism)
│   └── Loads:
│       ├── css/prism.css             # Prism-specific styling
│       ├── js/prism-core.js          # Prism runtime
│       └── js/prism-components.js    # Prism UI components
│
├── js/
│   ├── prism-core.js                 # Core Prism logic
│   │   ├── Job queue management      # Monitor running jobs
│   │   ├── Event log viewer          # System event stream
│   │   ├── Metrics dashboard         # Health, performance
│   │   └── API client                # Calls /api/prism/*
│   │
│   └── prism-components.js           # Prism-specific UI
│       ├── JobCard()                 # Job display card
│       ├── LogViewer()               # Event log component
│       └── MetricsChart()            # Metrics visualization
│
└── assets/
    └── css/prism.css                 # Prism styling
```

### Communication Pattern

```javascript
// Example: Prism Console fetching jobs

// 1. Prism UI component (prism/js/prism-core.js)
async function fetchJobs() {
    const response = await fetch('/api/prism/jobs', {
        headers: {
            'Authorization': `Bearer ${localStorage.getItem('token')}`
        }
    });
    const jobs = await response.json();
    renderJobs(jobs);
}

// 2. Backend router (backend/app/routers/prism.py)
@router.get("/jobs")
async def get_jobs(
    current_user = Depends(get_current_user),
    db: AsyncSession = Depends(get_db)
):
    jobs = await db.execute(select(Job).where(Job.user_id == current_user.id))
    return jobs.scalars().all()

// 3. Response flows back to frontend, rendered in UI
```

---

## 3. Backend API Architecture

### Router Organization (backend/app/routers/)

```
routers/
├── auth.py                           # Authentication
│   ├── POST /api/auth/register       # User registration
│   ├── POST /api/auth/login          # User login
│   ├── POST /api/auth/refresh        # Token refresh
│   └── GET /api/auth/me              # Current user
│
├── prism_static.py                   # Prism Console static serving (NEW)
│   └── GET /prism/*                  # Serve Prism UI files
│
├── prism.py                          # Prism API (future)
│   ├── GET /api/prism/jobs           # List jobs
│   ├── POST /api/prism/jobs          # Create job
│   ├── GET /api/prism/jobs/{id}      # Get job details
│   ├── GET /api/prism/events         # Event stream
│   └── GET /api/prism/metrics        # System metrics
│
├── dashboard.py                      # Dashboard data
│   ├── GET /api/dashboard/stats      # System statistics
│   └── GET /api/dashboard/activity   # Recent activity
│
├── blockchain.py                     # RoadChain
│   ├── GET /api/blockchain/blocks    # List blocks
│   ├── POST /api/blockchain/blocks   # Create block
│   └── GET /api/blockchain/verify    # Verify chain
│
├── ai_chat.py                        # AI/Lucidia integration
│   ├── POST /api/chat/message        # Send message
│   └── GET /api/chat/history         # Chat history
│
├── miner.py                          # Mining operations
│   ├── POST /api/miner/start         # Start mining
│   ├── POST /api/miner/stop          # Stop mining
│   └── GET /api/miner/stats          # Mining statistics
│
└── [30+ other routers]               # See backend/app/main.py for full list
```

### Service Layer (backend/app/services/)

```
services/
├── auth.py                           # Authentication logic
│   ├── authenticate_user()           # Verify credentials
│   ├── create_access_token()         # Generate JWT
│   └── verify_token()                # Validate JWT
│
├── crypto.py                         # Cryptography
│   ├── hash_password()               # Password hashing
│   ├── verify_password()             # Password verification
│   └── encrypt_wallet_key()          # Wallet encryption
│
├── blockchain.py                     # RoadChain logic
│   ├── create_block()                # Create new block
│   ├── verify_chain()                # Verify blockchain
│   └── calculate_hash()              # SHA-256 hashing
│
└── [Other services]
```

### Database Models (backend/app/models/)

```
models/
├── user.py                           # User model
│   ├── id: int (PK)
│   ├── email: str (unique)
│   ├── password_hash: str
│   ├── created_at: datetime
│   └── Relationships: wallets, jobs
│
├── wallet.py                         # Wallet model
│   ├── id: int (PK)
│   ├── user_id: int (FK → users)
│   ├── address: str (unique)
│   ├── private_key_encrypted: str
│   └── balance: float
│
├── block.py                          # Blockchain block
│   ├── id: int (PK)
│   ├── index: int
│   ├── timestamp: datetime
│   ├── data: JSON
│   ├── previous_hash: str
│   └── hash: str
│
├── job.py                            # Prism job (future)
│   ├── id: int (PK)
│   ├── user_id: int (FK → users)
│   ├── type: str (e.g., "deploy", "test")
│   ├── status: str (pending/running/completed/failed)
│   ├── created_at: datetime
│   └── result: JSON
│
└── [Other models]
```

---

## 4. Agent Ecosystem (agents/)

### Base Framework (agents/base/)

```
base/
├── agent.py                          # Base Agent class
│   ├── __init__(name, version, category)
│   ├── async execute()               # Main execution method
│   ├── async initialize()            # Setup before execution
│   ├── async cleanup()               # Cleanup after execution
│   └── async on_error(error)         # Error handling
│
├── executor.py                       # Execution engine
│   ├── run_agent(agent)              # Execute single agent
│   ├── run_workflow(agents)          # Execute agent workflow
│   └── schedule_agent(agent, cron)   # Schedule recurring execution
│
└── registry.py                       # Agent discovery
    ├── register(agent)               # Register agent
    ├── discover()                    # Auto-discover agents
    └── get_agent(name)               # Get agent by name
```

### Agent Categories (agents/categories/)

```
categories/
├── devops/                           # DevOps agents (30+)
│   ├── deploy_agent.py               # Deployment automation
│   ├── monitor_agent.py              # Infrastructure monitoring
│   └── backup_agent.py               # Backup automation
│
├── engineering/                      # Engineering agents (40+)
│   ├── code_review_agent.py          # Code review
│   ├── test_generator_agent.py       # Test generation
│   └── refactor_agent.py             # Code refactoring
│
├── ai_ml/                            # AI/ML agents (25+)
│   ├── model_trainer_agent.py        # Model training
│   ├── data_pipeline_agent.py        # Data processing
│   └── inference_agent.py            # Model inference
│
└── [7 more categories]               # See agents/README.md
```

### Agent Communication (via Prism)

```
┌─────────────────────────────────────────────────────────────┐
│ AGENT A (Deploy Agent)                                       │
│ 1. Execute deployment                                        │
│ 2. Publish event to Prism: {"type": "deploy_complete"}      │
└─────────────────────────────────────────────────────────────┘
                            ↓ Event
┌─────────────────────────────────────────────────────────────┐
│ PRISM (Event Bus)                                            │
│ - Receives event                                             │
│ - Logs to event table (database)                            │
│ - Publishes to Redis (pub/sub)                              │
│ - Notifies subscribed agents                                │
└─────────────────────────────────────────────────────────────┘
                            ↓ Subscription
┌─────────────────────────────────────────────────────────────┐
│ AGENT B (Monitor Agent)                                      │
│ 1. Receives "deploy_complete" event                         │
│ 2. Runs health checks                                       │
│ 3. Publishes event: {"type": "health_check_passed"}        │
└─────────────────────────────────────────────────────────────┘
```

---

## 5. Documentation (codex-docs/)

### MkDocs Structure

```
codex-docs/
├── mkdocs.yml                        # Configuration
│   ├── site_name: "BlackRoad OS Codex"
│   ├── theme: material               # Material for MkDocs
│   ├── plugins: search, etc.         # MkDocs plugins
│   └── nav: [navigation structure]   # Sidebar navigation
│
├── docs/                             # Markdown documentation
│   ├── index.md                      # Landing page
│   │
│   ├── architecture/                 # Architecture docs
│   │   ├── overview.md               # System overview
│   │   ├── phase2-decisions.md       # Phase 2.5 decisions
│   │   └── infra-deployment.md       # Deployment architecture
│   │
│   ├── api/                          # API reference
│   │   ├── authentication.md         # Auth endpoints
│   │   ├── prism.md                  # Prism API
│   │   └── blockchain.md             # RoadChain API
│   │
│   ├── guides/                       # User guides
│   │   ├── quickstart.md             # Quick start guide
│   │   ├── deployment.md             # Deployment guide
│   │   └── development.md            # Development setup
│   │
│   ├── agents/                       # Agent documentation
│   │   ├── overview.md               # Agent ecosystem
│   │   ├── creating-agents.md        # How to create agents
│   │   └── categories.md             # Agent categories
│   │
│   └── contributing.md               # Contribution guidelines
│
├── DEPLOY_DOCS.md                    # Deployment guide for docs
│
└── site/                             # Generated site (gitignored)
    └── [Built HTML files]
```

### Documentation Deployment Flow

```
┌─────────────────────────────────────────────────────────────┐
│ DEVELOPER                                                    │
│ 1. Edit markdown in codex-docs/docs/                        │
│ 2. Test locally: mkdocs serve                               │
│ 3. Commit and push to main                                  │
└─────────────────────────────────────────────────────────────┘
                            ↓ Git Push
┌─────────────────────────────────────────────────────────────┐
│ GITHUB ACTIONS (.github/workflows/docs-deploy.yml)          │
│ 1. Checkout code                                             │
│ 2. Install MkDocs + Material theme                          │
│ 3. Run: mkdocs build --strict                               │
│ 4. Deploy to gh-pages branch                                │
└─────────────────────────────────────────────────────────────┘
                            ↓ Deploy
┌─────────────────────────────────────────────────────────────┐
│ GITHUB PAGES                                                 │
│ - Serves from: gh-pages branch                              │
│ - URL: https://blackboxprogramming.github.io/BlackRoad-*    │
└─────────────────────────────────────────────────────────────┘
                            ↓ DNS
┌─────────────────────────────────────────────────────────────┐
│ CLOUDFLARE                                                   │
│ - CNAME: docs.blackroad.systems → blackboxprogramming.github.io │
│ - Proxied: Yes (SSL + CDN)                                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ USER                                                         │
│ - Visits: https://docs.blackroad.systems                    │
│ - Views: MkDocs documentation                               │
└─────────────────────────────────────────────────────────────┘
```

---

## 6. SDK Architecture (sdk/)

### Python SDK (sdk/python/)

```python
# Example usage:
from blackroad import BlackRoadClient

client = BlackRoadClient(
    base_url="https://blackroad.systems",
    api_key="your-api-key"
)

# Authenticate
user = await client.auth.login("email@example.com", "password")

# Create a job
job = await client.prism.create_job({
    "type": "deploy",
    "target": "production",
    "config": {...}
})

# Monitor job
status = await client.prism.get_job_status(job.id)
```

### TypeScript SDK (sdk/typescript/)

```typescript
// Example usage:
import { BlackRoadClient } from '@blackroad/sdk';

const client = new BlackRoadClient({
    baseUrl: 'https://blackroad.systems',
    apiKey: 'your-api-key'
});

// Authenticate
const user = await client.auth.login('email@example.com', 'password');

// Create a job
const job = await client.prism.createJob({
    type: 'deploy',
    target: 'production',
    config: {...}
});

// Monitor job
const status = await client.prism.getJobStatus(job.id);
```

---

## 7. Infrastructure (infra/)

### Cloudflare (infra/cloudflare/)

```
cloudflare/
├── records.yaml                      # DNS records
├── CLOUDFLARE_DNS_BLUEPRINT.md       # DNS configuration guide
├── DNS_CONFIGURATION.md              # Detailed DNS setup (NEW)
└── cloudflare_dns_sync.py            # Automated DNS sync script
```

### Railway (infra/railway/)

```
railway/
├── RAILWAY_DEPLOYMENT_GUIDE.md       # Complete deployment guide (NEW)
├── railway.toml                      # Railway configuration
└── railway.json                      # Service definitions
```

### Environment (infra/env/)

```
env/
└── ENVIRONMENT_MAP.md                # Cross-platform env vars
```

---

## 8. CI/CD (.github/workflows/)

```
workflows/
├── ci.yml                            # Main CI (lint, test, build)
├── backend-tests.yml                 # Backend test suite
├── railway-deploy.yml                # Deploy to Railway
├── docs-deploy.yml                   # Deploy docs to GitHub Pages (NEW)
├── railway-automation.yml            # Railway secrets audit
└── [Other workflows]
```

---

## API Contracts Between Layers

### Frontend ↔ Backend

**Authentication:**
```typescript
// Request
POST /api/auth/login
{
    "email": "user@example.com",
    "password": "password123"
}

// Response
{
    "access_token": "eyJhbGciOi...",
    "token_type": "bearer",
    "user": {
        "id": 1,
        "email": "user@example.com"
    }
}
```

**Prism Jobs:**
```typescript
// Request
GET /api/prism/jobs
Headers: { "Authorization": "Bearer eyJhbGciOi..." }

// Response
{
    "data": [
        {
            "id": 1,
            "type": "deploy",
            "status": "completed",
            "created_at": "2025-11-18T12:00:00Z",
            "result": {...}
        }
    ],
    "total": 42,
    "page": 1,
    "per_page": 20
}
```

### Backend ↔ Database

**User Query:**
```python
# ORM Query (SQLAlchemy)
from app.models.user import User
from sqlalchemy import select

result = await db.execute(
    select(User).where(User.email == email)
)
user = result.scalar_one_or_none()
```

**Blockchain Query:**
```python
# Get latest blocks
from app.models.block import Block

result = await db.execute(
    select(Block)
    .order_by(Block.index.desc())
    .limit(10)
)
blocks = result.scalars().all()
```

### Backend ↔ Redis

**Session Storage:**
```python
# Store session
await redis.setex(
    f"session:{user_id}",
    3600,  # 1 hour
    json.dumps({"user_id": user_id, "email": email})
)

# Retrieve session
session_data = await redis.get(f"session:{user_id}")
```

**WebSocket State:**
```python
# Publish event
await redis.publish(
    "prism:events",
    json.dumps({"type": "job_completed", "job_id": 123})
)

# Subscribe to events
pubsub = redis.pubsub()
await pubsub.subscribe("prism:events")
```

---

## Key Integration Points

### 1. OS → Prism Console
- User clicks "Prism Console" app in OS
- OS opens window with iframe/route to `/prism`
- Prism UI loads, shares auth token from OS
- Prism makes API calls to `/api/prism/*`

### 2. Prism → Backend API
- Prism fetches jobs: `GET /api/prism/jobs`
- Backend queries database via models
- Returns JSON response
- Prism renders in UI

### 3. Backend → Database
- Router receives request
- Service layer business logic
- ORM query via async session
- Results returned to router

### 4. Backend → Redis
- Session management
- WebSocket state
- Caching API responses
- Pub/sub for real-time events

### 5. Frontend → Documentation
- "Help" link in OS
- Opens new tab to `https://docs.blackroad.systems`
- MkDocs site served from GitHub Pages
- Searchable documentation

---

## Deployment Connections

### Development Environment

```
Developer Machine
├── Backend: http://localhost:8000
│   ├── OS: http://localhost:8000/
│   ├── Prism: http://localhost:8000/prism
│   └── API Docs: http://localhost:8000/api/docs
│
├── Docs: http://localhost:8001
│   └── mkdocs serve (port 8001)
│
├── PostgreSQL: localhost:5432 (via Docker)
└── Redis: localhost:6379 (via Docker)
```

### Production Environment

```
User Browser
     ↓
Cloudflare CDN (DNS + SSL)
     ↓
Railway Backend
├── FastAPI (port 8000)
├── PostgreSQL (Railway managed)
└── Redis (Railway managed)

GitHub Pages
└── Docs (codex-docs/ → gh-pages branch)
```

---

## Phase 2 vs Phase 3: Monorepo Evolution

### Phase 2 (Current): Monorepo

**All in `BlackRoad-Operating-System`:**
- ✅ Single source of truth
- ✅ Easy cross-component changes
- ✅ Simple CI/CD

### Phase 3 (Future): Multi-Repo

**When to split:**
- Team size > 10 developers
- Independent release cycles needed
- Different tech stacks emerging

**Potential split:**
```
blackroad-os-core         → Core runtime (Python)
blackroad-os-api          → Backend API (Python/FastAPI)
blackroad-os-web          → Frontend UI (JavaScript)
blackroad-os-prism        → Prism Console (JavaScript/Python)
blackroad-os-operator     → Worker engine (Python)
blackroad-os-docs         → Documentation (Markdown/MkDocs)
```

**Migration strategy:**
- Use `git subtree split` to preserve history
- Set up cross-repo CI coordination
- Implement versioned API contracts
- Maintain unified documentation

---

## Summary: How It All Connects

1. **User** visits `blackroad.systems`
2. **Cloudflare** resolves DNS, terminates SSL, proxies to Railway
3. **Railway** runs FastAPI backend
4. **Backend** serves static OS UI from `backend/static/`
5. **OS** boots in browser, renders Windows 95-style interface
6. **User** opens Prism Console app
7. **OS** loads `/prism` route (static Prism UI)
8. **Prism** makes API calls to `/api/prism/*`
9. **Backend** routes to `routers/prism.py`
10. **Router** calls service layer
11. **Service** queries database via models
12. **Database** returns data
13. **Service** returns to router
14. **Router** returns JSON to Prism
15. **Prism** renders data in UI
16. **User** sees job queue, metrics, events

**For documentation:**
1. **Developer** edits `codex-docs/docs/`
2. **Push** to main branch
3. **GitHub Actions** runs `mkdocs build`
4. **Deploys** to `gh-pages` branch
5. **GitHub Pages** serves at `blackboxprogramming.github.io/...`
6. **Cloudflare** CNAMEs `docs.blackroad.systems` to GitHub Pages
7. **User** visits `https://docs.blackroad.systems`

---

**Where AI meets the open road.** 🛣️

*Complete repository map showing all module connections and data flows.*