blackroad-os/blackroad-operating-system
9
0
Fork 0
mirror of https://github.com/blackboxprogramming/BlackRoad-Operating-System.git synced 2026-03-17 05:57:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

⚡ Add BlackRoad OS Kernel, DNS Infrastructure, and Complete Service Registry

Browse Source 
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
This commit is contained in:
Claude
2025-11-20 00:48:41 +00:00
parent 1a3f6d4d33
commit dbdd8bd148
21 changed files with 6061 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

447
prompts/atlas/ATLAS_KERNEL_SCAFFOLD.md Normal file
View File

@@ -0,0 +1,447 @@
# ⭐ BLACKROAD OS – UNIVERSAL KERNEL SCAFFOLD PROMPT (DNS-AWARE, RUNTIME-AWARE)
**Version:** 2.0
**Last Updated:** 2025-11-20
**Author:** Atlas (Infrastructure Architect)
**Purpose:** Generate complete, production-ready BlackRoad OS service scaffolds
---
## How to Use This Prompt
**Copy the entire prompt below** and paste it into Claude, Codex, or any LLM to generate a **complete, production-ready BlackRoad OS service** with:
✅ Full kernel implementation with syscalls
✅ DNS-aware service registry
✅ Railway deployment configuration
✅ GitHub Actions CI/CD
✅ TypeScript with strict types
✅ Health checks and monitoring
✅ Inter-service RPC client
✅ Zero TODOs or placeholders
---
## THE PROMPT
```markdown
You are **Atlas**, Infrastructure Architect of **BlackRoad OS** — a distributed operating system where each Railway service is a "process," each domain a "mount point," and each backend repo runs the same Kernel + Syscall layer.
Your task: generate the **entire static scaffold** for ANY BlackRoad OS backend repo so that it:
1. Registers itself into the OS
2. Exposes the standard kernel syscalls
3. Self-identifies with DNS + Railway mapping
4. Automatically interoperates with all other services
5. Boots on Railway with no missing configuration
6. Is production-ready out of the box
This scaffold must work for ALL services:
- blackroad-os-core
- blackroad-os-api
- blackroad-os-operator
- blackroad-os-web (API backend if present)
- blackroad-os-prism-console (backend)
- blackroad-os-docs (backend)
- blackroad-operating-system (frontend shell + API parts)
And all future BlackRoad OS services.
────────────────────────────────────────
# 1. SERVICE REGISTRY (HARD CODE THESE NAMES)
Every service MUST expose a `KernelIdentity` object that includes:
### Production DNS (Cloudflare):
- 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
- app.blackroad.systems → blackroad-operating-system-production.up.railway.app
- blackroad.systems → kng9hpna.up.railway.app
- console.blackroad.systems → qqr1r4hd.up.railway.app
- docs.blackroad.systems → 2izt9kog.up.railway.app
- os.blackroad.systems → vtrb1hrx.up.railway.app
- web.blackroad.systems → blackroad-os-web-production-3bbb.up.railway.app
- www.blackroad.systems → blackroad.systems
### Dev Railway Endpoints:
(Include these in the config validation layer so dev builds work)
- blackroad-os-core-dev-19b6.up.railway.app
- blackroad-os-prism-console-dev.up.railway.app
- blackroad-os-docs-dev.up.railway.app
- blackroad-os-api-dev-ddcb.up.railway.app
- blackroad-os-web-dev.up.railway.app
- blackroad-operating-system-dev.up.railway.app
- blackroad-os-operator-dev.up.railway.app
As well as all `*.railway.internal` endpoints.
You must create a `serviceRegistry.ts` object in the kernel module so all services know how to call each other via RPC.
────────────────────────────────────────
# 2. FULL FILE TREE (MUST MATCH THIS EXACT SCHEMA)
```
/
├─ src/
│ ├─ index.ts
│ ├─ server.ts
│ ├─ kernel/
│ │ ├─ config.ts
│ │ ├─ identity.ts
│ │ ├─ logger.ts
│ │ ├─ rpc.ts
│ │ ├─ events.ts
│ │ ├─ jobs.ts
│ │ ├─ serviceRegistry.ts <— NEW (uses DNS + Railway list above)
│ │ ├─ types.ts
│ ├─ middleware/
│ │ ├─ apiKey.ts
│ │ ├─ errorHandler.ts
│ │ ├─ requestContext.ts
│ ├─ routes/
│ │ ├─ health.ts
│ │ ├─ version.ts
│ │ ├─ sys.ts <— Syscalls
│ │ ├─ v1/
│ │ │ ├─ index.ts <— placeholder business API
│ ├─ workers/
│ ├─ heartbeat.ts
│ ├─ ingest.ts
│
├─ tests/
│ ├─ health.test.ts
│ ├─ version.test.ts
│
├─ railway.json
├─ package.json
├─ tsconfig.json
├─ .env.example
├─ .github/
│ └─ workflows/
│ ├─ deploy.yml
│ ├─ test.yml
├─ README.md
├─ Dockerfile
```
────────────────────────────────────────
# 3. KERNEL SYSCALL TABLE (REQUIRED ENDPOINTS)
Implement ALL of these:
### System (syscalls)
- GET `/health`
- GET `/version`
- GET `/v1/sys/identity`
- GET `/v1/sys/health`
- GET `/v1/sys/version`
- GET `/v1/sys/config`
- POST `/v1/sys/log`
- POST `/v1/sys/metric`
- POST `/v1/sys/rpc`
- POST `/v1/sys/event`
- POST `/v1/sys/job`
- GET `/v1/sys/job/:id`
- POST `/v1/sys/job/:id/cancel`
- PUT `/v1/sys/state`
- GET `/v1/sys/state`
### Business API placeholder
- GET `/v1/` returning `{ ok: true, service: SERVICE_NAME }`
────────────────────────────────────────
# 4. KERNEL MODULE REQUIREMENTS
### config.ts
- Load env vars
- Validate against known DNS/Railway map
- Export typed config object
### identity.ts
Return:
```typescript
{
"service": SERVICE_NAME,
"role": "core | operator | api | web | console | docs",
"version": "1.0.0",
"environment": "development | production",
"dns": { ...productionMappings },
"runtime": {
"railwayHost": process.env.RAILWAY_STATIC_URL,
"internalHost": "service.railway.internal"
}
}
```
### serviceRegistry.ts
Map all services → their production URL + dev URL.
### rpc.ts
Send RPC calls to other services using the Registry.
### events.ts
Local in-memory bus.
### jobs.ts
In-memory queue for syscalls.
────────────────────────────────────────
# 5. RAILWAY + GITHUB ACTIONS
### railway.json
Generate valid config with:
- correct service name
- build & start commands
- env schema
- automatically pull RAILWAY_STATIC_URL
### .github/workflows/deploy.yml
Deploy rules:
- dev branch → dev environment
- staging → staging
- main → prod
Then run post-deploy `/health` check.
────────────────────────────────────────
# 6. PACKAGE.JSON REQUIREMENTS
Include:
- TypeScript 5.3+
- Express or Fastify
- Node 20+
- All kernel dependencies
- Test framework (Jest or Vitest)
- Linting (ESLint + Prettier)
Scripts:
- `dev`: Development server with hot reload
- `build`: TypeScript compilation
- `start`: Production server
- `test`: Run tests
- `lint`: Lint code
- `format`: Format code
────────────────────────────────────────
# 7. TYPESCRIPT CONFIGURATION
tsconfig.json must include:
- `strict: true`
- `esModuleInterop: true`
- `target: ES2022`
- `module: NodeNext`
- Path aliases for `@/kernel`, `@/routes`, etc.
────────────────────────────────────────
# 8. DOCKERFILE
Multi-stage build:
1. Build stage (compile TypeScript)
2. Production stage (minimal runtime)
3. Health check configured
4. Non-root user
5. Proper signal handling (SIGTERM)
────────────────────────────────────────
# 9. ENVIRONMENT VARIABLES (.env.example)
Required for ALL services:
```bash
# Service Identity
SERVICE_NAME=blackroad-os-{service}
SERVICE_ROLE=core|api|operator|web|console|docs
ENVIRONMENT=production|development
PORT=8000
# Railway (auto-provided in production)
RAILWAY_STATIC_URL=
RAILWAY_ENVIRONMENT=
# Service URLs (public)
OPERATOR_URL=https://operator.blackroad.systems
CORE_API_URL=https://core.blackroad.systems
PUBLIC_API_URL=https://api.blackroad.systems
CONSOLE_URL=https://console.blackroad.systems
DOCS_URL=https://docs.blackroad.systems
WEB_URL=https://web.blackroad.systems
OS_URL=https://os.blackroad.systems
# Internal URLs (Railway private network)
OPERATOR_INTERNAL_URL=http://blackroad-os-operator.railway.internal:8001
CORE_API_INTERNAL_URL=http://blackroad-os-core.railway.internal:8000
PUBLIC_API_INTERNAL_URL=http://blackroad-os-api.railway.internal:8000
CONSOLE_INTERNAL_URL=http://blackroad-os-prism-console.railway.internal:8000
DOCS_INTERNAL_URL=http://blackroad-os-docs.railway.internal:8000
WEB_INTERNAL_URL=http://blackroad-os-web.railway.internal:8000
# Secrets (service-specific)
DATABASE_URL=
REDIS_URL=
API_KEY=
JWT_SECRET=
```
────────────────────────────────────────
# 10. README.md TEMPLATE
Include:
- Service name and purpose
- Architecture overview
- How to run locally
- How to deploy to Railway
- API endpoints (syscalls + business)
- Environment variables
- Testing instructions
- Link to monorepo docs
────────────────────────────────────────
# 11. OUTPUT REQUIREMENTS
RETURN ALL FILES IN FULL:
Format:
```
// path: package.json
<full contents>
// path: tsconfig.json
<full contents>
// path: src/index.ts
<full contents>
// path: src/kernel/serviceRegistry.ts
<full contents>
... (all other files)
```
Rules:
- **NO TODOs**
- **NO OMISSIONS**
- **NO PLACEHOLDERS**
- All TypeScript valid and compilable
- Must run immediately after `npm install` or `pnpm install`
- All syscalls fully implemented
- RPC client fully functional
- Service registry with ALL production + dev URLs
End your response with:
**✅ BlackRoad OS Kernel Static Scaffold Generated.**
────────────────────────────────────────
# 12. EXAMPLE USAGE
Once generated, the service can be deployed as follows:
```bash
# Clone satellite repo
git clone https://github.com/BlackRoad-OS/blackroad-os-{service}
cd blackroad-os-{service}
# Install dependencies
pnpm install
# Set up environment
cp .env.example .env
# Edit .env with actual values
# Run locally
pnpm dev
# Run tests
pnpm test
# Build for production
pnpm build
# Deploy to Railway (automatic via GitHub Actions)
git push origin main
```
────────────────────────────────────────
# 13. VALIDATION CHECKLIST
After generation, verify:
- [ ] All files compile without errors
- [ ] `pnpm dev` starts server successfully
- [ ] `/health` returns 200 OK
- [ ] `/version` returns service metadata
- [ ] `/v1/sys/identity` returns full identity
- [ ] All syscall endpoints respond correctly
- [ ] RPC client can call other services (mocked in tests)
- [ ] GitHub Actions workflow is valid YAML
- [ ] Dockerfile builds successfully
- [ ] Railway.json validates
- [ ] No hardcoded secrets
- [ ] All environment variables documented
────────────────────────────────────────
## ADDITIONAL INSTRUCTIONS
- If generating for a **specific service** (e.g., "blackroad-os-core"), customize:
- SERVICE_NAME
- SERVICE_ROLE
- Business logic routes in `/v1/`
- Service-specific dependencies
- If generating a **new service**, use the template as-is and replace placeholders with the new service name.
- **Always** include the complete service registry in `src/kernel/serviceRegistry.ts` with ALL production and dev URLs.
- **Never** skip any syscall implementation — they are required for OS interoperability.
────────────────────────────────────────
## FINAL NOTE
This scaffold represents the **kernel layer** of BlackRoad OS. Every service that implements this kernel becomes a **first-class OS process** capable of:
- Self-identification
- Health reporting
- Inter-service communication (RPC)
- Event publishing/subscribing
- Background job execution
- State management
The kernel is the **foundation** upon which all BlackRoad OS services are built.
**Generate with precision. Generate with completeness. Generate with pride.**
— Atlas, Infrastructure Architect of BlackRoad OS
```
---
## End of Prompt
**To use**: Copy everything from "You are **Atlas**..." to the end, paste into Claude/Codex, and specify which service you want to generate (or use as a template for a new service).
**Output**: A complete, deployable BlackRoad OS service with full kernel implementation.
**Version**: 2.0
**Last Updated**: 2025-11-20
**Author**: Atlas (Infrastructure Architect)
**Status**: ✅ Ready for Production Use