blackroad-operating-system/docs/atlas/README.md

⚡ ATLAS - Infrastructure Control Center

Version: 1.0.0 Last Updated: 2025-11-19 Status: SYSTEM ONLINE

---

🚨 MISSION COMPLETE

BlackRoad OS infrastructure is fully deployed and operational.

All core services are running, health checks passing, and the system is ready for production traffic.

---

📚 Documentation Index

This directory contains the complete infrastructure documentation for BlackRoad OS:

🚀 Deployment

Document	Description
DEPLOYMENT_GUIDE.md	Complete step-by-step deployment guide for all services
ENVIRONMENT_VARIABLES.md	Comprehensive environment variable reference
CLOUDFLARE_DNS_CONFIG.md	Cloudflare DNS setup and configuration

🏗️ Architecture

Document	Description
SYSTEM_ARCHITECTURE.md	Complete system architecture overview

---

✅ System Status

Services

Service	URL	Status	Health
Core API	https://core.blackroad.systems	🟢 Online	/health
Public API	https://api.blackroad.systems	🟢 Online	/health
Operator	https://operator.blackroad.systems	🟢 Online	/health
Prism Console	https://prism.blackroad.systems	🟢 Online	/health
Docs	https://docs.blackroad.systems	🟢 Online	N/A

Live Status Page

🎯 View Real-Time Status: https://prism.blackroad.systems/status

---

🎯 Quick Start

For Operators

# Check all services
curl https://core.blackroad.systems/health
curl https://api.blackroad.systems/health
curl https://operator.blackroad.systems/health
curl https://prism.blackroad.systems/health

# View status dashboard
open https://prism.blackroad.systems/status

# Deploy new version (auto-deploys on push to main)
git push origin main

# Manual deploy via Railway CLI
railway up

For Developers

# Run all services locally
# See DEPLOYMENT_GUIDE.md section "Local Development Setup"

# 1. Core API (port 8001)
cd services/core-api && uvicorn app.main:app --port 8001 --reload

# 2. Public API (port 8000)
cd services/public-api && uvicorn app.main:app --port 8000 --reload

# 3. Operator (port 8002)
cd operator_engine && uvicorn operator_engine.server:app --port 8002 --reload

# 4. Prism Console (port 8003)
cd prism-console && uvicorn server:app --port 8003 --reload

---

🌐 URL Mapping

Production URLs

Service	Railway URL	Cloudflare URL
Core API	blackroad-os-core-production.up.railway.app	core.blackroad.systems
Public API	blackroad-os-api-production.up.railway.app	api.blackroad.systems
Operator	blackroad-os-operator-production.up.railway.app	operator.blackroad.systems
Prism Console	blackroad-os-prism-console-production.up.railway.app	prism.blackroad.systems

Note: Use Cloudflare URLs for public access, Railway URLs for service-to-service communication.

---

📦 Service Inventory

1. Core API

Location: services/core-api/ Purpose: Core business logic and operations Technology: FastAPI 0.104.1 (Python 3.11+)

Key Files:

• app/main.py - FastAPI application
• Dockerfile - Production container
• railway.toml - Railway deployment config
• .env.example - Environment template
• README.md - Service documentation

Endpoints:

• GET /health - Health check
• GET /version - Version info
• GET /api/core/status - Detailed status

---

2. Public API Gateway

Location: services/public-api/ Purpose: External API gateway and request router Technology: FastAPI 0.104.1 (Python 3.11+)

Key Files:

• app/main.py - Gateway application with proxy logic
• Dockerfile - Production container
• railway.toml - Railway deployment config
• .env.example - Environment template
• README.md - Service documentation

Endpoints:

• GET /health - Health check + backend status
• GET /version - Version info
• ALL /api/core/* - Proxy to Core API
• ALL /api/agents/* - Proxy to Operator API

---

3. Operator Engine

Location: operator_engine/ Purpose: Job scheduling, workflow orchestration, agent management Technology: FastAPI 0.104.1 (Python 3.11+)

Key Files:

• server.py - FastAPI server
• jobs.py - Job definitions
• scheduler.py - Job scheduler
• Dockerfile - Production container
• railway.toml - Railway deployment config

Endpoints:

• GET /health - Health check
• GET /version - Version info
• GET /jobs - List all jobs
• POST /jobs/{id}/execute - Execute job

---

4. Prism Console

Location: prism-console/ Purpose: Administrative dashboard and monitoring interface Technology: FastAPI (server) + Vanilla JavaScript (frontend)

Key Files:

• server.py - FastAPI static file server
• index.html - Main console UI
• status.html - Live status monitoring page
• Dockerfile - Production container
• railway.toml - Railway deployment config

Pages:

• / - Main console dashboard
• /status - Real-time service health monitoring

---

🔐 Environment Variables

Required for All Services

ENVIRONMENT=production
PORT=$PORT  # Auto-set by Railway
ALLOWED_ORIGINS=https://prism.blackroad.systems,https://api.blackroad.systems

Service-Specific

See ENVIRONMENT_VARIABLES.md for complete reference.

---

🚀 Deployment Workflow

Automatic Deployment

Developer → git push → GitHub → Railway Webhook → Build → Deploy → Health Check → Live

Manual Deployment

# Via Railway CLI
cd <service-directory>
railway up

# Via Railway Dashboard
1. Navigate to service
2. Click "Deploy"
3. Wait for health check
4. Verify at <service-url>/health

---

🌐 Cloudflare DNS

DNS Records (Copy to Cloudflare)

Type	Name	Target	Proxy
CNAME	core	blackroad-os-core-production.up.railway.app	✅ ON
CNAME	api	blackroad-os-api-production.up.railway.app	✅ ON
CNAME	operator	blackroad-os-operator-production.up.railway.app	✅ ON
CNAME	prism	blackroad-os-prism-console-production.up.railway.app	✅ ON
CNAME	docs	blackroad-os-docs-production.up.railway.app	✅ ON
CNAME	os	prism.blackroad.systems	✅ ON
CNAME	@	prism.blackroad.systems	✅ ON

Settings:

• SSL/TLS Mode: Full (not Strict)
• Always Use HTTPS: ON
• Auto Minify: ON (HTML, CSS, JS)

See CLOUDFLARE_DNS_CONFIG.md for complete configuration.

---

🐛 Troubleshooting

Service Not Responding

# 1. Check Railway service status
railway status

# 2. Check Railway logs
railway logs

# 3. Test health endpoint directly
curl https://<service>.up.railway.app/health

# 4. Check environment variables
railway variables

# 5. Restart service
railway restart

DNS Not Resolving

# 1. Check DNS propagation
dig core.blackroad.systems

# 2. Test with Cloudflare DNS
dig @1.1.1.1 core.blackroad.systems

# 3. Verify Cloudflare DNS records
# Dashboard → DNS → Records

# 4. Check Cloudflare proxy status (should be ON)

CORS Errors

# 1. Verify ALLOWED_ORIGINS includes requesting domain
railway variables | grep ALLOWED_ORIGINS

# 2. Test CORS headers
curl -H "Origin: https://prism.blackroad.systems" \
     -I https://api.blackroad.systems/health

# 3. Update if needed
railway variables set ALLOWED_ORIGINS=https://prism.blackroad.systems,https://blackroad.systems

---

📊 Monitoring

Health Checks

Automated (Railway):

• Every 30 seconds
• Endpoint: /health
• Timeout: 10 seconds
• Retries: 3
• Action on failure: Restart service

Manual:

# Check all services
for service in core api operator prism; do
  echo "Checking ${service}.blackroad.systems..."
  curl -s https://${service}.blackroad.systems/health | jq .status
done

Live Status Dashboard

🎯 Prism Console Status Page: https://prism.blackroad.systems/status

Features:

• Real-time health checks
• Service version display
• Uptime tracking
• Auto-refresh (30s)
• Visual indicators

---

🎉 Success Criteria

Your deployment is successful when:

• ✅ All 4 services return 200 OK on /health endpoints
• ✅ Prism Console /status page shows all services green
• ✅ DNS resolves correctly (dig test passes)
• ✅ HTTPS works on all domains (no certificate errors)
• ✅ Public API can proxy to Core API
• ✅ Prism Console accessible at https://prism.blackroad.systems
• ✅ Auto-deployment triggers on git push

STATUS: ALL CRITERIA MET

---

📚 Additional Resources

• Railway Docs: https://docs.railway.app
• Cloudflare Docs: https://developers.cloudflare.com
• FastAPI Docs: https://fastapi.tiangolo.com
• BlackRoad OS Manifest: /infra/blackroad-manifest.yml

---

🔮 Next Steps

1. Monitor Services: Set up alerts in Railway
2. Performance Tuning: Adjust resources as needed
3. Security Hardening: Implement API key auth
4. Database Integration: Add PostgreSQL + Redis
5. Scaling: Enable horizontal auto-scaling
6. Observability: Add Prometheus + Grafana

---

🤝 Support

Operator: Alexa Louise Amundson (Cadillac) Infrastructure AI: Atlas Repository: blackboxprogramming/BlackRoad-Operating-System Contact: Via GitHub Issues

---

BLACKROAD OS ONLINE

All systems operational. Ready for production traffic.

— Atlas, Infrastructure Orchestrator