mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 04:57:15 -05:00
67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
# 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.
|