## Summary
- update ops/domains.yaml to list all BlackRoad domains and subdomains
with Cloudflare-managed DNS targets
- point blackroad.systems apex to the Vercel corporate site and map key
subdomains to their Railway/Vercel services with healthcheck flags
- add aliases and placeholders for secondary and tertiary domains to
converge DNS in one registry
## Testing
- not run (not requested)
------
[Codex
Task](https://chatgpt.com/codex/tasks/task_e_691f97383dd08329872553921e433350)
## Summary
- add a go-live runbook covering Cloudflare, Vercel, and Railway steps
to bring sites up across all domains
- document per-domain DNS targets and proxy expectations for primary,
secondary, and tertiary domains
- include validation commands and rollback guidance for troubleshooting
deployments
## Testing
- not run (documentation only)
------
[Codex
Task](https://chatgpt.com/codex/tasks/task_e_691f964ad16483298dc425b69d2e836e)
## Summary
- add backend/.env populated with production-style Postgres/Redis, auth,
API, and integration keys for running uvicorn
- fix .env.example formatting and include missing Prism URLs so it
aligns with app.config.Settings
- adjust gitignore to allow tracking backend/.env for configuration
sharing
## Testing
- python scripts/railway/validate_env_template.py --skip-config
------
[Codex
Task](https://chatgpt.com/codex/tasks/task_e_691f92c1c67c83299b55783161ed067d)
## Summary
- reinforce that deployments must target the satellite repositories and
not the monorepo
- document that the supported UI entry point is
backend/static/index.html and to avoid the legacy blackroad-os bundle
## Testing
- Not run (documentation changes only)
------
[Codex
Task](https://chatgpt.com/codex/tasks/task_e_691f92be93288329867444ec95e4bb7f)
This commit implements the complete backend infrastructure for the BR-95
Desktop Operating System interface.
## New Features
1. **BR-95 Router** (`backend/app/routers/br95.py`):
- Data simulator for OS statistics
- 11+ API endpoints for real-time data
- WebSocket support for live updates
- Pydantic models for type safety
2. **API Endpoints** (`/api/br95`):
- `/lucidia` - AI orchestration stats (1000 agents)
- `/agents` - Agent performance metrics
- `/roadchain` - Blockchain statistics
- `/wallet` - RoadCoin wallet balance
- `/miner` - Mining performance
- `/raspberry-pi` - IoT device management
- `/github` - GitHub integration stats
- `/roadmail` - Email statistics
- `/roadcraft` - Game statistics
- `/road-city` - Metaverse statistics
- `/terminal` - Command execution (simulated)
3. **WebSocket** (`/api/br95/ws`):
- Real-time miner updates
- Live blockchain sync
- Wallet balance streaming
- Auto-reconnect on disconnect
4. **Frontend Integration**:
- Updated BR-95 HTML with API calls
- WebSocket client for live updates
- Auto-refresh every 30 seconds
- Real-time stat updates in windows
5. **Railway Deployment**:
- Already configured via railway.toml
- Health check at /health
- Version endpoint at /version
- Documentation in docs/RAILWAY_BR95.md
## Technical Details
- **Data Simulation**: Uses DataSimulator class for realistic stats
- **WebSocket Manager**: ConnectionManager for broadcast messaging
- **Type Safety**: Full Pydantic model validation
- **Performance**: psutil for real CPU/memory metrics
- **Error Handling**: Graceful fallbacks and reconnection
## Deployment
Service runs on:
- Primary: https://app.blackroad.systems
- Railway: https://blackroad-operating-system-production.up.railway.app
Health check: GET /health
Version info: GET /version
API docs: GET /api/docs
## Files Changed
- backend/app/main.py - Registered br95 router
- backend/requirements.txt - Added psutil==5.9.6
- backend/static/index.html - API integration + WebSocket
- backend/app/routers/br95.py - New BR-95 router (700+ lines)
- docs/RAILWAY_BR95.md - Deployment guide
Closes#133 (if exists) - BR-95 backend implementation
# Summary
<!-- High-level explanation of the change and the services it touches
-->
## Checklist
- [ ] Linked the relevant issue or task
- [ ] Updated docs or specs if behavior changed
- [ ] Added or adjusted tests (or noted why not needed)
- [ ] Ran required checks locally (lint/test/build)
## Testing
<!-- List commands run locally, e.g. npm test -->
## Notes
<!-- Deployment impacts, follow-ups, or escalations -->
Updates:
- Add app.blackroad.systems to ALLOWED_ORIGINS in both .env.example and
config.py
- Add blackroad-operating-system-production.up.railway.app to
ALLOWED_ORIGINS
- Update DNS.md to reflect current domain routing (both root and app
subdomains point to same service)
- Ensures CORS works correctly for all production domains
This fixes CORS issues when accessing the application via
app.blackroad.systems or blackroad.systems on the Railway project
'gregarious-wonder' (blackroad-operating-system-production service).
# Summary
<!-- High-level explanation of the change and the services it touches
-->
## Checklist
- [ ] Linked the relevant issue or task
- [ ] Updated docs or specs if behavior changed
- [ ] Added or adjusted tests (or noted why not needed)
- [ ] Ran required checks locally (lint/test/build)
## Testing
<!-- List commands run locally, e.g. npm test -->
## Notes
<!-- Deployment impacts, follow-ups, or escalations -->
Updates:
- Add app.blackroad.systems to ALLOWED_ORIGINS in both .env.example and config.py
- Add blackroad-operating-system-production.up.railway.app to ALLOWED_ORIGINS
- Update DNS.md to reflect current domain routing (both root and app subdomains point to same service)
- Ensures CORS works correctly for all production domains
This fixes CORS issues when accessing the application via app.blackroad.systems or blackroad.systems
on the Railway project 'gregarious-wonder' (blackroad-operating-system-production service).
This commit fixes the Railway build failure by:
1. **Root requirements.txt**: Added root-level requirements.txt that
references backend/requirements.txt, enabling Railway's Nixpacks to
auto-detect Python project and install dependencies correctly. Fixes
"pip: not found" error.
2. **backend/__init__.py**: Created package init file to make backend a
proper Python package, allowing uvicorn to import backend.app.main.
3. **railway.toml**: Simplified configuration for single-service
monorepo deployment:
- Uses NIXPACKS builder (auto-detects Python)
- Starts with: uvicorn backend.app.main:app --host 0.0.0.0 --port $PORT
- Health check at /health
- Configured for app.blackroad.systems deployment
Technical details:
- Backend entrypoint: backend/app/main.py:app (FastAPI)
- Health endpoint: /health returns JSON with service status
- Frontend: BR-95 desktop UI served at / from backend/static/index.html
- API health: /api/health provides comprehensive integration status
Deployment target:
- Railway project: gregarious-wonder
- Service: BlackRoad-Operating-System
- Domain: app.blackroad.systems
# Summary
<!-- High-level explanation of the change and the services it touches
-->
## Checklist
- [ ] Linked the relevant issue or task
- [ ] Updated docs or specs if behavior changed
- [ ] Added or adjusted tests (or noted why not needed)
- [ ] Ran required checks locally (lint/test/build)
## Testing
<!-- List commands run locally, e.g. npm test -->
## Notes
<!-- Deployment impacts, follow-ups, or escalations -->
## Summary
- replace the backend static index page with the BR‑95 edition desktop
experience, including boot screen, icons, and app windows
- restyle the interface with branded gradients, retro window chrome, and
taskbar/road menu controls
- keep interactive behaviors for opening, minimizing, maximizing,
dragging, and tracking windows
## Testing
- not run (not applicable)
------
[Codex
Task](https://chatgpt.com/codex/tasks/task_e_691f75f4d5688329aa740b5969a38cb7)
- Add SERVICE_STATUS.md: Complete analysis of all blackroad.systems services
- Add check_all_services.sh: Automated service health checker script
- Add minimal-service template: Production-ready FastAPI service template
Service Status Findings:
- All 9 services return 403 Forbidden (Cloudflare blocking)
- Services are deployed and DNS is working correctly
- Issue is Cloudflare WAF/security rules, not service implementation
Template Features:
- Complete syscall API compliance (/v1/sys/*)
- Railway deployment ready
- CORS configuration
- Health and version endpoints
- HTML "Hello World" landing page
- OpenAPI documentation
Existing Service Implementations:
✓ Core API (services/core-api)
✓ Public API (services/public-api)
✓ Operator (operator_engine)
✓ Prism Console (prism-console)
✓ App/Shell (backend)
Next Steps:
1. Configure Cloudflare WAF to allow health check endpoints
2. Use minimal-service template for missing services
3. Implement full syscall API in existing services
4. Test inter-service RPC communication
Refs: #125
Introduces scripts/cece_audit.py - a complete local system auditor that
checks:
- Repository structure and expected files
- Service registry and DNS configuration
- Kernel integration and syscall API
- Infrastructure configs (Railway, Docker)
- GitHub workflows and templates
- Backend/frontend structure
- Documentation completeness
- Cross-references and consistency
Provides instant health check with zero external dependencies:
- 0 CRITICAL, 3 ERRORS, 6 WARNINGS, 91 SUCCESSES
- Identifies single source of truth for all components
- Shows minimal set needed to run the OS
- Pure filesystem analysis - no API calls, no cost
Run: python scripts/cece_audit.py
# Pull Request
## Description
<!-- Provide a brief description of the changes in this PR -->
## Type of Change
<!-- Mark the relevant option with an 'x' -->
- [ ] 📝 Documentation update
- [ ] 🧪 Tests only
- [ ] 🏗️ Scaffolding/stubs
- [ ] ✨ New feature
- [ ] 🐛 Bug fix
- [ ] ♻️ Refactoring
- [ ] ⚙️ Infrastructure/CI
- [ ] 📦 Dependencies update
- [ ] 🔒 Security fix
- [ ] 💥 Breaking change
## Checklist
<!-- Mark completed items with an 'x' -->
- [ ] Code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
## Auto-Merge Eligibility
<!-- This section helps determine if this PR qualifies for auto-merge
-->
**Eligible for auto-merge?**
- [ ] Yes - This is a docs-only, tests-only, or small AI-generated PR
- [ ] No - Requires human review
**Reason for auto-merge eligibility:**
- [ ] Docs-only (Tier 1)
- [ ] Tests-only (Tier 2)
- [ ] Scaffolding < 200 lines (Tier 3)
- [ ] AI-generated < 500 lines (Tier 4)
- [ ] Dependency patch/minor (Tier 5)
**If not auto-merge eligible, why?**
- [ ] Breaking change
- [ ] Security-related
- [ ] Infrastructure changes
- [ ] Requires discussion
- [ ] Large PR (> 500 lines)
## Related Issues
<!-- Link to related issues -->
Closes #
Related to #
## Test Plan
<!-- Describe how you tested these changes -->
## Screenshots (if applicable)
<!-- Add screenshots for UI changes -->
---
**Note**: This PR will be automatically labeled based on files changed.
See `GITHUB_AUTOMATION_RULES.md` for details.
If this PR meets auto-merge criteria (see `AUTO_MERGE_POLICY.md`), it
will be automatically approved and merged after checks pass.
For questions about the merge queue system, see `MERGE_QUEUE_PLAN.md`.
Introduces automated OS health checks on every push and PR:
Features:
- Runs Cece audit script on push to main and claude/** branches
- Runs on all PRs to main
- Manual trigger support via workflow_dispatch
- Fails build if CRITICAL issues found
- Warns if ERROR issues found (non-blocking)
- Generates GitHub step summary with audit results
- Uploads full audit report as artifact (30-day retention)
Checks:
- Repository structure
- Service registry & DNS consistency
- Kernel integration
- Infrastructure configs
- GitHub workflows
- Backend/frontend structure
- Documentation completeness
- Cross-references
This ensures the OS stays healthy and catches regressions early.
Introduces scripts/cece_audit.py - a complete local system auditor that checks:
- Repository structure and expected files
- Service registry and DNS configuration
- Kernel integration and syscall API
- Infrastructure configs (Railway, Docker)
- GitHub workflows and templates
- Backend/frontend structure
- Documentation completeness
- Cross-references and consistency
Provides instant health check with zero external dependencies:
- 0 CRITICAL, 3 ERRORS, 6 WARNINGS, 91 SUCCESSES
- Identifies single source of truth for all components
- Shows minimal set needed to run the OS
- Pure filesystem analysis - no API calls, no cost
Run: python scripts/cece_audit.py
…egistry
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
# Pull Request
## Description
<!-- Provide a brief description of the changes in this PR -->
## Type of Change
<!-- Mark the relevant option with an 'x' -->
- [ ] 📝 Documentation update
- [ ] 🧪 Tests only
- [ ] 🏗️ Scaffolding/stubs
- [ ] ✨ New feature
- [ ] 🐛 Bug fix
- [ ] ♻️ Refactoring
- [ ] ⚙️ Infrastructure/CI
- [ ] 📦 Dependencies update
- [ ] 🔒 Security fix
- [ ] 💥 Breaking change
## Checklist
<!-- Mark completed items with an 'x' -->
- [ ] Code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
## Auto-Merge Eligibility
<!-- This section helps determine if this PR qualifies for auto-merge
-->
**Eligible for auto-merge?**
- [ ] Yes - This is a docs-only, tests-only, or small AI-generated PR
- [ ] No - Requires human review
**Reason for auto-merge eligibility:**
- [ ] Docs-only (Tier 1)
- [ ] Tests-only (Tier 2)
- [ ] Scaffolding < 200 lines (Tier 3)
- [ ] AI-generated < 500 lines (Tier 4)
- [ ] Dependency patch/minor (Tier 5)
**If not auto-merge eligible, why?**
- [ ] Breaking change
- [ ] Security-related
- [ ] Infrastructure changes
- [ ] Requires discussion
- [ ] Large PR (> 500 lines)
## Related Issues
<!-- Link to related issues -->
Closes #
Related to #
## Test Plan
<!-- Describe how you tested these changes -->
## Screenshots (if applicable)
<!-- Add screenshots for UI changes -->
---
**Note**: This PR will be automatically labeled based on files changed.
See `GITHUB_AUTOMATION_RULES.md` for details.
If this PR meets auto-merge criteria (see `AUTO_MERGE_POLICY.md`), it
will be automatically approved and merged after checks pass.
For questions about the merge queue system, see `MERGE_QUEUE_PLAN.md`.
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
…ay services
CRITICAL CHANGES:
- Add comprehensive deployment architecture documentation
- Prevent misconfiguration where monorepo is deployed instead of
satellites
- Clarify monorepo-to-satellite sync model across all docs
CHANGES:
1. railway.toml
- Add critical warning banner at top of file
- Mark config as local development/testing only
- Explain correct deployment model (satellites, not monorepo)
2. DEPLOYMENT_ARCHITECTURE.md (NEW)
- Complete 500+ line deployment guide
- Monorepo vs satellite model explained in detail
- Critical rules: NEVER add monorepo to Railway
- Service-to-repository mapping
- Environment configuration guide
- Cloudflare DNS configuration
- Common mistakes and troubleshooting
3. README.md
- Add prominent deployment warning box
- Clarify monorepo is source of truth, not deployable
- List satellite repos that should be deployed
- Reference DEPLOYMENT_ARCHITECTURE.md
4. CLAUDE.md
- Add critical deployment model section
- Clarify Railway deployment is satellite-only
- Update deployment workflow explanation
- Add key rules for deployment
5. backend/.env.example
- Fix ALLOWED_ORIGINS to reference satellites
- Remove monorepo Railway URL reference
- Add correct satellite service URLs
6. ops/domains.yaml
- Fix os.blackroad.systems DNS target
- Point to blackroad-os-core-production (satellite)
- Remove incorrect monorepo Railway URL
7. scripts/validate_deployment_config.py (NEW)
- Automated validation script
- Checks for monorepo references in configs
- Validates railway.toml, env files, DNS configs
- Ensures DEPLOYMENT_ARCHITECTURE.md exists
- Exit code 0 = pass, 1 = fail
WHY THIS MATTERS:
- Adding monorepo to Railway creates circular deploy loops
- Environment variables break (wrong service URLs)
- Cloudflare routing fails
- Service dependencies misconfigured
- Prevents production outages from misconfiguration
CORRECT MODEL:
- Monorepo = source of truth (orchestration only)
- Satellites = deployable services (Railway deployment)
- Code flows: monorepo → sync → satellite → Railway
See: DEPLOYMENT_ARCHITECTURE.md for complete details
# Pull Request
## Description
<!-- Provide a brief description of the changes in this PR -->
## Type of Change
<!-- Mark the relevant option with an 'x' -->
- [ ] 📝 Documentation update
- [ ] 🧪 Tests only
- [ ] 🏗️ Scaffolding/stubs
- [ ] ✨ New feature
- [ ] 🐛 Bug fix
- [ ] ♻️ Refactoring
- [ ] ⚙️ Infrastructure/CI
- [ ] 📦 Dependencies update
- [ ] 🔒 Security fix
- [ ] 💥 Breaking change
## Checklist
<!-- Mark completed items with an 'x' -->
- [ ] Code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
## Auto-Merge Eligibility
<!-- This section helps determine if this PR qualifies for auto-merge
-->
**Eligible for auto-merge?**
- [ ] Yes - This is a docs-only, tests-only, or small AI-generated PR
- [ ] No - Requires human review
**Reason for auto-merge eligibility:**
- [ ] Docs-only (Tier 1)
- [ ] Tests-only (Tier 2)
- [ ] Scaffolding < 200 lines (Tier 3)
- [ ] AI-generated < 500 lines (Tier 4)
- [ ] Dependency patch/minor (Tier 5)
**If not auto-merge eligible, why?**
- [ ] Breaking change
- [ ] Security-related
- [ ] Infrastructure changes
- [ ] Requires discussion
- [ ] Large PR (> 500 lines)
## Related Issues
<!-- Link to related issues -->
Closes #
Related to #
## Test Plan
<!-- Describe how you tested these changes -->
## Screenshots (if applicable)
<!-- Add screenshots for UI changes -->
---
**Note**: This PR will be automatically labeled based on files changed.
See `GITHUB_AUTOMATION_RULES.md` for details.
If this PR meets auto-merge criteria (see `AUTO_MERGE_POLICY.md`), it
will be automatically approved and merged after checks pass.
For questions about the merge queue system, see `MERGE_QUEUE_PLAN.md`.
