mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 06:57:17 -05:00
abdbc764e6
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
89 lines
2.1 KiB
Markdown
89 lines
2.1 KiB
Markdown
# Service Analysis: blackroad-api (PLANNED)
|
|
|
|
**Status**: 📋 PLANNED (Phase 2)
|
|
**Target Date**: Q2 2026
|
|
**Service Type**: Public API Gateway
|
|
**Repository**: `blackboxprogramming/blackroad-api` (to be created)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Standalone public API gateway to be extracted from the monolith in Phase 2. Will serve versioned API endpoints with enhanced security, rate limiting, and developer experience.
|
|
|
|
---
|
|
|
|
## Extraction Plan
|
|
|
|
### Source
|
|
- **Current Location**: `backend/app/routers/` in monolith
|
|
- **Target Repo**: New `blackroad-api` repository
|
|
- **Migration Method**: `git subtree split`
|
|
|
|
### Timeline
|
|
1. **Month 1-2**: Plan API contract versioning
|
|
2. **Month 3-4**: Extract routers, create new repo
|
|
3. **Month 5**: Deploy to Railway (parallel with monolith)
|
|
4. **Month 6**: DNS cutover, deprecate monolith API
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### Technology Stack
|
|
- **Language**: Python 3.11+
|
|
- **Framework**: FastAPI 0.104.1
|
|
- **Features**:
|
|
- Versioned endpoints (`/v1/`, `/v2/`)
|
|
- Enhanced rate limiting
|
|
- API key management
|
|
- Developer portal
|
|
|
|
### Endpoints (Planned)
|
|
- `/v1/health` - Health check
|
|
- `/v1/version` - API version
|
|
- `/v1/auth/*` - Authentication
|
|
- `/v1/blockchain/*` - RoadChain access
|
|
- `/v1/agents/*` - Agent orchestration
|
|
- `/v1/data/*` - Data access APIs
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
```bash
|
|
CORE_API_URL=https://core-internal.blackroad.systems
|
|
AGENTS_API_URL=https://agents-internal.blackroad.systems
|
|
DATABASE_URL=${{Postgres.DATABASE_URL}}
|
|
REDIS_URL=${{Redis.REDIS_URL}}
|
|
API_KEYS_ENCRYPTION_KEY=<generate>
|
|
RATE_LIMIT_PER_MINUTE=60
|
|
```
|
|
|
|
### Domains
|
|
- **Production**: `api.blackroad.systems`
|
|
- **Staging**: `staging.api.blackroad.systems`
|
|
- **Dev**: `dev.api.blackroad.systems`
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
- Internal core API (monolith)
|
|
- Internal agents API
|
|
- PostgreSQL (shared or dedicated)
|
|
- Redis (shared or dedicated)
|
|
|
|
---
|
|
|
|
## Risks & Mitigation
|
|
- **Risk**: Breaking changes for existing clients
|
|
- **Mitigation**: Version API endpoints, maintain v1 compatibility
|
|
- **Risk**: Performance degradation with extra hop
|
|
- **Mitigation**: Implement intelligent caching, optimize internal calls
|
|
|
|
---
|
|
|
|
*Analysis Date: 2025-11-19*
|
|
*Status: Planning Phase*
|