blackroad-operating-system/CLAUDE.md

CLAUDE.md - AI Assistant Guide for BlackRoad Operating System

Last Updated: 2025-11-18 Repository: BlackRoad-Operating-System Primary Language: Python (Backend), JavaScript (Frontend) Canonical Entry Point: backend/static/index.html served by FastAPI

---

Table of Contents

1. Repository Overview
2. Technology Stack
3. Repository Structure
4. Development Setup
5. Key Architectural Patterns
6. Development Workflows
7. Testing Practices
8. Deployment
9. Important Conventions
10. Common Tasks
11. Gotchas and Critical Notes

---

Repository Overview

BlackRoad Operating System is a nostalgic Windows 95-inspired web-based operating system interface that brings together AI orchestration, blockchain technology, social media, video streaming, and gaming. The project represents a complete AI-powered ecosystem with 200+ autonomous agents, extensive third-party integrations, and a unique blend of retro UI design with modern architecture.

Core Philosophy

• Agent-First: Humans orchestrate, agents execute
• Memory-Conscious: Everything is logged and retrievable
• Ledger-Aware: Critical actions are provable and tamper-evident
• Zero-Dependency Frontend: Vanilla JavaScript with no build process
• Cloud-Native: Infrastructure as software with Railway deployment

Project Vision

The "Big Kahuna" vision (see BLACKROAD_OS_BIG_KAHUNA_VISION.md) outlines an ambitious roadmap that includes:

• Multi-tier architecture with Lucidia (AI), Prism (orchestration), CloudWay (infra), RoadChain (blockchain), Vault (compliance), Quantum Lab (research), and MetaCity (worlds)
• 7 core pillars: Create, Build, Operate, Trade, Govern, Dream, Explore
• Complete suite of native applications replacing external tools

---

Technology Stack

Backend Stack

Core Framework:

• FastAPI 0.104.1 - Modern async web framework
• Uvicorn 0.24.0 - ASGI server with WebSocket support
• Pydantic 2.5.0 - Data validation and settings management
• SQLAlchemy 2.0.23 - ORM with async support

Databases:

• PostgreSQL - Production database (via psycopg2-binary, asyncpg)
• SQLite - Development/testing database (via aiosqlite)
• Alembic 1.12.1 - Database migrations

Caching & Sessions:

• Redis 5.0.1 - Session store, caching
• Hiredis 2.2.3 - Redis performance optimization

Authentication & Security:

• python-jose[cryptography] 3.3.0 - JWT handling
• passlib[bcrypt] 1.7.4 - Password hashing
• cryptography 41.0.7 - Encryption utilities
• ecdsa 0.18.0 - Elliptic curve cryptography

External Integrations:

• httpx 0.25.2, aiohttp 3.9.1 - Async HTTP clients
• boto3 1.29.7 - AWS S3
• stripe 7.8.0 - Payments
• sentry-sdk 1.39.1 - Error monitoring
• prometheus-client 0.19.0 - Metrics

Testing:

• pytest 7.4.3 - Testing framework
• pytest-asyncio 0.21.1 - Async support
• pytest-cov 4.1.0 - Coverage reporting

Frontend Stack

Primary Approach: Vanilla JavaScript (ES6+) with zero dependencies

Key Characteristics:

• No build process required
• No transpilation, bundling, or minification
• ~200KB uncompressed bundle size
• ~3,500 lines of well-documented code
• WCAG 2.1 compliant accessibility

Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge)

SDKs

Python SDK (sdk/python/):

• Python 3.8+ with type hints
• httpx for async requests
• Black, flake8, mypy for quality

TypeScript SDK (sdk/typescript/):

• TypeScript 5.3.3
• Axios 1.6.2 with retry logic
• Jest 29.7.0 for testing
• Dual CJS/ESM builds

---

Repository Structure

/home/user/BlackRoad-Operating-System/
├── backend/                    # FastAPI backend services
│   ├── app/
│   │   ├── main.py            # Main FastAPI application (33+ routers)
│   │   ├── config.py          # Pydantic settings
│   │   ├── database.py        # Database session management
│   │   ├── models/            # SQLAlchemy models
│   │   ├── routers/           # 33+ API endpoint routers
│   │   ├── services/          # Business logic layer
│   │   └── utils/             # Shared utilities
│   ├── static/                # **CANONICAL FRONTEND** served at /
│   │   ├── index.html         # Main OS interface
│   │   ├── js/                # JavaScript modules
│   │   └── assets/            # CSS, images, fonts
│   ├── tests/                 # Backend test suite
│   ├── requirements.txt       # Python dependencies
│   ├── Dockerfile             # Container definition
│   ├── docker-compose.yml     # Local dev stack
│   └── .env.example           # Environment template
│
├── blackroad-os/              # Legacy standalone UI (superseded by backend/static)
│   ├── index.html
│   ├── js/
│   └── assets/
│
├── agents/                    # 200+ AI agent ecosystem
│   ├── base/                  # Core agent framework
│   │   ├── agent.py           # Base agent class
│   │   ├── executor.py        # Execution engine
│   │   └── registry.py        # Agent discovery
│   ├── categories/            # 10 agent categories
│   │   ├── devops/
│   │   ├── engineering/
│   │   ├── data/
│   │   ├── security/
│   │   ├── finance/
│   │   ├── creative/
│   │   ├── business/
│   │   ├── research/
│   │   ├── web/
│   │   └── ai_ml/
│   ├── templates/             # Agent templates
│   └── tests/                 # Agent tests
│
├── sdk/                       # Client SDKs
│   ├── python/                # Python SDK (v0.1.0)
│   └── typescript/            # TypeScript SDK (v0.1.0)
│
├── docs/                      # Architecture documentation
├── infra/                     # Infrastructure configs
├── ops/                       # Operations scripts
├── scripts/                   # Utility scripts
│   ├── railway/               # Railway deployment helpers
│   └── run_backend_tests.sh  # Test runner
│
├── .github/workflows/         # CI/CD pipelines
│   ├── ci.yml                 # HTML/JS validation
│   ├── backend-tests.yml      # Backend tests
│   ├── deploy.yml             # GitHub Pages deploy
│   ├── railway-deploy.yml     # Railway backend deploy
│   └── railway-automation.yml # Env validation
│
├── railway.toml               # Railway deployment config
├── railway.json               # Railway service definitions
└── [Documentation files]
    ├── README.md
    ├── BLACKROAD_OS_BIG_KAHUNA_VISION.md
    ├── CODEBASE_STATUS.md
    ├── SECURITY.md
    ├── API_INTEGRATIONS.md
    └── CLAUDE.md (this file)

Critical Path Files

Entry Points:

• Backend: backend/app/main.py:8 (FastAPI app)
• Frontend: backend/static/index.html (canonical UI)
• Agents: agents/base/agent.py:1 (base agent class)

Configuration:

• backend/app/config.py:1 - All settings (Pydantic)
• backend/.env.example - Environment template
• railway.toml - Railway deployment settings

Database:

• backend/app/database.py:1 - Session management
• backend/app/models/ - All ORM models

---

Development Setup

Local Backend Development

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file from template
cp .env.example .env
# Edit .env with your settings (SECRET_KEY, DATABASE_URL, etc.)

# Run development server
uvicorn app.main:app --reload

# Server runs at http://localhost:8000
# Frontend UI at http://localhost:8000/
# API docs at http://localhost:8000/api/docs

Using Docker Compose (Recommended)

cd backend

# Start all services (Postgres, Redis, FastAPI, Adminer)
docker-compose up

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Services:

• FastAPI: http://localhost:8000
• PostgreSQL: localhost:5432
• Redis: localhost:6379
• Adminer (DB UI): http://localhost:8080

Frontend Development

Option 1: Via Backend (Recommended)

# Start backend as above
# Visit http://localhost:8000/
# Frontend is served from backend/static/

Option 2: Direct File

cd backend/static
# Open index.html in browser
# Note: API calls will fail without backend running

SDK Development

Python SDK:

cd sdk/python
pip install -e .
pytest

TypeScript SDK:

cd sdk/typescript
npm install
npm run build
npm test

---

Key Architectural Patterns

1. Multi-Tier Architecture

┌─────────────────────────────────┐
│  Frontend (Vanilla JS)          │
│  Zero dependencies, event-driven│
└─────────────────────────────────┘
              ↕ HTTP/WebSocket
┌─────────────────────────────────┐
│  Backend (FastAPI)              │
│  REST API + WebSocket           │
└─────────────────────────────────┘
              ↕
┌─────────────────────────────────┐
│  Agent Layer (200+ agents)      │
│  Autonomous execution           │
└─────────────────────────────────┘
              ↕
┌───────────┬──────────┬──────────┐
│ Postgres  │  Redis   │ External │
│ Database  │  Cache   │  APIs    │
└───────────┴──────────┴──────────┘

2. Event-Driven Frontend

Event Bus (backend/static/js/os.js):

• Global event system for inter-app communication
• Built-in events: os:boot, window:created, theme:changed
• Custom event support for loose coupling

Example:

// Emit event
window.OS.emit('data:updated', { source: 'dashboard' });

// Listen for event
window.OS.on('data:updated', (data) => {
    console.log('Data updated from:', data.source);
});

3. Async-First Backend

All operations are async:

# Database operations
@router.get("/users")
async def get_users(db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(User))
    return result.scalars().all()

# External API calls
async with httpx.AsyncClient() as client:
    response = await client.get(url)

4. Repository Pattern

Separation of concerns:

• Models (app/models/): Database schema
• Routers (app/routers/): API endpoints
• Services (app/services/): Business logic
• Utils (app/utils/): Shared helpers

5. Agent Pattern

Base agent with lifecycle hooks:

class Agent:
    async def initialize(self):
        """Setup before execution"""

    async def execute(self):
        """Main execution logic"""

    async def cleanup(self):
        """Cleanup after execution"""

    async def on_error(self, error):
        """Error handling"""

6. Component-Based Frontend

15 reusable UI components in backend/static/js/components.js:

• Factory pattern for consistent API
• Accessibility built-in (WCAG 2.1)
• No external dependencies

Example:

// Create a card component
const card = Components.Card({
    title: 'Dashboard',
    content: 'Hello World',
    footer: 'Updated 5 min ago'
});

document.body.appendChild(card);

---

Development Workflows

Git Workflow

Branch Strategy:

• main - Production branch (protected)
• claude/* - AI assistant branches (auto-created)
• codex/*, copilot/* - Other AI branches
• feature/*, fix/*, docs/* - Human developer branches

Current Branch: claude/claude-md-mi3wes6waq9fnfmt-012kKpHTPTV5D9YBFB7ufuwy

Commit Guidelines:

# Good commit messages
git commit -m "Add user authentication endpoint"
git commit -m "Fix CORS issue in API middleware"
git commit -m "Update README with Docker instructions"

# Avoid
git commit -m "updates"
git commit -m "fix stuff"

CI/CD Pipeline

GitHub Actions (7 workflows):

1. CI (.github/workflows/ci.yml):

   • HTML validation
   • JavaScript syntax checking
   • Security scanning
   • Runs on: push, PR to main

2. Backend Tests (.github/workflows/backend-tests.yml):

   • Python setup
   • Dependency installation
   • pytest with coverage
   • Runs on: push, PR to main

3. Deploy to GitHub Pages (.github/workflows/deploy.yml):

   • Bundles backend/static/
   • Deploys frontend to Pages
   • Runs on: push to main

4. Railway Deploy (.github/workflows/railway-deploy.yml):

   • Deploys backend to Railway
   • Runs migrations
   • Health check validation

5. Railway Automation (.github/workflows/railway-automation.yml):

   • Validates env template
   • Checks secret sync
   • Detects config drift

Environment Management

Configuration Hierarchy:

1. .env file (gitignored, highest priority)
2. Railway environment variables (production)
3. backend/app/config.py defaults (fallback)

Required Variables (see backend/.env.example):

# Core
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db
REDIS_URL=redis://host:6379/0
SECRET_KEY=your-secret-key-here

# JWT
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# CORS
ALLOWED_ORIGINS=http://localhost:8000,https://yourdomain.com

# Blockchain
WALLET_MASTER_KEY=your-wallet-master-key

# AI
OPENAI_API_KEY=sk-...

# Cloud (optional)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

# Payment (optional)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...

# Communication (optional)
SMTP_HOST=smtp.gmail.com
TWILIO_ACCOUNT_SID=...
SLACK_BOT_TOKEN=...

Validation:

# Validate environment template
python scripts/railway/validate_env_template.py

---

Testing Practices

Backend Testing

Framework: pytest with async support

Test Structure:

backend/tests/
├── conftest.py              # Shared fixtures
├── test_auth.py             # Authentication
├── test_blockchain.py       # Blockchain
├── test_dashboard.py        # Dashboard
├── test_miner.py            # Mining
├── test_vscode_router.py    # VSCode integration
└── test_api_integrations.py # External APIs

Running Tests:

# Via helper script (recommended)
bash scripts/run_backend_tests.sh

# Manual
cd backend
source .venv-tests/bin/activate
pytest -v --maxfail=1

# With coverage
pytest --cov=app --cov-report=html

Test Configuration (backend/tests/conftest.py):

• Isolated SQLite test database
• Automatic setup/teardown
• Fixtures: db_session, client, test_user, auth_headers

Example Test:

import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_create_user(client: AsyncClient):
    response = await client.post(
        "/api/auth/register",
        json={
            "email": "test@example.com",
            "password": "secure123"
        }
    )
    assert response.status_code == 200
    data = response.json()
    assert data["email"] == "test@example.com"

Frontend Testing

Approach: CI-based validation (no unit tests currently)

Validation Steps:

1. DOCTYPE validation
2. Tag matching (html, head, body, script)
3. JavaScript syntax checking
4. Security checks (eval, innerHTML XSS)

Agent Testing

Test Suite (agents/tests/test_agents.py):

• Base agent functionality
• Execution lifecycle
• Error handling
• Retry logic
• Hook system

---

Deployment

Railway (Backend)

Configuration (railway.toml):

[build]
builder = "DOCKERFILE"
dockerfilePath = "backend/Dockerfile"

[deploy]
startCommand = "cd backend && uvicorn app.main:app --host 0.0.0.0 --port $PORT"
healthcheck.path = "/health"

Deployment Steps:

1. Push to main branch
2. GitHub Action triggers Railway deploy
3. Railway builds Docker image
4. Runs Alembic migrations
5. Starts FastAPI server
6. Health check validation
7. Traffic cutover

Manual Deploy:

# Install Railway CLI
curl -fsSL https://railway.app/install.sh | sh

# Login
railway login

# Deploy
railway up

GitHub Pages (Frontend)

Deployment:

• Automatic on push to main
• Workflow bundles backend/static/
• Publishes to GitHub Pages
• Frontend only (backend on Railway)

Manual Deploy:

# Copy static files
mkdir -p dist
cp -r backend/static/* dist/

# Upload to Pages (via GitHub UI or gh CLI)
gh pages deploy dist/

Docker

Build Image:

cd backend
docker build -t blackroad-os:latest .

Run Container:

docker run -p 8000:8000 \
  -e DATABASE_URL=postgresql://... \
  -e REDIS_URL=redis://... \
  -e SECRET_KEY=... \
  blackroad-os:latest

---

Important Conventions

Code Style

Python:

• Follow PEP 8
• Use type hints
• Async/await for I/O operations
• Pydantic for validation
• Docstrings for public functions

JavaScript:

• ES6+ syntax
• No semicolons (consistent omission)
• camelCase for variables
• PascalCase for classes/components
• 2-space indentation

File Organization

Backend Router Pattern:

# app/routers/example.py
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from ..database import get_db

router = APIRouter(prefix="/api/example", tags=["Example"])

@router.get("/")
async def get_items(db: AsyncSession = Depends(get_db)):
    """Get all items"""
    # Implementation

Frontend App Pattern:

// backend/static/js/apps/example.js
window.Apps = window.Apps || {};

window.Apps.Example = {
    init() {
        // Initialize app
    },

    render() {
        // Render UI
    },

    handleEvent(event) {
        // Handle events
    }
};

Database Migrations

Create Migration:

cd backend
alembic revision --autogenerate -m "Add user table"

Run Migrations:

alembic upgrade head

Rollback:

alembic downgrade -1

API Design

RESTful Patterns:

• GET /api/resource - List all
• GET /api/resource/{id} - Get one
• POST /api/resource - Create
• PUT /api/resource/{id} - Update
• DELETE /api/resource/{id} - Delete

Response Format:

# Success
{"data": [...], "message": "Success"}

# Error
{"detail": "Error message"}

# Pagination
{
    "data": [...],
    "page": 1,
    "per_page": 20,
    "total": 100
}

Security

Authentication:

from fastapi import Depends
from ..utils.auth import get_current_user

@router.get("/protected")
async def protected_route(
    current_user = Depends(get_current_user)
):
    return {"user": current_user}

Input Validation:

from pydantic import BaseModel, EmailStr

class UserCreate(BaseModel):
    email: EmailStr
    password: str

@router.post("/users")
async def create_user(user: UserCreate):
    # user is validated

Avoid:

• eval() in JavaScript
• innerHTML with user input
• SQL string concatenation
• Hardcoded secrets

---

Common Tasks

Adding a New API Endpoint

1. Create router (or add to existing):

# backend/app/routers/my_router.py
from fastapi import APIRouter

router = APIRouter(prefix="/api/myrouter", tags=["MyRouter"])

@router.get("/")
async def my_endpoint():
    return {"message": "Hello"}

2. Register in main.py:

# backend/app/main.py
from .routers import my_router

app.include_router(my_router.router)

3. Add tests:

# backend/tests/test_my_router.py
@pytest.mark.asyncio
async def test_my_endpoint(client):
    response = await client.get("/api/myrouter/")
    assert response.status_code == 200

Adding a New Frontend App

1. Create app file:

// backend/static/js/apps/myapp.js
window.Apps = window.Apps || {};

window.Apps.MyApp = {
    init() {
        console.log('MyApp initialized');
    },

    render() {
        return `
            <div class="myapp">
                <h1>My App</h1>
            </div>
        `;
    }
};

2. Add to registry (backend/static/js/registry.js):

{
    id: 'myapp',
    name: 'My App',
    icon: '🎨',
    category: 'create',
    component: Apps.MyApp
}

3. Add desktop icon (backend/static/index.html):

<div class="icon" ondblclick="openWindow('myapp')">
    <div class="icon-image">🎨</div>
    <div class="icon-label">My App</div>
</div>

Adding a Database Model

1. Create model:

# backend/app/models/mymodel.py
from sqlalchemy import Column, Integer, String
from ..database import Base

class MyModel(Base):
    __tablename__ = "mymodel"

    id = Column(Integer, primary_key=True)
    name = Column(String, nullable=False)

2. Import in models/init.py:

from .mymodel import MyModel

3. Create migration:

alembic revision --autogenerate -m "Add mymodel table"
alembic upgrade head

Adding an Agent

1. Create agent file:

# agents/categories/mycategory/my_agent.py
from agents.base.agent import Agent

class MyAgent(Agent):
    def __init__(self):
        super().__init__(
            name="MyAgent",
            version="1.0.0",
            category="mycategory"
        )

    async def execute(self):
        # Agent logic
        return {"status": "success"}

2. Register in category init.py:

from .my_agent import MyAgent

3. Add tests:

# agents/tests/test_my_agent.py
import pytest
from agents.categories.mycategory.my_agent import MyAgent

@pytest.mark.asyncio
async def test_my_agent():
    agent = MyAgent()
    result = await agent.execute()
    assert result["status"] == "success"

---

Gotchas and Critical Notes

🚨 Critical Issues

1. Frontend Duplication:

   • Canonical: backend/static/index.html (served by FastAPI)
   • Legacy: blackroad-os/index.html (superseded, may drift)
   • Action: Always edit backend/static/, not blackroad-os/

2. Environment Variables:

   • Missing SECRET_KEY will break JWT auth
   • Missing DATABASE_URL defaults to SQLite (may hide issues)
   • Missing REDIS_URL disables caching
   • Action: Always use .env.example as template

3. Database Migrations:

   • Startup auto-creates tables via Base.metadata.create_all()
   • This can cause schema drift with Alembic
   • Action: Use Alembic for all schema changes in production

4. CORS Configuration:

   • ALLOWED_ORIGINS must include frontend domain
   • Missing origins will block API calls
   • Action: Update .env for each environment

5. Integration Routers:

   • Some routers (Stripe, Twilio, etc.) may be stubs
   • Deployment without API keys will fail
   • Action: Validate integration status before use

⚠️ Common Pitfalls

1. Async/Await:

   • Forgetting await on async functions
   • Mixing sync/async code
   • Fix: All DB and HTTP calls must be awaited

2. Database Sessions:

   • Not closing sessions properly
   • Sharing sessions across requests
   • Fix: Use Depends(get_db) for automatic session management

3. Frontend API Calls:

   • Hardcoded localhost URLs
   • Not handling errors
   • Fix: Use relative URLs (/api/...), add error handling

4. Agent Execution:

   • Long-running agents blocking event loop
   • No timeout handling
   • Fix: Use timeouts, run in background tasks

5. Static Files:

   • Editing blackroad-os/ instead of backend/static/
   • Caching issues after updates
   • Fix: Always edit canonical location, hard refresh browser

🔍 Debugging Tips

Backend Debugging:

# Add logging
import logging
logger = logging.getLogger(__name__)
logger.info("Debug message")

# Use debugger
import pdb; pdb.set_trace()

# Check database
# Visit http://localhost:8080 (Adminer) when using docker-compose

Frontend Debugging:

// Console logging
console.log('Debug:', data);

// Network tab (Chrome DevTools)
// Check API calls, responses, timing

// Event debugging
window.OS.on('*', (event, data) => {
    console.log('Event:', event, data);
});

Agent Debugging:

# Enable debug logging
agent.logger.setLevel(logging.DEBUG)

# Check execution logs
result = await agent.execute()
print(agent.get_logs())

📝 Best Practices

1. Always read before writing:

   • Use Read tool before Edit/Write
   • Understand context before changes

2. Test locally before pushing:

   • Run backend tests: bash scripts/run_backend_tests.sh
   • Test frontend: Open in browser, check console
   • Validate env: python scripts/railway/validate_env_template.py

3. Keep documentation updated:

   • Update CLAUDE.md when patterns change
   • Document new integrations in API_INTEGRATIONS.md
   • Update README.md for user-facing changes

4. Security first:

   • Never commit .env files
   • Validate all user input
   • Use parameterized SQL queries
   • Sanitize HTML output

5. Performance considerations:

   • Use async for I/O operations
   • Cache expensive computations
   • Paginate large result sets
   • Monitor database query performance

---

Quick Reference

Key Files to Know

File	Purpose	Location
Main app	FastAPI application	backend/app/main.py:8
Settings	Environment config	backend/app/config.py:1
Database	Session management	backend/app/database.py:1
Frontend	OS interface	backend/static/index.html
OS core	Window manager	backend/static/js/os.js
Components	UI library	backend/static/js/components.js
Agent base	Agent framework	agents/base/agent.py:1
Test runner	Backend tests	scripts/run_backend_tests.sh

Useful Commands

# Start backend
cd backend && uvicorn app.main:app --reload

# Start with Docker
cd backend && docker-compose up

# Run tests
bash scripts/run_backend_tests.sh

# Create migration
cd backend && alembic revision --autogenerate -m "message"

# Run migration
cd backend && alembic upgrade head

# Validate environment
python scripts/railway/validate_env_template.py

# Deploy to Railway
railway up

# View logs (Railway)
railway logs

# Check API docs
# Visit http://localhost:8000/api/docs

Getting Help

• Documentation: Check docs/ folder
• Vision: Read BLACKROAD_OS_BIG_KAHUNA_VISION.md
• Status: Check CODEBASE_STATUS.md
• Security: Review SECURITY.md
• API Reference: http://localhost:8000/api/docs (when running)

---

Conclusion

This guide provides the essential knowledge for AI assistants working on BlackRoad Operating System. The project combines nostalgic UI design with modern architecture, creating a unique web-based operating system experience.

Remember:

• Frontend lives in backend/static/ (not blackroad-os/)
• Backend is fully async with FastAPI
• Zero-dependency frontend with vanilla JavaScript
• 200+ agents in modular categories
• Comprehensive testing with pytest
• Railway for backend, GitHub Pages for frontend
• Always validate environment variables
• Security and accessibility are priorities

Happy coding! 🛣️

---

This document is maintained by AI assistants working on the codebase. Keep it updated as patterns and practices evolve.