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](#repository-overview)
2. [Technology Stack](#technology-stack)
3. [Repository Structure](#repository-structure)
4. [Development Setup](#development-setup)
5. [Key Architectural Patterns](#key-architectural-patterns)
6. [Development Workflows](#development-workflows)
7. [Testing Practices](#testing-practices)
8. [Deployment](#deployment)
9. [Important Conventions](#important-conventions)
10. [Common Tasks](#common-tasks)
11. [Gotchas and Critical Notes](#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

```bash
# 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)

```bash
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)
```bash
# Start backend as above
# Visit http://localhost:8000/
# Frontend is served from backend/static/
```

**Option 2: Direct File**
```bash
cd backend/static
# Open index.html in browser
# Note: API calls will fail without backend running
```

### SDK Development

**Python SDK**:
```bash
cd sdk/python
pip install -e .
pytest
```

**TypeScript SDK**:
```bash
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**:
```javascript
// 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**:
```python
# 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**:
```python
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**:
```javascript
// 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**:
```bash
# 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`):
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```python
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`):
```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**:
```bash
# 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**:
```bash
# 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**:
```bash
cd backend
docker build -t blackroad-os:latest .
```

**Run Container**:
```bash
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**:
```python
# 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**:
```javascript
// 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**:
```bash
cd backend
alembic revision --autogenerate -m "Add user table"
```

**Run Migrations**:
```bash
alembic upgrade head
```

**Rollback**:
```bash
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**:
```python
# Success
{"data": [...], "message": "Success"}

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

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

### Security

**Authentication**:
```python
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**:
```python
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):
```python
# 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**:
```python
# backend/app/main.py
from .routers import my_router

app.include_router(my_router.router)
```

3. **Add tests**:
```python
# 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**:
```javascript
// 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`):
```javascript
{
    id: 'myapp',
    name: 'My App',
    icon: '🎨',
    category: 'create',
    component: Apps.MyApp
}
```

3. **Add desktop icon** (`backend/static/index.html`):
```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**:
```python
# 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**:
```python
from .mymodel import MyModel
```

3. **Create migration**:
```bash
alembic revision --autogenerate -m "Add mymodel table"
alembic upgrade head
```

### Adding an Agent

1. **Create agent file**:
```python
# 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**:
```python
from .my_agent import MyAgent
```

3. **Add tests**:
```python
# 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**:
```python
# 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**:
```javascript
// 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**:
```python
# 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

```bash
# 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.*