blackroad-operating-system/docs/architecture

BlackRoad OS Architecture Overview

BlackRoad OS combines the Pocket OS front-end, a Python backend, and deployment infrastructure across Railway, Cloudflare, and GitHub Actions. This document captures the high-level layout, the next build milestones, and the prompts/processes needed to keep contributors and agents aligned.

Repository Layout (proposed)

/
  backend/             # API, workers, models, tests
  frontend/            # Pocket OS UI
  apps/                # Modular OS applications (planned)
  infra/               # Deployment, DNS, automation configs
    env/               # Environment variable source of truth
  docs/                # Architecture, onboarding, specs

Use this as the north-star layout when moving files or adding new components so tooling and contributors can find things quickly.

Current System

• Frontend: Pocket OS UI deployed via Railway static hosting with Cloudflare in front.
• Backend: Python service (FastAPI/Flask) deployed on Railway with /health available for smoke checks.
• CI/CD: GitHub Actions building and deploying to Railway; DNS managed via Cloudflare/GoDaddy.

Next Three Moves (execution-focused)

1. Stabilize the foundation

   • Refine the directory structure above; group backend code into app/api, app/models, app/utils, app/workers, and collect tests under backend/tests.
   • Centralize environment variables under infra/env/ENVIRONMENT_MAP.md and sync to Railway, GitHub Actions, and Cloudflare.
   • Maintain a single architectural source of truth (this file) to reduce context churn for agents.

2. Turn the OS into an OS

   • Introduce a pluggable app system under /apps/<app-name> with a manifest.json and optional index.js/api.js entrypoints.
   • Persist user state (open windows, layout, theme, installed apps, agent console state) via localStorage initially, with a path to backend storage.
   • Build an Agent Panel so Lucidia, Cece, Codex, Silas, etc. appear as processes inside the OS.

3. Harden deployments

   • Split CI pipelines so backend and frontend deploy independently; include Cloudflare cache invalidation.
   • Add smoke/health checks (backend /health, frontend /) gated in the pipeline.
   • Define fallback routing: if Railway is unavailable, serve from GitHub Pages; otherwise serve backend static as a last resort.

Visual Identity (priority)

Lock in the OS look-and-feel early:

• Neon spectrum palette, window chrome, typography, animation timing, and a short boot sequence.
• Keep these tokens centralized (e.g., a theme module in frontend/src/systems/theme).

Agent Kernel Concept

A lightweight kernel to orchestrate agents inside the OS:

/kernel/
  agent_registry.js
  message_bus.js
  process_scheduler.js

Agents register with the kernel and render inside the Agent Panel for observability and control.

Prompt for Scaffolding Agents

When onboarding new AI agents, provide this file plus:

• The environment map (infra/env/ENVIRONMENT_MAP.md).
• The current CI/CD pipeline summary.
• The pluggable app spec (once created).

This reduces hallucinations and keeps responses grounded in the actual architecture.