mirror of https://github.com/blackboxprogramming/BlackRoad-Operating-System.git synced 2026-03-17 00:57:12 -05:00

Files

Claude abdbc764e6 Establish BlackRoad OS infrastructure control plane

Add comprehensive infrastructure management system to centralize all service
definitions, deployment configurations, and operational tooling.

## New Infrastructure Components

### 1. Service Manifest (infra/blackroad-manifest.yml)
- Complete catalog of all active and planned services
- Deployment configuration for each service
- Environment variable definitions
- Domain mappings and routing
- Database and cache dependencies
- Health check endpoints
- CI/CD integration specifications

### 2. Operations CLI (scripts/br_ops.py)
- Command-line tool for managing all BlackRoad services
- Commands: list, env, repo, open, status, health
- Reads from service manifest for unified operations
- Colored terminal output for better readability

### 3. Service Analysis Documents (infra/analysis/)
- Detailed technical analysis for each service
- Active services:
  - blackroad-backend.md (FastAPI backend)
  - postgres.md (PostgreSQL database)
  - redis.md (Redis cache)
  - docs-site.md (MkDocs documentation)
- Planned services:
  - blackroad-api.md (API gateway - Phase 2)
  - prism-console.md (Admin console - Phase 2)

### 4. Infrastructure Templates (infra/templates/)
- railway.toml.template - Railway deployment config
- railway.json.template - Alternative Railway config
- Dockerfile.fastapi.template - Multi-stage FastAPI Dockerfile
- github-workflow-railway-deploy.yml.template - CI/CD workflow
- .env.example.template - Comprehensive env var template

### 5. Documentation (infra/README.md)
- Complete guide to infrastructure control plane
- Usage instructions for ops CLI
- Service manifest documentation
- Deployment procedures
- Troubleshooting guide
- Phase 2 migration plan

## Architecture

This establishes BlackRoad-Operating-System as the canonical control plane
for all BlackRoad services, both current and planned:

**Phase 1 (Active)**:
- blackroad-backend (FastAPI + static UI)
- postgres (Railway managed)
- redis (Railway managed)
- docs-site (GitHub Pages)

**Phase 2 (Planned)**:
- blackroad-api (API gateway)
- blackroad-prism-console (Admin UI)
- blackroad-agents (Orchestration)
- blackroad-web (Marketing site)

**Phase 3 (Future)**:
- lucidia (AI orchestration)
- Additional microservices

## Usage

# List all services
python scripts/br_ops.py list

# Show environment variables
python scripts/br_ops.py env blackroad-backend

# Show repository info
python scripts/br_ops.py repo blackroad-backend

# Show service URL
python scripts/br_ops.py open blackroad-backend prod

# Show overall status
python scripts/br_ops.py status

# Show health checks
python scripts/br_ops.py health blackroad-backend

## Benefits

1. **Single Source of Truth**: All service configuration in one manifest
2. **Unified Operations**: One CLI for all services
3. **Documentation**: Comprehensive per-service analysis
4. **Templates**: Reusable infrastructure patterns
5. **Migration Ready**: Clear path to Phase 2 microservices

## References

- MASTER_ORCHESTRATION_PLAN.md - 7-layer architecture
- ORG_STRUCTURE.md - Repository strategy
- PRODUCTION_STACK_AUDIT_2025-11-18.md - Current state

Implemented by: Atlas (AI Infrastructure Orchestrator)
Date: 2025-11-19

2025-11-19 21:04:14 +00:00

2.9 KiB

Raw Blame History

Service Analysis: docs-site

Status: ✅ ACTIVE (GitHub Pages) Last Analyzed: 2025-11-19 Service Type: Static Documentation Site Platform: GitHub Pages + Cloudflare CDN

Overview

Technical documentation site built with MkDocs Material theme. Deployed to GitHub Pages and served via Cloudflare CDN at docs.blackroad.systems.

Technology Stack

Static Site Generator

Tool: MkDocs 1.5+
Theme: Material for MkDocs
Plugins: search, minify, git-revision-date

Build Process

cd codex-docs
mkdocs build --strict
# Output: site/

Content Structure

Documentation Categories

Architecture: System design, decisions, deployment
API Reference: Endpoint documentation, schemas
Guides: Quickstart, development, deployment
Agents: Agent ecosystem, creating agents
Contributing: Contribution guidelines

Source Location

Root: codex-docs/
Config: codex-docs/mkdocs.yml
Docs: codex-docs/docs/
Build Output: codex-docs/site/ (gitignored)

Deployment

Platform

Primary: GitHub Pages
Branch: gh-pages (auto-generated)
CDN: Cloudflare (proxied)

CI/CD

# .github/workflows/docs-deploy.yml
on:
  push:
    branches: [main]
    paths: ['codex-docs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: pip install mkdocs mkdocs-material
      - name: Build docs
        run: cd codex-docs && mkdocs build --strict
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./codex-docs/site

Domain Configuration

DNS (Cloudflare)

Type: CNAME
Name: docs
Value: blackboxprogramming.github.io
Proxy: Enabled (Orange cloud)
TTL: Auto

GitHub Pages

Repository Settings → Pages
Source: gh-pages branch
Custom domain: docs.blackroad.systems
HTTPS: Enforced

Performance

Metrics

Build Time: ~10-20 seconds
Deploy Time: ~30-60 seconds
Page Load: < 1s (CDN cached)
Size: ~5-10 MB (all pages)

Optimizations

Minified HTML/CSS/JS
Image optimization
Cloudflare CDN caching
Gzip compression

Maintenance

Regular Tasks

Update documentation with code changes
Review for outdated content
Check broken links
Update screenshots

Versioning

Current: Single version (latest)
Future: Multi-version support with mike

Troubleshooting

Build Failures

Check MkDocs config syntax
Verify all referenced files exist
Look for broken internal links
Check plugin compatibility

DNS Issues

Verify CNAME record in Cloudflare
Check GitHub Pages custom domain setting
Wait for DNS propagation (up to 24h)

Analysis Date: 2025-11-19 Next Review: 2025-12-19

2.9 KiB Raw Blame History