blackroad-operating-system/BLACKROAD_OS_REPO_MAP.md

BlackRoad OS Repository Map

Version: Phase 2 Scaffold Last Updated: 2025-11-18 Branch: claude/os-phase2-scaffold-01LKeSDWFNBtXhhsV2xMbM4T

Overview

This document maps all Phase 2 scaffolded components within the BlackRoad-Operating-System monorepo.

Repository Structure

All components are housed in the single monorepo:

• Repo: blackboxprogramming/BlackRoad-Operating-System
• Approach: Monorepo with modular services
• Future: May extract to separate repos if needed

---

Component Map

1. Backend API

Property	Value
Location	backend/
Language	Python (FastAPI)
New Endpoints	/api/system/version, /api/system/config/public, /api/system/os/state
Tests	backend/tests/test_system.py
CI Workflow	.github/workflows/backend-tests.yml
Run Command	cd backend && uvicorn app.main:app --reload
API Docs	http://localhost:8000/api/docs

Key Features:

• 30+ existing API routers
• New system endpoints for OS integration
• JWT authentication
• PostgreSQL + Redis integration

How to Run:

cd backend
uvicorn app.main:app --reload

---

2. Core OS Runtime

Property	Value
Location	core_os/
Language	Python
Key Files	models.py, state.py, adapters/api_client.py
Tests	core_os/tests/
CI Workflow	.github/workflows/core-os-tests.yml
README	core_os/README.md

Key Features:

• UserSession, Window, OSState models
• State management functions (open_window, close_window, etc.)
• Backend API adapter for communication
• In-memory state storage (future: Redis/PostgreSQL)

How to Run:

from core_os import get_initial_state, open_window
state = get_initial_state()
state = open_window("notepad")

---

3. Operator Engine

Property	Value
Location	operator_engine/
Language	Python
Key Files	jobs.py, scheduler.py, server.py
Tests	operator_engine/tests/
CI Workflow	.github/workflows/operator-tests.yml
Run Command	python -m operator_engine.server
README	operator_engine/README.md

Key Features:

• In-memory job registry with example jobs
• Simple interval-based scheduler
• Optional HTTP API on port 8001
• Job lifecycle management (pending, running, completed, failed)

How to Run:

# As a library
python -c "from operator_engine import Scheduler; print('OK')"

# As a service
python -m operator_engine.server
# Visit http://localhost:8001/docs

---

4. Web Client (Pocket OS)

Property	Value
Location	backend/static/ (primary), web-client/ (docs)
Language	JavaScript (Vanilla), HTML, CSS
New File	backend/static/js/core-os-client.js
CI Workflow	.github/workflows/ci.yml (HTML/JS validation)
Run Command	Served by backend at http://localhost:8000/
README	web-client/README.md

Key Features:

• Windows 95-style desktop UI
• New CoreOSClient class for API integration
• Event-driven architecture
• Zero dependencies

How to Run:

# Start backend (serves frontend at /)
cd backend
uvicorn app.main:app --reload

# Visit http://localhost:8000/

New in Phase 2:

await window.coreOS.initialize();
const version = await window.coreOS.getVersion();
console.log('OS Version:', version.version);

---

5. Prism Console

Property	Value
Location	prism-console/
Language	HTML, CSS, JavaScript
Entry Point	prism-console/index.html
Run Command	cd prism-console && python -m http.server 8080
README	prism-console/README.md

Key Features:

• Modern dark-themed admin UI
• Multi-tab navigation (Overview, Jobs, Agents, Logs, System)
• System metrics dashboard
• Backend API integration
• Auto-refresh every 30 seconds

How to Run:

# Standalone
cd prism-console
python -m http.server 8080
# Visit http://localhost:8080/

# Or integrate with backend (future)
# Visit http://localhost:8000/prism

---

6. Documentation (Codex)

Property	Value
Location	codex-docs/
Technology	MkDocs + Material theme
Config	codex-docs/mkdocs.yml
Source	codex-docs/docs/
CI Workflow	.github/workflows/docs-build.yml
Run Command	cd codex-docs && mkdocs serve
README	codex-docs/README.md

Key Features:

• Complete system documentation
• Architecture guides
• Component documentation
• API reference
• Development guides

How to Run:

cd codex-docs
pip install mkdocs mkdocs-material mkdocstrings
mkdocs serve
# Visit http://localhost:8000

---

CI/CD Workflows

All workflows in .github/workflows/:

Workflow	Triggers	Tests	Artifact
backend-tests.yml	backend/* changes	Backend API + system endpoints	Test results
core-os-tests.yml	core_os/* changes	Core OS models + state management	Test results
operator-tests.yml	operator_engine/* changes	Operator jobs + scheduler	Test results
docs-build.yml	codex-docs/* changes	MkDocs build	Documentation site
ci.yml	HTML/JS changes	HTML/JS validation	-

---

Integration Flow

User Request Flow

User Browser
    ↓
Web Client (Pocket OS)
    ├── core-os-client.js
    ├── Calls: GET /api/system/version
    └── Calls: GET /api/system/os/state
    ↓
Backend API (FastAPI)
    ├── /api/system/version → system.py router
    ├── /api/system/config/public → system.py router
    └── /api/system/os/state → system.py router (stub)
    ↓
Core OS Runtime (future integration)
    ├── get_current_state()
    └── Returns OSState with windows, desktop, etc.

Admin/Ops Flow

Admin Browser
    ↓
Prism Console
    ├── prism.js
    ├── Calls: GET /api/system/version
    ├── Calls: GET /api/system/config/public
    └── Calls: GET /api/operator/jobs (future)
    ↓
Backend API
    ↓
Operator Engine (future integration)
    ├── list_jobs()
    └── execute_job(job_id)

---

Request Path Examples

Example 1: Get System Version

Client Code:

const version = await window.coreOS.getVersion();

HTTP Request:

GET /api/system/version

Backend Route:

# backend/app/routers/system.py
@router.get("/version")
async def get_version():
    return {
        "version": settings.APP_VERSION,
        "build_time": datetime.utcnow().isoformat(),
        "env": settings.ENVIRONMENT,
    }

Response:

{
  "version": "1.0.0",
  "build_time": "2025-11-18T12:00:00",
  "env": "development",
  "git_sha": "abc12345"
}

---

Example 2: Get Public Config

Client Code:

const config = await window.coreOS.getPublicConfig();

HTTP Request:

GET /api/system/config/public

Response:

{
  "environment": "development",
  "app_name": "BlackRoad Operating System",
  "version": "1.0.0",
  "features": {
    "blockchain_enabled": true,
    "ai_agents_enabled": true,
    "video_streaming_enabled": true
  },
  "limits": {
    "max_upload_size_mb": 100,
    "session_timeout_minutes": 60
  },
  "external_services": {
    "github_integration": true,
    "stripe_enabled": false,
    "openai_enabled": true
  }
}

---

Example 3: Initialize OS (Client-side)

Client Code:

const result = await window.coreOS.initialize();
console.log('Version:', result.version);
console.log('Config:', result.config);
console.log('State:', result.state);

Makes 3 parallel requests:

1. GET /api/system/version
2. GET /api/system/config/public
3. GET /api/system/os/state

---

Testing Each Component

Backend API

cd backend
pytest tests/test_system.py -v

Core OS

pytest core_os/tests/ -v

Operator Engine

pytest operator_engine/tests/ -v

Web Client

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

# Open browser: http://localhost:8000/
# Open console: Should see "Core OS Client loaded (v0.1.0)"
# Run: await window.coreOS.initialize()

Prism Console

cd prism-console
python -m http.server 8080

# Visit http://localhost:8080/
# Should see system metrics dashboard

Documentation

cd codex-docs
mkdocs build
# Check for errors in build output

---

File Count Summary

Component	Files Created	Tests	CI Workflows
Backend API	1 new router	1 test file	Existing
Core OS	6 files	2 test files	1 new workflow
Operator Engine	7 files	2 test files	1 new workflow
Web Client	2 files	Manual	Existing
Prism Console	4 files	Manual	None yet
Documentation	10+ files	Build test	1 new workflow

Total New Files: ~30+ Total New Tests: 5 test files Total New Workflows: 3 CI workflows

---

Environment Variables

All modules share these environment variables (set in backend/.env):

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

# Application
APP_NAME="BlackRoad Operating System"
APP_VERSION="1.0.0"
ENVIRONMENT=development

# Operator
SCHEDULER_INTERVAL_SECONDS=60
MAX_CONCURRENT_JOBS=5

# External (optional)
GITHUB_TOKEN=...
OPENAI_API_KEY=...
STRIPE_SECRET_KEY=...

---

Next Steps (Post-PR)

1. Merge PR - Review and merge this scaffold
2. Deploy to Railway - Test in production
3. Integrate Core OS - Connect backend API to core_os module
4. Enable Prism Route - Serve Prism at /prism from backend
5. Add WebSocket - Real-time state sync
6. Production Jobs - Replace stub jobs with real ones
7. Deploy Docs - Publish Codex to GitHub Pages

---

Troubleshooting

Backend won't start

# Check dependencies
pip install -r backend/requirements.txt

# Check database
# Ensure DATABASE_URL is set

# Check ports
# Ensure port 8000 is available

Tests failing

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run with verbose output
pytest -v --tb=short

Docs won't build

# Install MkDocs
pip install mkdocs mkdocs-material mkdocstrings

# Build with strict mode
cd codex-docs
mkdocs build --strict

---

Repository Summary

Monorepo: blackboxprogramming/BlackRoad-Operating-System Branch: claude/os-phase2-scaffold-01LKeSDWFNBtXhhsV2xMbM4T Components: 6 modules (API, Core OS, Operator, Web, Prism, Docs) New Code: ~3,000 lines (Python + JavaScript + HTML + Markdown) Tests: 5 test suites with 15+ tests CI: 3 new workflows + 4 existing Documentation: 10+ pages in MkDocs

---

Phase 2 Scaffold Complete! Ready for Alexa's review. 🚀