mirror of https://github.com/blackboxprogramming/BlackRoad-Operating-System.git synced 2026-03-17 07:57:19 -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: Postgres

Status: ✅ ACTIVE (Production) Last Analyzed: 2025-11-19 Service Type: Managed Database (PostgreSQL) Provider: Railway

Overview

Managed PostgreSQL database service provided by Railway. Stores all persistent data for BlackRoad OS including users, wallets, blockchain, and application data.

Configuration

Version

PostgreSQL: 15+ (Railway managed, auto-updates minor versions)

Resources

Storage: Auto-scaling (starts at 1GB)
Memory: Shared (Railway managed)
Connections: Max 100 concurrent

Performance Tuning

-- Current settings (Railway defaults)
max_connections = 100
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 4MB
maintenance_work_mem = 64MB

Schema

Current Tables

users - User accounts (auth, profiles)
wallets - Blockchain wallets (encrypted keys)
blocks - RoadChain blockchain
transactions - Blockchain transactions
jobs - Prism job queue (future)
events - Audit/compliance events

Migration Management

Tool: Alembic
Location: backend/alembic/
Strategy: Manual migrations (no auto-upgrade in production)

Backups

Automated Backups (Railway)

Frequency: Daily
Retention: 30 days
Storage: Railway managed

Restore Process

Railway Dashboard → Database → Backups
Select backup date
Click "Restore"
Verify data integrity

Security

Access Control

Network: Private Railway network only
Credentials: Auto-generated, injected via ${{Postgres.DATABASE_URL}}
SSL/TLS: Enforced

Encryption

At Rest: Railway managed encryption
In Transit: SSL/TLS (required)

Monitoring

Metrics (Railway Dashboard)

Connection count
Query performance
Storage usage
CPU/memory usage

Alerts (Recommended)

Storage > 80% full
Connection pool exhausted
Slow queries (> 1s)

Maintenance

Regular Tasks

Vacuum: Automatic (Railway managed)
Analyze: Automatic (Railway managed)
Index optimization: Manual (as needed)

Scaling

Vertical: Upgrade Railway plan
Storage: Auto-scales up to plan limit

Connection Details

Environment Variable

DATABASE_URL=${{Postgres.DATABASE_URL}}
# Format: postgresql+asyncpg://user:pass@host:port/db

Connection Pool (SQLAlchemy)

# backend/app/database.py
engine = create_async_engine(
    DATABASE_URL,
    echo=False,
    pool_size=10,
    max_overflow=20,
    pool_pre_ping=True
)

Troubleshooting

Connection Issues

Verify DATABASE_URL is set in Railway
Check service logs for connection errors
Verify database service is running
Check connection pool exhaustion

Performance Issues

Check slow query log
Analyze query plans with EXPLAIN
Add missing indexes
Optimize N+1 queries

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

2.9 KiB Raw Blame History