mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 04:57:15 -05:00
dbdd8bd148
This commit introduces a comprehensive infrastructure overhaul that transforms
BlackRoad OS into a true distributed operating system with unified kernel,
DNS-aware service discovery, and standardized syscall APIs.
## New Infrastructure Components
### 1. Kernel Module (kernel/typescript/)
- Complete TypeScript kernel implementation for all services
- Service registry with production and dev DNS mappings
- RPC client for inter-service communication
- Event bus, job queue, state management
- Structured logging with log levels
- Full type safety with TypeScript
Modules:
- types.ts: Complete type definitions
- serviceRegistry.ts: DNS-aware service discovery
- identity.ts: Service identity and metadata
- config.ts: Environment-aware configuration
- logger.ts: Structured logging
- rpc.ts: Inter-service RPC client
- events.ts: Event bus (pub/sub)
- jobs.ts: Background job queue
- state.ts: Key-value state management
- index.ts: Main exports
### 2. DNS Infrastructure Documentation (infra/DNS.md)
- Complete Cloudflare DNS mapping
- Railway production and dev endpoints
- Email configuration (MX, SPF, DKIM, DMARC)
- SSL/TLS, security, and monitoring settings
- Service-to-domain mapping
- Health check configuration
Production Services:
- operator.blackroad.systems
- core.blackroad.systems
- api.blackroad.systems
- console.blackroad.systems
- docs.blackroad.systems
- web.blackroad.systems
- os.blackroad.systems
- app.blackroad.systems
### 3. Service Registry & Architecture (INFRASTRUCTURE.md)
- Canonical service registry with all endpoints
- Monorepo-to-satellite deployment model
- Service-as-process architecture
- DNS-as-filesystem model
- Inter-service communication patterns
- Service lifecycle management
- Complete environment variable documentation
### 4. Syscall API Specification (SYSCALL_API.md)
- Standard kernel API for all services
- Required syscalls: health, version, identity, RPC
- Optional syscalls: logging, metrics, events, jobs, state
- Complete API documentation with examples
- Express.js implementation guide
Core Endpoints:
- GET /health
- GET /version
- GET /v1/sys/identity
- GET /v1/sys/health
- POST /v1/sys/rpc
- POST /v1/sys/event
- POST /v1/sys/job
- GET/PUT /v1/sys/state
### 5. Railway Deployment Guide (docs/RAILWAY_DEPLOYMENT.md)
- Step-by-step deployment instructions
- Environment variable configuration
- Monitoring and health checks
- Troubleshooting guide
- Best practices for Railway deployment
### 6. Atlas Kernel Scaffold Prompt (prompts/atlas/ATLAS_KERNEL_SCAFFOLD.md)
- Complete prompt for generating new services
- Auto-generates full kernel implementation
- Includes all DNS and Railway mappings
- Production-ready output with zero TODOs
### 7. GitHub Workflow Templates (templates/github-workflows/)
- deploy.yml: Railway auto-deployment
- test.yml: Test suite with coverage
- validate-kernel.yml: Kernel validation
- README.md: Template documentation
## Updated Files
### CLAUDE.md
- Added "Kernel Architecture & DNS Infrastructure" section
- Updated Table of Contents
- Added service architecture diagram
- Documented all new infrastructure files
- Updated repository structure with new directories
- Added kernel and infrastructure to critical path files
## Architecture Impact
This update establishes BlackRoad OS as a distributed operating system where:
- Each Railway service = OS process
- Each Cloudflare domain = mount point
- All services communicate via syscalls
- Unified kernel ensures interoperability
- DNS-aware service discovery
- Production and development environments
## Service Discovery
Services can now discover and call each other:
```typescript
import { rpc } from './kernel';
const user = await rpc.call('core', 'getUserById', { id: 123 });
```
## DNS Mappings
Production:
- operator.blackroad.systems → blackroad-os-operator-production-3983.up.railway.app
- core.blackroad.systems → 9gw4d0h2.up.railway.app
- api.blackroad.systems → ac7bx15h.up.railway.app
Internal (Railway):
- blackroad-os-operator.railway.internal:8001
- blackroad-os-core.railway.internal:8000
- blackroad-os-api.railway.internal:8000
## Next Steps
1. Sync kernel to satellite repos
2. Implement syscall endpoints in all services
3. Update services to use RPC for inter-service calls
4. Configure Cloudflare health checks
5. Deploy updated services to Railway
---
Files Added:
- INFRASTRUCTURE.md
- SYSCALL_API.md
- infra/DNS.md
- docs/RAILWAY_DEPLOYMENT.md
- kernel/typescript/* (9 modules + README)
- prompts/atlas/ATLAS_KERNEL_SCAFFOLD.md
- templates/github-workflows/* (4 files)
Files Modified:
- CLAUDE.md
Total: 22 new files, 1 updated file
94 lines
2.4 KiB
YAML
94 lines
2.4 KiB
YAML
# BlackRoad OS - Railway Deployment Workflow
|
|
#
|
|
# This workflow automatically deploys to Railway when code is pushed to main.
|
|
# Copy this file to .github/workflows/deploy.yml in your satellite repo.
|
|
#
|
|
# Required Secrets:
|
|
# - RAILWAY_TOKEN: Railway API token (get from railway.app)
|
|
#
|
|
# Usage:
|
|
# 1. Copy to .github/workflows/deploy.yml
|
|
# 2. Replace {SERVICE_NAME} with actual service name (e.g., "core", "api")
|
|
# 3. Replace {DOMAIN} with Cloudflare subdomain (e.g., "core", "api")
|
|
# 4. Add RAILWAY_TOKEN to GitHub repo secrets
|
|
|
|
name: Deploy to Railway
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
- main
|
|
workflow_dispatch:
|
|
|
|
jobs:
|
|
deploy:
|
|
name: Deploy to Production
|
|
runs-on: ubuntu-latest
|
|
|
|
steps:
|
|
- name: Checkout code
|
|
uses: actions/checkout@v4
|
|
|
|
- name: Setup Node.js
|
|
uses: actions/setup-node@v4
|
|
with:
|
|
node-version: '20'
|
|
cache: 'npm'
|
|
|
|
- name: Install dependencies
|
|
run: npm ci
|
|
|
|
- name: Run tests
|
|
run: npm test
|
|
continue-on-error: false
|
|
|
|
- name: Build application
|
|
run: npm run build
|
|
|
|
- name: Install Railway CLI
|
|
run: npm install -g @railway/cli
|
|
|
|
- name: Deploy to Railway
|
|
run: railway up --service blackroad-os-{SERVICE_NAME}-production
|
|
env:
|
|
RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
|
|
|
|
- name: Wait for deployment
|
|
run: sleep 15
|
|
|
|
- name: Health check
|
|
run: |
|
|
MAX_RETRIES=5
|
|
RETRY_COUNT=0
|
|
until [ $RETRY_COUNT -ge $MAX_RETRIES ]
|
|
do
|
|
if curl -f https://{DOMAIN}.blackroad.systems/health; then
|
|
echo "Health check passed!"
|
|
exit 0
|
|
fi
|
|
RETRY_COUNT=$((RETRY_COUNT+1))
|
|
echo "Health check failed, retrying... ($RETRY_COUNT/$MAX_RETRIES)"
|
|
sleep 5
|
|
done
|
|
echo "Health check failed after $MAX_RETRIES attempts"
|
|
exit 1
|
|
|
|
- name: Notify on failure
|
|
if: failure()
|
|
run: echo "Deployment failed! Check Railway logs."
|
|
|
|
notify:
|
|
name: Notify Deployment Status
|
|
runs-on: ubuntu-latest
|
|
needs: deploy
|
|
if: always()
|
|
|
|
steps:
|
|
- name: Deployment succeeded
|
|
if: needs.deploy.result == 'success'
|
|
run: echo "✅ Deployment to production succeeded"
|
|
|
|
- name: Deployment failed
|
|
if: needs.deploy.result == 'failure'
|
|
run: echo "❌ Deployment to production failed"
|