mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 09:37:55 -05:00
2609eaa3a5
- 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>
222 lines
9.4 KiB
Markdown
222 lines
9.4 KiB
Markdown
# 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*
|