blackroad-operating-system/codex-docs/docs/architecture/phase2-decisions.md

Phase 2.5 Architectural Decisions

Date: 2025-11-18 Version: 2.5 Status: Implemented

This document codifies the key architectural decisions made in BlackRoad OS Phase 2.5.

---

Decision Summary

Decision	Choice	Rationale
Repository Strategy	Monorepo	Single source of truth for Phase 1-2
Prism Console Serving	Backend at /prism	Integrated deployment, shared auth
Documentation Hosting	GitHub Pages	Free, reliable, custom domain support
Frontend Technology	Vanilla JavaScript	Zero dependencies, no build process

---

Decision 1: Monorepo Strategy

Context

BlackRoad OS consists of multiple components:

• Core OS runtime
• Backend API
• Frontend UI
• Prism Console
• Agent library
• Documentation
• Infrastructure configuration

Options Considered

Option A: Monorepo (✅ Selected)

• Pros:

  • Single source of truth
  • Easier cross-component changes
  • Simpler CI/CD pipeline
  • Atomic commits across components
  • Faster iteration for small teams

• Cons:

  • Large repository size
  • All contributors need full repo access
  • Harder to scale to large teams

Option B: Multi-Repo

• Pros:

  • Clear component boundaries
  • Independent release cycles
  • Granular access control
  • Easier to scale teams

• Cons:

  • Coordination overhead
  • Cross-repo changes require multiple PRs
  • Complex CI/CD setup
  • Risk of version drift

Decision

Chose: Monorepo for Phase 1-2

When to reconsider:

• Team size > 10 developers
• Independent release cycles needed
• Different tech stacks emerging
• Clear ownership boundaries established

Migration path (Phase 3):

BlackRoad-Operating-System (monorepo)
  ↓ git subtree split
├── blackroad-os-core
├── blackroad-os-api
├── blackroad-os-web
├── blackroad-os-prism
├── blackroad-os-operator
└── blackroad-os-docs

Implementation

• Repository: blackboxprogramming/BlackRoad-Operating-System
• All components in single repo
• Shared CI/CD workflows
• Unified versioning

---

Decision 2: Prism Console Serving

Context

Prism Console is the administrative interface for BlackRoad OS. It needs to be:

• Accessible to authenticated users
• Integrated with backend API
• Properly routed and cached

Options Considered

Option A: Serve from Backend at /prism (✅ Selected)

• Pros:

  • Single deployment unit
  • Shared authentication
  • No CORS issues
  • Easier routing

• Cons:

  • Backend serves static files
  • Couples frontend and backend

Option B: Separate Static Hosting

• Pros:

  • Decoupled deployments
  • CDN optimization
  • Independent scaling

• Cons:

  • CORS complexity
  • Multiple deployments
  • Auth token sharing

Option C: Subdomain with Separate Deployment

• Pros:

  • Clean separation
  • Independent deployment
  • Scalable

• Cons:

  • Additional infrastructure
  • DNS configuration
  • CORS setup

Decision

Chose: Serve from Backend at /prism

Rationale:

1. Simplicity: Single deployment reduces operational complexity
2. Authentication: Shares auth context with main OS
3. Routing: Clean URL structure (/prism)
4. Caching: Cloudflare caches static assets anyway
5. Phase 1 appropriate: Good enough for early-stage product

Future evolution (Phase 3):

• Move to subdomain (prism.blackroad.systems)
• Separate deployment for independent scaling
• Dedicated CDN optimization

Implementation

• Route: GET /prism → backend/app/routers/prism_static.py
• Static files: backend/static/prism/
• URL: https://blackroad.systems/prism

---

Decision 3: Documentation Hosting

Context

Technical documentation needs to be:

• Easy to write (Markdown)
• Easy to deploy (automated)
• Searchable
• Custom domain support
• Low/no cost

Options Considered

Option A: GitHub Pages with MkDocs (✅ Selected)

• Pros:

  • Free hosting
  • Custom domain support
  • Automated deployment (GitHub Actions)
  • MkDocs Material theme (beautiful)
  • Search built-in

• Cons:

  • Static site only (no server-side logic)
  • Limited to public repos (or Enterprise)

Option B: ReadTheDocs

• Pros:

  • Purpose-built for docs
  • Versioning support
  • Free for open source

• Cons:

  • Less control
  • Custom domain on paid plans
  • Branding

Option C: Serve from Backend

• Pros:

  • Full control
  • Server-side features

• Cons:

  • Backend complexity
  • Deployment coupling
  • No built-in search

Decision

Chose: GitHub Pages with MkDocs Material

Rationale:

1. Cost: Free for public repos
2. Workflow: GitHub Actions automation
3. Quality: Material theme is production-grade
4. Search: Built-in search with minisearch
5. Custom domain: docs.blackroad.systems support

Implementation

• Source: codex-docs/ directory
• Builder: MkDocs + Material theme
• Deployment: .github/workflows/docs-deploy.yml
• Branch: gh-pages (auto-created)
• URL: https://docs.blackroad.systems

---

Decision 4: Frontend Technology

Context

Frontend needs to be:

• Fast to load
• Easy to maintain
• No build complexity
• Accessible (WCAG 2.1)

Options Considered

Option A: Vanilla JavaScript (✅ Selected)

• Pros:

  • Zero dependencies
  • No build process
  • Fast load times (~200KB)
  • Easy to understand
  • No framework lock-in

• Cons:

  • More verbose
  • Manual DOM manipulation
  • No TypeScript (unless added)

Option B: React

• Pros:

  • Rich ecosystem
  • Component model
  • TypeScript support

• Cons:

  • Build process required
  • Bundle size (~300KB+ with React + deps)
  • Learning curve
  • Overkill for Phase 1

Option C: Vue or Svelte

• Pros:

  • Smaller than React
  • Easier learning curve
  • Good developer experience

• Cons:

  • Still requires build
  • Framework dependency
  • Not needed for current scope

Decision

Chose: Vanilla JavaScript (ES6+)

Rationale:

1. Philosophy: Aligns with "Zero-Dependency" principle
2. Performance: Fastest load times
3. Simplicity: No build process to maintain
4. Maintainability: Plain JavaScript is timeless
5. Nostalgia: Fits Windows 95 theme

When to reconsider:

• App complexity exceeds ~10,000 LOC
• Team prefers framework
• TypeScript becomes critical

Evolution path:

• Add TypeScript (via Vite, no bundling)
• Migrate to Lit (web components, minimal overhead)
• Or stick with vanilla (perfectly fine!)

Implementation

• Location: backend/static/
• Structure:
  • js/os.js - Core OS runtime
  • js/components.js - UI library
  • js/apps/*.js - Applications
• Patterns:
  • Event-driven architecture
  • Factory pattern for components
  • Module pattern for encapsulation

---

Cross-Cutting Concerns

Deployment Flow

Developer pushes to main
  ↓
GitHub Actions CI
  ↓
Tests pass ✓
  ↓
├── Backend → Railway
│   ├── Build Docker image
│   ├── Deploy to production
│   └── Serve OS at / and Prism at /prism
│
└── Docs → GitHub Pages
    ├── Build MkDocs
    └── Deploy to gh-pages branch

URL Structure

Path	Serves	Source
https://blackroad.systems	Main OS	backend/static/index.html
https://blackroad.systems/prism	Prism Console	backend/static/prism/index.html
https://blackroad.systems/api/docs	API Documentation	FastAPI OpenAPI
https://docs.blackroad.systems	Technical Docs	GitHub Pages (codex-docs/)

DNS Configuration

Record	Target	Purpose
blackroad.systems →	Railway backend	Main OS + API
docs.blackroad.systems →	GitHub Pages	Documentation
www.blackroad.systems →	blackroad.systems	Redirect

---

Future Decisions (Phase 3+)

Likely Changes

1. Multi-Repo Split

   • When: Team > 10 people
   • How: Git subtree split
   • Why: Independent releases

2. Microservices

   • When: Scaling bottlenecks
   • Services: API gateway, Prism worker, Lucidia engine
   • Why: Independent scaling

3. Frontend Framework

   • When: App > 10,000 LOC or team preference
   • Options: Lit (web components), Vue (lightweight), or stick with vanilla
   • Why: Developer experience

Unlikely Changes

1. Documentation Hosting

   • GitHub Pages + MkDocs works well
   • No reason to change

2. Backend Framework

   • FastAPI is excellent
   • Python async ecosystem mature
   • No reason to change

---

Decision Log

Date	Decision	Status
2025-11-18	Monorepo for Phase 1-2	✅ Implemented
2025-11-18	Prism at /prism route	✅ Implemented
2025-11-18	Docs via GitHub Pages	✅ Implemented
2025-11-18	Vanilla JS frontend	✅ Confirmed

---

References

• MASTER_ORCHESTRATION_PLAN.md - Complete infrastructure blueprint
• PHASE2_5_SUMMARY_FOR_ALEXA.md - Phase 2.5 summary
• BLACKROAD_OS_REPO_MAP.md - Repository structure
• DEPLOYMENT_NOTES.md - Deployment guide

---

Where AI meets the open road. 🛣️

Architectural decisions for BlackRoad OS Phase 2.5