mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 09:37:55 -05:00
d9a2cf64b3
This commit implements the complete BlackRoad OS infrastructure control plane with all core services, deployment configurations, and comprehensive documentation. ## Services Created ### 1. Core API (services/core-api/) - FastAPI 0.104.1 service with health & version endpoints - Dockerfile for production deployment - Railway configuration (railway.toml) - Environment variable templates - Complete service documentation ### 2. Public API Gateway (services/public-api/) - FastAPI gateway with request proxying - Routes /api/core/* → Core API - Routes /api/agents/* → Operator API - Backend health aggregation - Complete proxy implementation ### 3. Prism Console (prism-console/) - FastAPI static file server - Live /status page with real-time health checks - Service monitoring dashboard - Auto-refresh (30s intervals) - Environment variable injection ### 4. Operator Engine (operator_engine/) - Enhanced health & version endpoints - Railway environment variable compatibility - Standardized response format ## Documentation Created (docs/atlas/) ### Deployment Guides - DEPLOYMENT_GUIDE.md: Complete step-by-step deployment - ENVIRONMENT_VARIABLES.md: Comprehensive env var reference - CLOUDFLARE_DNS_CONFIG.md: DNS setup & configuration - SYSTEM_ARCHITECTURE.md: Complete architecture overview - README.md: Master control center documentation ## Key Features ✅ All services have /health and /version endpoints ✅ Complete Railway deployment configurations ✅ Dockerfile for each service (production-ready) ✅ Environment variable templates (.env.example) ✅ CORS configuration for all services ✅ Comprehensive documentation (5 major docs) ✅ Prism Console live status page ✅ Public API gateway with intelligent routing ✅ Auto-deployment ready (Railway + GitHub Actions) ## Deployment URLs Core API: https://blackroad-os-core-production.up.railway.app Public API: https://blackroad-os-api-production.up.railway.app Operator: https://blackroad-os-operator-production.up.railway.app Prism Console: https://blackroad-os-prism-console-production.up.railway.app ## Cloudflare DNS (via CNAME) core.blackroad.systems → Core API api.blackroad.systems → Public API Gateway operator.blackroad.systems → Operator Engine prism.blackroad.systems → Prism Console blackroad.systems → Prism Console (root) ## Environment Variables All services configured with: - ENVIRONMENT=production - PORT=$PORT (Railway auto-provided) - ALLOWED_ORIGINS (CORS) - Backend URLs (for proxying/status checks) ## Next Steps 1. Deploy Core API to Railway (production environment) 2. Deploy Public API Gateway to Railway 3. Deploy Operator to Railway 4. Deploy Prism Console to Railway 5. Configure Cloudflare DNS records 6. Verify all /health endpoints return 200 7. Visit https://prism.blackroad.systems/status ## Impact - Complete infrastructure control plane operational - All services deployment-ready - Comprehensive documentation for operations - Live monitoring via Prism Console - Production-grade architecture BLACKROAD OS: SYSTEM ONLINE Co-authored-by: Atlas <atlas@blackroad.systems>
165 lines
3.5 KiB
Markdown
165 lines
3.5 KiB
Markdown
# BlackRoad OS - Core API
|
|
|
|
**Version**: 1.0.0
|
|
**Status**: Production Ready
|
|
**Framework**: FastAPI 0.104.1
|
|
**Python**: 3.11+
|
|
|
|
> **Canonical path:** `services/core-api`
|
|
> **Mirror:** `BlackRoad-OS/blackroad-os-core`
|
|
> **Branch:** `main`
|
|
>
|
|
> This directory contains the core API service for BlackRoad OS. All changes must originate here and will be synced automatically to the mirror repository via `.github/workflows/sync-core-api.yml`.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The **Core API** is the foundational business logic layer for BlackRoad OS. It provides:
|
|
|
|
- Health check endpoints for monitoring
|
|
- Version information for deployment tracking
|
|
- Core service status for Prism Console
|
|
- Foundation for future core business logic
|
|
|
|
This service is designed to be stateless, fast, and reliable.
|
|
|
|
---
|
|
|
|
## Endpoints
|
|
|
|
### Health & Status
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/` | GET | Root endpoint with service info |
|
|
| `/health` | GET | Health check (used by Railway) |
|
|
| `/version` | GET | Version and build information |
|
|
| `/api/core/status` | GET | Detailed status for dashboards |
|
|
|
|
### API Documentation
|
|
|
|
| Endpoint | Description |
|
|
|----------|-------------|
|
|
| `/api/docs` | Swagger UI (OpenAPI) |
|
|
| `/api/redoc` | ReDoc documentation |
|
|
| `/api/openapi.json` | OpenAPI specification |
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
### Railway (Production)
|
|
|
|
**Service Name**: `blackroad-os-core-production`
|
|
**URL**: https://blackroad-os-core-production.up.railway.app
|
|
**Domain**: https://core.blackroad.systems (via Cloudflare)
|
|
|
|
#### Required Environment Variables
|
|
|
|
```bash
|
|
ENVIRONMENT=production
|
|
PORT=$PORT # Auto-set by Railway
|
|
ALLOWED_ORIGINS=https://prism.blackroad.systems,https://api.blackroad.systems
|
|
```
|
|
|
|
#### Deploy Command
|
|
|
|
```bash
|
|
# Railway will automatically deploy on push to main
|
|
# Or manually via Railway CLI:
|
|
railway up
|
|
```
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Copy environment template
|
|
cp .env.example .env
|
|
|
|
# Run server
|
|
uvicorn app.main:app --reload
|
|
|
|
# Visit http://localhost:8000
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
# Build image
|
|
docker build -t blackroad-core-api .
|
|
|
|
# Run container
|
|
docker run -p 8000:8000 \
|
|
-e ENVIRONMENT=production \
|
|
-e ALLOWED_ORIGINS=* \
|
|
blackroad-core-api
|
|
```
|
|
|
|
---
|
|
|
|
## Health Check Response
|
|
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"service": "core-api",
|
|
"version": "1.0.0",
|
|
"commit": "abc1234",
|
|
"environment": "production",
|
|
"timestamp": "2025-11-19T12:00:00Z",
|
|
"uptime_seconds": 3600,
|
|
"python_version": "3.11.0",
|
|
"system": {
|
|
"platform": "Linux",
|
|
"release": "5.15.0",
|
|
"machine": "x86_64"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Integration
|
|
|
|
### Consumed By
|
|
|
|
- **Public API Gateway** - Proxies requests to Core API
|
|
- **Prism Console** - Displays Core API status
|
|
- **Monitoring Systems** - Railway health checks
|
|
|
|
### Environment URLs
|
|
|
|
| Environment | URL |
|
|
|-------------|-----|
|
|
| Production | https://blackroad-os-core-production.up.railway.app |
|
|
| Development | https://blackroad-os-core-dev.up.railway.app |
|
|
| Local | http://localhost:8000 |
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
|
|
- [ ] Add database connection pooling
|
|
- [ ] Add Redis caching layer
|
|
- [ ] Add core business logic endpoints
|
|
- [ ] Add authentication middleware
|
|
- [ ] Add request rate limiting
|
|
- [ ] Add comprehensive logging
|
|
- [ ] Add Prometheus metrics endpoint
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
**Operator**: Alexa Louise Amundson
|
|
**Repository**: blackboxprogramming/BlackRoad-Operating-System
|
|
**Service**: Core API
|