blackroad-os/blackroad-operating-system
9
0
Fork 0
mirror of https://github.com/blackboxprogramming/BlackRoad-Operating-System.git synced 2026-03-17 07:57:19 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
0de6e35e97b95f9998b8a346f64004c274514b9f
blackroad-operating-system/infra/railway/SERVICES.md
Alexa Louise 2609eaa3a5 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>
2025-11-29 13:26:13 -06:00

9.4 KiB
Raw Blame History

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

# 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

Reference in New Issue View Git Blame Copy Permalink