8.4 KiB
Welcome to BlackRoad OS Codex
Version: 0.1.0 (Phase 2 Scaffold) Last Updated: 2025-11-18
What is BlackRoad OS?
BlackRoad OS is a nostalgic Windows 95-inspired web-based operating system that brings together AI orchestration, blockchain technology, social media, video streaming, and gaming into a unified ecosystem.
Key Features
- 🪟 Windows 95 UI - Nostalgic desktop experience in your browser
- 🤖 208 AI Agents - Autonomous agents across 10 categories
- ⛓️ RoadChain - Tamper-evident blockchain ledger
- ⚡ Prism Console - Admin and observability dashboard
- 🧠 Lucidia Layer - Multi-model AI orchestration (Phase 2)
- 🌍 MetaCity - Virtual worlds and experiences (Phase 3)
Architecture Overview
BlackRoad OS is built on a 7-layer architecture:
Layer 7: User Experience (Domains & Landing Pages)
Layer 6: Application Layer (Pocket OS, Native Apps)
Layer 5: API Gateway & Routing (FastAPI)
Layer 4: Orchestration & Intelligence (Lucidia, Prism, Operator)
Layer 3: Data & State (PostgreSQL, Redis, RoadChain, Vault)
Layer 2: Compute & Infrastructure (Railway, DigitalOcean, Cloudflare Workers)
Layer 1: DNS & CDN (Cloudflare)
Quick Links
- Architecture Guide - Understand the system design
- Components Overview - Explore each module
- Getting Started - Start developing
- API Reference - Explore the API
Phase 2 Scaffold Status
| Module | Status | Description |
|---|---|---|
| Backend API | ✅ Complete | FastAPI with system endpoints |
| Core OS Runtime | ✅ Complete | State management and models |
| Operator Engine | ✅ Complete | Job scheduling and orchestration |
| Web Client | ✅ Enhanced | Pocket OS with Core OS client |
| Prism Console | ✅ Complete | Admin dashboard UI |
| Documentation | ✅ Complete | MkDocs-based Codex |
Repository Structure
BlackRoad-Operating-System/
├── backend/ # FastAPI backend
├── core_os/ # Core OS runtime (NEW)
├── operator_engine/ # Operator engine (NEW)
├── prism-console/ # Prism admin UI (NEW)
├── web-client/ # Web client docs (NEW)
├── codex-docs/ # This documentation (NEW)
├── agents/ # 208 AI agents
├── docs/ # Legacy docs
└── README.md
Next Steps
- Explore the Architecture - Read the Architecture Guide
- Set Up Locally - Follow the Local Setup Guide
- Review Modules - Understand each Component
- Try the API - Check out the API Reference
Vision
The ultimate goal is to create a complete AI-powered operating system that enables:
- Create - Content, code, and creative works
- Build - Infrastructure and applications
- Operate - Automated workflows and agents
- Trade - Digital assets and tokens
- Govern - Decentralized decision-making
- Dream - Virtual worlds and experiences
- Explore - Research and innovation
Contributing
See the Contributing Guide to learn how to contribute to BlackRoad OS.
License
BlackRoad Operating System is licensed under the MIT License.
Built with ❤️ by the BlackRoad OS Team
BlackRoad OS Codex
Welcome to the BlackRoad Operating System Documentation
BlackRoad OS is a Windows 95-inspired web-based operating system that brings together AI orchestration, blockchain technology, and a nostalgic user interface. This is the complete technical documentation for developers, operators, and contributors.
🚀 Quick Links
-
Get up and running with BlackRoad OS in minutes
-
Understand the system design and components
-
Explore the complete API documentation
-
Deploy BlackRoad OS to production
📚 What is BlackRoad OS?
BlackRoad Operating System is a complete AI-powered ecosystem that includes:
- 🖥️ Pocket OS: A browser-based operating system with a Windows 95-inspired interface
- 🌌 Prism Console: Administrative interface for job queue management, event logging, and system metrics
- 🤖 Agent Library: 200+ autonomous AI agents across 10 categories
- 🔗 RoadChain: Blockchain-based audit trail and provenance system
- 🔐 PS-SHA∞ Identity: Sovereign identity system for agents and users
- ☁️ CloudWay: Infrastructure automation and deployment orchestration
🎯 Core Philosophy
- Agent-First
- Humans orchestrate, agents execute. BlackRoad OS is designed for AI-driven workflows.
- Memory-Conscious
- Everything is logged and retrievable. Complete audit trails for compliance and debugging.
- Ledger-Aware
- Critical actions are provable and tamper-evident via RoadChain.
- Zero-Dependency Frontend
- Vanilla JavaScript with no build process. Fast, simple, and maintainable.
- Cloud-Native
- Infrastructure as software. Deployed on Railway with Cloudflare CDN.
🗺️ Documentation Map
For Developers
- Quick Start Guide: Get started in 5 minutes
- Development Setup: Set up your local environment
- API Reference: Complete API documentation
- Creating Agents: Build your own agents
For Operators
- Deployment Guide: Production deployment steps
- Environment Variables: Configuration reference
- Infrastructure & Deployment: Railway + Cloudflare setup
For Contributors
- Contributing Guide: How to contribute to BlackRoad OS
- Architecture Overview: System architecture deep dive
🏗️ Current Status: Phase 2.5
Infrastructure Wiring Complete
BlackRoad OS Phase 2.5 has completed the infrastructure wiring, including:
- ✅ Monorepo as canonical OS home
- ✅ Prism Console served at
/prism - ✅ Documentation via GitHub Pages
- ✅ Railway + Cloudflare deployment ready
- ✅ Comprehensive environment variable management
What's Next: Phase 2.6+
- 🔄 Full Prism Console functionality (job queue, event log, metrics)
- 🔄 Agent orchestration workflows
- 🔄 RoadChain integration
- 🔄 PS-SHA∞ identity system
See Phase 2.5 Decisions for details.
🌟 Key Features
Prism Console
Administrative interface for managing the entire BlackRoad ecosystem:
- Job Queue: Monitor and manage long-running tasks
- Event Log: Real-time system event stream
- Metrics Dashboard: System health and performance
- Agent Management: View and control 200+ AI agents
Access: https://blackroad.systems/prism
Agent Library
200+ autonomous AI agents across 10 categories:
- DevOps (30+ agents)
- Engineering (40+ agents)
- Data Science (25+ agents)
- Security (20+ agents)
- Finance (15+ agents)
- Creative (20+ agents)
- Business (15+ agents)
- Research (15+ agents)
- Web (15+ agents)
- AI/ML (15+ agents)
Learn more: Agent Overview
RoadChain
Blockchain-based audit trail:
- Tamper-evident logging
- Provenance tracking
- Compliance-ready
- SHA-256 hashing
API: /api/blockchain
🚀 Production URLs
| Service | URL | Description |
|---|---|---|
| Main OS | https://blackroad.systems | BlackRoad OS desktop interface |
| Prism Console | https://blackroad.systems/prism | Administrative console |
| API Documentation | https://blackroad.systems/api/docs | OpenAPI/Swagger docs |
| Codex (this site) | https://docs.blackroad.systems | Complete documentation |
🤝 Community & Support
- GitHub: blackboxprogramming/BlackRoad-Operating-System
- Issues: Report bugs and request features on GitHub Issues
- Discord: Coming in Phase 1 Q2 (community hub)
📄 License
BlackRoad Operating System is proprietary software. See the repository LICENSE file for details.
Where AI meets the open road. 🛣️
Built with ❤️ by the BlackRoad team