feat: Add Railway infrastructure configuration and documentation

- Add railway.json with complete service registry (22 services) - Add SERVICES.md documenting all Railway services and endpoints - Add .env.railway.example template for environment variables - Document custom domains (operator, beacon, prism) - Include service-to-service communication patterns - Add architecture diagram showing Railway network topology 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-03-17 07:57:19 -05:00 · 2025-11-29 13:26:13 -06:00
parent 0108860bff
commit 2609eaa3a5
3 changed files with 467 additions and 0 deletions
--- a/infra/railway/.env.railway.example
+++ b/infra/railway/.env.railway.example
@@ -0,0 +1,143 @@
+# ==============================================================================
+# BlackRoad OS - Railway Environment Variables Template
+# ==============================================================================
+#
+# This file contains all Railway-specific environment variables.
+# Copy this file to your Railway service settings or use it as reference.
+#
+# DO NOT commit actual values to version control.
+#
+# Last Updated: 2025-11-29
+# ==============================================================================
+
+# ------------------------------------------------------------------------------
+# Railway Auto-Injected Variables (DO NOT SET MANUALLY)
+# These are automatically set by Railway for each service
+# ------------------------------------------------------------------------------
+
+# RAILWAY_ENVIRONMENT=production
+# RAILWAY_ENVIRONMENT_ID=57e6ac32-0e86-4bde-a337-948535e27bcc
+# RAILWAY_ENVIRONMENT_NAME=production
+# RAILWAY_PROJECT_ID=03ce1e43-5086-4255-b2bc-0146c8916f4c
+# RAILWAY_PROJECT_NAME=BlackRoad OS
+# RAILWAY_SERVICE_ID=<auto-generated>
+# RAILWAY_SERVICE_NAME=<service-name>
+# RAILWAY_PRIVATE_DOMAIN=<service-name>.railway.internal
+
+# ------------------------------------------------------------------------------
+# Service URL References (Auto-injected by Railway)
+# Use these to communicate between services
+# ------------------------------------------------------------------------------
+
+# RAILWAY_SERVICE_BLACKROAD_OS_API_GATEWAY_URL=blackroad-os-api-gateway-production.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_API_URL=blackroad-os-api-production-3335.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_BEACON_URL=beacon.blackroad.systems
+# RAILWAY_SERVICE_BLACKROAD_OS_CORE_URL=blackroad-os-core-production.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_DOCS_URL=blackroad-os-docs-production-f7af.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_HOME_URL=blackroad-os-home-production.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_INFRA_URL=blackroad-os-infra-production.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_MASTER_URL=blackroad-os-master-production.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_PACK_RESEARCH_LAB_URL=blackroad-os-pack-research-lab-production.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_OS_URL=blackroad-os-production.up.railway.app
+# RAILWAY_SERVICE_BLACKROAD_PRISM_CONSOLE_URL=prism.blackroad.systems
+
+# ------------------------------------------------------------------------------
+# Application Settings (SET THESE)
+# ------------------------------------------------------------------------------
+
+# Server Configuration
+PORT=8000
+HOST=0.0.0.0
+NODE_ENV=production
+
+# Security
+SECRET_KEY=your-secret-key-here-min-32-chars
+JWT_SECRET=your-jwt-secret-here
+
+# ------------------------------------------------------------------------------
+# Database (Railway Plugin or External)
+# ------------------------------------------------------------------------------
+
+# PostgreSQL (Railway Plugin auto-populates these)
+# DATABASE_URL=postgresql://user:password@host:5432/database
+# PGHOST=
+# PGPORT=5432
+# PGUSER=
+# PGPASSWORD=
+# PGDATABASE=
+
+# For async PostgreSQL (FastAPI)
+# DATABASE_URL=postgresql+asyncpg://user:password@host:5432/database
+
+# ------------------------------------------------------------------------------
+# Redis (Railway Plugin or External)
+# ------------------------------------------------------------------------------
+
+# REDIS_URL=redis://host:6379/0
+# REDIS_HOST=
+# REDIS_PORT=6379
+# REDIS_PASSWORD=
+
+# ------------------------------------------------------------------------------
+# External API Keys (Service Specific)
+# ------------------------------------------------------------------------------
+
+# AI Services
+# OPENAI_API_KEY=sk-...
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# Cloud Services
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+# AWS_REGION=us-east-1
+
+# Payments
+# STRIPE_SECRET_KEY=sk_live_...
+# STRIPE_PUBLISHABLE_KEY=pk_live_...
+# STRIPE_WEBHOOK_SECRET=whsec_...
+
+# Communication
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASSWORD=
+# TWILIO_ACCOUNT_SID=
+# TWILIO_AUTH_TOKEN=
+
+# GitHub (for Operator service)
+# GITHUB_APP_ID=
+# GITHUB_PRIVATE_KEY=
+# GITHUB_WEBHOOK_SECRET=
+
+# Monitoring
+# SENTRY_DSN=https://...@sentry.io/...
+
+# ------------------------------------------------------------------------------
+# CORS Configuration
+# ------------------------------------------------------------------------------
+
+ALLOWED_ORIGINS=https://blackroad.systems,https://*.blackroad.systems,https://*.up.railway.app
+
+# ------------------------------------------------------------------------------
+# Feature Flags
+# ------------------------------------------------------------------------------
+
+# DEBUG=false
+# ENABLE_METRICS=true
+# ENABLE_TRACING=true
+
+# ------------------------------------------------------------------------------
+# Service-Specific Settings
+# ------------------------------------------------------------------------------
+
+# For blackroad-os-core
+# BLOCKCHAIN_NETWORK=mainnet
+# WALLET_MASTER_KEY=
+
+# For blackroad-os-operator
+# AUTO_MERGE_ENABLED=true
+# PR_CHECK_INTERVAL=60
+
+# For blackroad-prism-console
+# PRISM_MODE=production
+# AGENT_TIMEOUT=300
--- a/infra/railway/SERVICES.md
+++ b/infra/railway/SERVICES.md
@@ -0,0 +1,221 @@
+# BlackRoad OS - Railway Services Documentation
+
+> **Last Updated**: 2025-11-29
+> **Project ID**: `03ce1e43-5086-4255-b2bc-0146c8916f4c`
+> **Workspace**: BlackRoad OS, Inc.
+> **Environment**: production
+
+---
+
+## Overview
+
+BlackRoad OS is deployed across multiple Railway services, forming a distributed operating system architecture. Each service represents a distinct component of the OS ecosystem.
+
+---
+
+## Service Registry
+
+### Core Services
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| **blackroad** | `blackroad.railway.internal` | Main entry point service |
+| **blackroad-os** | `blackroad-os-production.up.railway.app` | Primary OS interface |
+| **blackroad-os-master** | `blackroad-os-master-production.up.railway.app` | Master orchestration service |
+| **blackroad-os-core** | `blackroad-os-core-production.up.railway.app` | Core backend API, auth, blockchain |
+
+### API Services
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| **blackroad-os-api** | `blackroad-os-api-production-3335.up.railway.app` | Public API service |
+| **blackroad-os-api-gateway** | `blackroad-os-api-gateway-production.up.railway.app` | API gateway/routing |
+
+### Frontend Services
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| **blackroad-os-home** | `blackroad-os-home-production.up.railway.app` | Home/landing page |
+| **blackroad-os-web** | `blackroad-os-web-production.up.railway.app` | Web client interface |
+| **blackroad-os-docs** | `blackroad-os-docs-production-f7af.up.railway.app` | Documentation site |
+| **blackroad-os-demo** | `blackroad-os-demo-production.up.railway.app` | Demo environment |
+
+### Infrastructure Services
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| **blackroad-os-infra** | `blackroad-os-infra-production.up.railway.app` | Infrastructure management |
+| **blackroad-os-operator** | `operator.blackroad.systems` | GitHub automation, PR orchestration |
+| **blackroad-os-beacon** | `beacon.blackroad.systems` | Health monitoring/beacon service |
+| **blackroad-os-archive** | `blackroad-os-archive-production.up.railway.app` | Archive/storage service |
+
+### Pack Services (Modular Extensions)
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| **blackroad-os-pack-creator-studio** | `blackroad-os-pack-creator-studio-production.up.railway.app` | Creator tools pack |
+| **blackroad-os-pack-research-lab** | `blackroad-os-pack-research-lab-production.up.railway.app` | Research tools pack |
+| **blackroad-os-pack-finance** | `blackroad-os-pack-finance-production.up.railway.app` | Finance tools pack |
+| **blackroad-os-pack-infra-devops** | `blackroad-os-pack-infra-devops-production.up.railway.app` | DevOps tools pack |
+| **blackroad-os-pack-legal** | `blackroad-os-pack-legal-production.up.railway.app` | Legal/compliance pack |
+
+### Specialized Services
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| **blackroad-prism-console** | `prism.blackroad.systems` | Prism AI orchestration console |
+| **blackroad-os-research** | `blackroad-os-research-production.up.railway.app` | Research platform |
+| **terrific-intuition** | `terrific-intuition-production.up.railway.app` | Experimental service |
+
+---
+
+## Custom Domains (Cloudflare DNS)
+
+The following services have custom domains configured via Cloudflare:
+
+| Domain | Service | Type |
+|--------|---------|------|
+| `operator.blackroad.systems` | blackroad-os-operator | CNAME |
+| `beacon.blackroad.systems` | blackroad-os-beacon | CNAME |
+| `prism.blackroad.systems` | blackroad-prism-console | CNAME |
+
+---
+
+## Environment Variables
+
+All services share the following Railway-injected environment variables:
+
+```
+RAILWAY_ENVIRONMENT=production
+RAILWAY_ENVIRONMENT_ID=57e6ac32-0e86-4bde-a337-948535e27bcc
+RAILWAY_ENVIRONMENT_NAME=production
+RAILWAY_PROJECT_ID=03ce1e43-5086-4255-b2bc-0146c8916f4c
+RAILWAY_PROJECT_NAME=BlackRoad OS
+```
+
+### Service URL References
+
+Services can reference each other using these environment variables:
+
+```
+RAILWAY_SERVICE_BLACKROAD_OS_API_GATEWAY_URL=blackroad-os-api-gateway-production.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_API_URL=blackroad-os-api-production-3335.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_BEACON_URL=beacon.blackroad.systems
+RAILWAY_SERVICE_BLACKROAD_OS_CORE_URL=blackroad-os-core-production.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_DOCS_URL=blackroad-os-docs-production-f7af.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_HOME_URL=blackroad-os-home-production.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_INFRA_URL=blackroad-os-infra-production.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_MASTER_URL=blackroad-os-master-production.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_PACK_RESEARCH_LAB_URL=blackroad-os-pack-research-lab-production.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_OS_URL=blackroad-os-production.up.railway.app
+RAILWAY_SERVICE_BLACKROAD_PRISM_CONSOLE_URL=prism.blackroad.systems
+```
+
+---
+
+## Internal Communication
+
+For service-to-service communication within Railway, use internal DNS:
+
+```
+http://{service-name}.railway.internal:{PORT}
+```
+
+Example:
+```
+http://blackroad.railway.internal:8000
+```
+
+---
+
+## Health Checks
+
+All services should implement the following health check endpoints:
+
+- `GET /health` - Basic health check
+- `GET /v1/sys/health` - Detailed system health (Syscall API)
+- `GET /v1/sys/identity` - Service identity information
+
+---
+
+## Deployment
+
+### Railway CLI Commands
+
+```bash
+# Link to project
+railway link -p 03ce1e43-5086-4255-b2bc-0146c8916f4c
+
+# Check status
+railway status
+
+# View logs
+railway logs
+
+# Deploy
+railway up
+
+# View variables
+railway variables
+```
+
+### Automatic Deployments
+
+Services are configured for automatic deployment when:
+1. Code is pushed to linked GitHub repositories
+2. Manual deploy triggered via Railway dashboard
+3. Railway CLI `railway up` command
+
+---
+
+## Architecture Diagram
+
+```
+                                    Cloudflare DNS
+                                         │
+              ┌──────────────────────────┼──────────────────────────┐
+              │                          │                          │
+    operator.blackroad.systems    beacon.blackroad.systems    prism.blackroad.systems
+              │                          │                          │
+              ▼                          ▼                          ▼
+    ┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐
+    │  blackroad-os-  │        │  blackroad-os-  │        │   blackroad-    │
+    │    operator     │        │     beacon      │        │  prism-console  │
+    └─────────────────┘        └─────────────────┘        └─────────────────┘
+              │                          │                          │
+              └──────────────────────────┼──────────────────────────┘
+                                         │
+                            Railway Internal Network
+                                         │
+    ┌────────────┬────────────┬─────────┴─────────┬────────────┬────────────┐
+    │            │            │                   │            │            │
+    ▼            ▼            ▼                   ▼            ▼            ▼
+┌────────┐  ┌────────┐  ┌──────────┐         ┌────────┐  ┌────────┐  ┌────────┐
+│  core  │  │  api   │  │ api-     │         │  web   │  │  docs  │  │ infra  │
+│        │  │        │  │ gateway  │         │        │  │        │  │        │
+└────────┘  └────────┘  └──────────┘         └────────┘  └────────┘  └────────┘
+    │            │            │                   │            │            │
+    └────────────┴────────────┴─────────┬─────────┴────────────┴────────────┘
+                                        │
+                              ┌─────────┴─────────┐
+                              │    Pack Services   │
+                              │  (creator-studio,  │
+                              │  research-lab,     │
+                              │  finance, legal,   │
+                              │  infra-devops)     │
+                              └───────────────────┘
+```
+
+---
+
+## Related Documentation
+
+- `railway.json` - Service definitions and IDs
+- `railway.toml` - Build and deploy configuration (root of repo)
+- `.env.railway.example` - Environment variable template
+- `INFRASTRUCTURE.md` - Full infrastructure documentation
+- `SYSCALL_API.md` - Standard API specification
+
+---
+
+*This document is auto-generated and maintained. Last sync: 2025-11-29*
--- a/infra/railway/railway.json
+++ b/infra/railway/railway.json
@@ -0,0 +1,103 @@
+{
+  "$schema": "https://railway.app/railway.schema.json",
+  "project": {
+    "id": "03ce1e43-5086-4255-b2bc-0146c8916f4c",
+    "name": "BlackRoad OS",
+    "workspace": "BlackRoad OS, Inc."
+  },
+  "environment": {
+    "id": "57e6ac32-0e86-4bde-a337-948535e27bcc",
+    "name": "production"
+  },
+  "services": [
+    {
+      "name": "blackroad",
+      "id": "fb011c5c-a007-4cb6-8955-eefb7b5f76a2",
+      "internalDomain": "blackroad.railway.internal"
+    },
+    {
+      "name": "blackroad-os",
+      "url": "blackroad-os-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-master",
+      "url": "blackroad-os-master-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-home",
+      "url": "blackroad-os-home-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-operator",
+      "url": "operator.blackroad.systems"
+    },
+    {
+      "name": "blackroad-os-beacon",
+      "url": "beacon.blackroad.systems"
+    },
+    {
+      "name": "blackroad-os-pack-creator-studio",
+      "url": "blackroad-os-pack-creator-studio-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-research",
+      "url": "blackroad-os-research-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-pack-research-lab",
+      "url": "blackroad-os-pack-research-lab-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-pack-finance",
+      "url": "blackroad-os-pack-finance-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-infra",
+      "url": "blackroad-os-infra-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-core",
+      "url": "blackroad-os-core-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-api-gateway",
+      "url": "blackroad-os-api-gateway-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-api",
+      "url": "blackroad-os-api-production-3335.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-web",
+      "url": "blackroad-os-web-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-archive",
+      "url": "blackroad-os-archive-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-pack-infra-devops",
+      "url": "blackroad-os-pack-infra-devops-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-prism-console",
+      "url": "prism.blackroad.systems"
+    },
+    {
+      "name": "blackroad-os-demo",
+      "url": "blackroad-os-demo-production.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-docs",
+      "url": "blackroad-os-docs-production-f7af.up.railway.app"
+    },
+    {
+      "name": "blackroad-os-pack-legal",
+      "url": "blackroad-os-pack-legal-production.up.railway.app"
+    },
+    {
+      "name": "terrific-intuition",
+      "url": "terrific-intuition-production.up.railway.app"
+    }
+  ]
+}