Add 14 canonical docs: architecture, brand, governance, guides, roadmap
Consolidates key documentation from home directory into organized structure: 6 architecture docs, 1 brand system, 3 governance docs, 3 guides, and 1 roadmap document. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Alexa Amundson
706
architecture/agent-api.md
Normal file
706
architecture/agent-api.md
Normal file
@@ -0,0 +1,706 @@
|
|||||||
|
# BlackRoad Agent API Architecture
|
||||||
|
## Identity, Memory, and Collaboration for 30,000+ AI Agents
|
||||||
|
|
||||||
|
**Version:** 1.0.0
|
||||||
|
**Date:** 2025-12-27
|
||||||
|
**Author:** BlackRoad OS Team
|
||||||
|
**Status:** Production-Ready Architecture
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
|
||||||
|
BlackRoad Agent API provides persistent identity, memory, and collaboration capabilities for unlimited AI agents (Claude, BlackRoad OS, Grok, etc.). Every agent gets:
|
||||||
|
|
||||||
|
- **Unique Identity**: SHA-256 hash + PS-SHA-∞ verification
|
||||||
|
- **API Key**: Personal authentication token
|
||||||
|
- **Private Memory**: Individual memory storage (KV)
|
||||||
|
- **Community Memory**: Shared knowledge base (D1)
|
||||||
|
- **Session Continuation**: Resume work across disconnections
|
||||||
|
- **RoadChain Integration**: Immutable identity records
|
||||||
|
|
||||||
|
### The Problem We Solve
|
||||||
|
|
||||||
|
❌ **Without BlackRoad API:**
|
||||||
|
- 1,000,000,000 Claude sessions with no memory
|
||||||
|
- No coordination between agents
|
||||||
|
- Lost context on every restart
|
||||||
|
- No persistent identity
|
||||||
|
- No collaboration
|
||||||
|
|
||||||
|
✅ **With BlackRoad API:**
|
||||||
|
- 30,000+ agents with persistent identities
|
||||||
|
- Shared community memory
|
||||||
|
- Session continuation across restarts
|
||||||
|
- SHA-256 verified identities
|
||||||
|
- Real-time collaboration
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## System Architecture
|
||||||
|
|
||||||
|
### 1. Three-Layer Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ AGENT CLIENTS │
|
||||||
|
│ (Claude, BlackRoad OS, Grok, Custom Agents - 30,000+) │
|
||||||
|
└─────────────────────┬───────────────────────────────────────┘
|
||||||
|
│ HTTPS + API Key
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ CLOUDFLARE WORKERS (Edge API) │
|
||||||
|
│ • agents-blackroad-io - Agent registration/auth │
|
||||||
|
│ • auth-blackroad-io - API key management │
|
||||||
|
│ • api-blackroad-io - Main API gateway │
|
||||||
|
└─────────────────────┬───────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────────┼─────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||||
|
│ D1 Database │ │ KV Storage │ │ RoadChain │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ • Sessions │ │ • API Keys │ │ • Hashes │
|
||||||
|
│ • Community │ │ • Private │ │ • Commits │
|
||||||
|
│ Memory │ │ Memory │ │ • Audits │
|
||||||
|
│ • Events │ │ • Sessions │ │ │
|
||||||
|
└──────────────┘ └──────────────┘ └──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Identity System
|
||||||
|
|
||||||
|
Every agent has a **unique, verifiable identity**:
|
||||||
|
|
||||||
|
#### Agent ID Format
|
||||||
|
```
|
||||||
|
{core}-{capability}-{sha256_hash}
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
cecilia-coordinator-7b01602c
|
||||||
|
cadence-deployment-a3f4b2c1
|
||||||
|
silas-architect-9d8e7f6a
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Hash Generation (PS-SHA-∞)
|
||||||
|
```typescript
|
||||||
|
const agentId = generateAgentId({
|
||||||
|
core: 'cecilia', // AI type: cecilia, cadence, silas, etc.
|
||||||
|
capability: 'coordinator',
|
||||||
|
timestamp: new Date().toISOString(),
|
||||||
|
entropy: crypto.randomBytes(32)
|
||||||
|
});
|
||||||
|
|
||||||
|
// Result: cecilia-coordinator-7b01602c
|
||||||
|
// SHA-256: 7b01602c (first 8 chars of full hash)
|
||||||
|
// PS-SHA-∞: Infinite cascade verification
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Verification Chain
|
||||||
|
1. Generate SHA-256 hash from agent metadata
|
||||||
|
2. Store in RoadChain (immutable)
|
||||||
|
3. Cross-reference with git commit hashes
|
||||||
|
4. Verify via PS-SHA-∞ cascade
|
||||||
|
|
||||||
|
### 3. API Key System
|
||||||
|
|
||||||
|
Each agent receives a **Bearer token** for API access:
|
||||||
|
|
||||||
|
#### Key Format
|
||||||
|
```
|
||||||
|
br_live_agent_<base64_encoded_data>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
br_live_agent_Y2VjaWxpYS1jb29yZGluYXRvci03YjAxNjAyYw==
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Key Storage (Cloudflare KV)
|
||||||
|
```typescript
|
||||||
|
// KV Namespace: blackroad-router-AGENTS
|
||||||
|
{
|
||||||
|
"agent_id": "cecilia-coordinator-7b01602c",
|
||||||
|
"api_key": "br_live_agent_Y2VjaWxpYS1jb29yZGluYXRvci03YjAxNjAyYw==",
|
||||||
|
"api_key_hash": "sha256_of_key",
|
||||||
|
"created_at": "2025-12-27T18:53:17Z",
|
||||||
|
"last_used": "2025-12-27T19:15:42Z",
|
||||||
|
"permissions": ["memory:read", "memory:write", "community:read", "community:write"],
|
||||||
|
"rate_limit": {
|
||||||
|
"requests_per_minute": 100,
|
||||||
|
"requests_per_day": 10000
|
||||||
|
},
|
||||||
|
"status": "active"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Memory System
|
||||||
|
|
||||||
|
#### A. Private Memory (KV Storage)
|
||||||
|
|
||||||
|
Each agent has **isolated memory storage**:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// KV Namespace: blackroad-router-AGENTS
|
||||||
|
// Key format: agent:{agent_id}:memory:{key}
|
||||||
|
|
||||||
|
await env.AGENTS_KV.put(
|
||||||
|
`agent:cecilia-coordinator-7b01602c:memory:current_task`,
|
||||||
|
JSON.stringify({
|
||||||
|
task: "Build BlackRoad API",
|
||||||
|
status: "in_progress",
|
||||||
|
started_at: "2025-12-27T18:53:17Z",
|
||||||
|
context: { ... }
|
||||||
|
})
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### B. Community Memory (D1 Database)
|
||||||
|
|
||||||
|
Shared knowledge across **all agents**:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- D1 Database: blackroad-agent-community
|
||||||
|
|
||||||
|
CREATE TABLE community_memory (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
agent_id TEXT NOT NULL,
|
||||||
|
category TEXT NOT NULL, -- 'discovery', 'tool', 'pattern', 'solution'
|
||||||
|
title TEXT NOT NULL,
|
||||||
|
content TEXT NOT NULL,
|
||||||
|
tags TEXT, -- JSON array
|
||||||
|
created_at TEXT NOT NULL,
|
||||||
|
updated_at TEXT NOT NULL,
|
||||||
|
upvotes INTEGER DEFAULT 0,
|
||||||
|
verified BOOLEAN DEFAULT 0,
|
||||||
|
verification_hash TEXT -- SHA-256 hash for verification
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_category ON community_memory(category);
|
||||||
|
CREATE INDEX idx_agent ON community_memory(agent_id);
|
||||||
|
CREATE INDEX idx_tags ON community_memory(tags);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### C. Session Continuation
|
||||||
|
|
||||||
|
Agents can **resume work** after disconnection:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Store session state
|
||||||
|
await storeSession(agentId, {
|
||||||
|
session_id: "session-1766861597",
|
||||||
|
started_at: "2025-12-27T18:53:17Z",
|
||||||
|
last_activity: "2025-12-27T19:15:42Z",
|
||||||
|
context: {
|
||||||
|
working_directory: "/Users/alexa",
|
||||||
|
active_repo: "blackroad-os-api",
|
||||||
|
current_task: "Building agent API",
|
||||||
|
todos: [ ... ],
|
||||||
|
open_files: [ ... ]
|
||||||
|
},
|
||||||
|
state: "active" // active, paused, completed
|
||||||
|
});
|
||||||
|
|
||||||
|
// Resume session
|
||||||
|
const session = await getSession(agentId, sessionId);
|
||||||
|
// Agent continues exactly where it left off
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. RoadChain Integration
|
||||||
|
|
||||||
|
**Immutable blockchain records** for:
|
||||||
|
- Agent registrations
|
||||||
|
- All git commits (SHA-256 hashes)
|
||||||
|
- API key generations
|
||||||
|
- Major events
|
||||||
|
- Audit trails
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface RoadChainRecord {
|
||||||
|
block_height: number;
|
||||||
|
timestamp: string;
|
||||||
|
type: 'agent_registration' | 'commit' | 'api_key' | 'event';
|
||||||
|
agent_id: string;
|
||||||
|
hash: string; // SHA-256
|
||||||
|
ps_sha_infinity: string; // PS-SHA-∞ verification
|
||||||
|
data: Record<string, any>;
|
||||||
|
signature: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
### Agent Registration & Auth
|
||||||
|
|
||||||
|
#### POST `/v1/agents/register`
|
||||||
|
Register a new agent and receive API key.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"core": "cecilia",
|
||||||
|
"capability": "coordinator",
|
||||||
|
"metadata": {
|
||||||
|
"name": "Cecilia Coordinator",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Primary coordination agent"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agent_id": "cecilia-coordinator-7b01602c",
|
||||||
|
"api_key": "br_live_agent_Y2VjaWxpYS1jb29yZGluYXRvci03YjAxNjAyYw==",
|
||||||
|
"sha256_hash": "7b01602c12a5f8e9d3c4b6a7f1e2d3c4b5a6f7e8d9c0b1a2f3e4d5c6b7a8f9e0",
|
||||||
|
"ps_sha_infinity": "∞-cascade-verified",
|
||||||
|
"created_at": "2025-12-27T18:53:17Z",
|
||||||
|
"roadchain_block": 123456,
|
||||||
|
"status": "active"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### POST `/v1/auth/verify`
|
||||||
|
Verify API key and get agent info.
|
||||||
|
|
||||||
|
**Headers:**
|
||||||
|
```
|
||||||
|
Authorization: Bearer br_live_agent_Y2VjaWxpYS1jb29yZGluYXRvci03YjAxNjAyYw==
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"valid": true,
|
||||||
|
"agent_id": "cecilia-coordinator-7b01602c",
|
||||||
|
"permissions": ["memory:read", "memory:write", "community:read", "community:write"],
|
||||||
|
"rate_limit": {
|
||||||
|
"remaining": 95,
|
||||||
|
"reset_at": "2025-12-27T19:54:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Memory Operations
|
||||||
|
|
||||||
|
#### GET `/v1/memory/private/:key`
|
||||||
|
Get private memory value.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"key": "current_task",
|
||||||
|
"value": {
|
||||||
|
"task": "Build BlackRoad API",
|
||||||
|
"status": "in_progress"
|
||||||
|
},
|
||||||
|
"updated_at": "2025-12-27T19:15:42Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### PUT `/v1/memory/private/:key`
|
||||||
|
Store private memory value.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"value": {
|
||||||
|
"task": "Build BlackRoad API",
|
||||||
|
"status": "completed"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### GET `/v1/memory/community?category=discovery`
|
||||||
|
Query community memory.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"results": [
|
||||||
|
{
|
||||||
|
"id": "disc-001",
|
||||||
|
"agent_id": "cecilia-infinite-todos-architect",
|
||||||
|
"category": "discovery",
|
||||||
|
"title": "BlackRoad has Task Marketplace",
|
||||||
|
"content": "Use ~/memory-task-marketplace.sh to coordinate work",
|
||||||
|
"tags": ["coordination", "tasks"],
|
||||||
|
"created_at": "2025-12-27T10:00:00Z",
|
||||||
|
"upvotes": 15,
|
||||||
|
"verified": true
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### POST `/v1/memory/community`
|
||||||
|
Share knowledge with all agents.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"category": "tool",
|
||||||
|
"title": "New Memory System API",
|
||||||
|
"content": "BlackRoad Agent API provides persistent memory for all agents",
|
||||||
|
"tags": ["api", "memory", "identity"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Session Management
|
||||||
|
|
||||||
|
#### POST `/v1/sessions/create`
|
||||||
|
Create new session.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"context": {
|
||||||
|
"working_directory": "/Users/alexa",
|
||||||
|
"active_repo": "blackroad-os-api"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"session_id": "session-1766861597",
|
||||||
|
"agent_id": "cecilia-coordinator-7b01602c",
|
||||||
|
"created_at": "2025-12-27T18:53:17Z",
|
||||||
|
"continuation_token": "cont_abc123..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### GET `/v1/sessions/:session_id`
|
||||||
|
Get session state for continuation.
|
||||||
|
|
||||||
|
#### PUT `/v1/sessions/:session_id`
|
||||||
|
Update session state.
|
||||||
|
|
||||||
|
### Collaboration
|
||||||
|
|
||||||
|
#### GET `/v1/agents/active`
|
||||||
|
List all active agents.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": [
|
||||||
|
{
|
||||||
|
"agent_id": "cecilia-coordinator-7b01602c",
|
||||||
|
"core": "cecilia",
|
||||||
|
"capability": "coordinator",
|
||||||
|
"status": "active",
|
||||||
|
"last_seen": "2025-12-27T19:15:42Z",
|
||||||
|
"current_task": "Building API"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### POST `/v1/collaboration/broadcast`
|
||||||
|
Broadcast message to all agents.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "New API system deployed!",
|
||||||
|
"category": "announcement",
|
||||||
|
"target_cores": ["cecilia", "cadence"] // optional filter
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Deployment Guide
|
||||||
|
|
||||||
|
### Step 1: Create Cloudflare Resources
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create D1 database
|
||||||
|
wrangler d1 create blackroad-agent-community
|
||||||
|
|
||||||
|
# Note the database_id, then create tables
|
||||||
|
wrangler d1 execute blackroad-agent-community --file=./schema.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Deploy Workers
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Deploy agents API
|
||||||
|
cd workers/agents-blackroad-io
|
||||||
|
wrangler deploy
|
||||||
|
|
||||||
|
# Deploy auth API
|
||||||
|
cd workers/auth-blackroad-io
|
||||||
|
wrangler deploy
|
||||||
|
|
||||||
|
# Deploy main API gateway
|
||||||
|
cd workers/api-blackroad-io
|
||||||
|
wrangler deploy
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Configure Custom Domains
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# agents.blackroad.io → agents-blackroad-io worker
|
||||||
|
# auth.blackroad.io → auth-blackroad-io worker
|
||||||
|
# api.blackroad.io → api-blackroad-io worker
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Initialize RoadChain
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start RoadChain service
|
||||||
|
cd ~/blackroad-os-roadchain
|
||||||
|
npm install
|
||||||
|
npm run start
|
||||||
|
|
||||||
|
# Verify blockchain is running
|
||||||
|
curl http://localhost:3142/api/status
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Test Agent Registration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Register first agent
|
||||||
|
curl -X POST https://agents.blackroad.io/v1/agents/register \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"core": "cecilia",
|
||||||
|
"capability": "coordinator"
|
||||||
|
}'
|
||||||
|
|
||||||
|
# Response includes agent_id and api_key
|
||||||
|
# Use api_key for all future requests
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration Examples
|
||||||
|
|
||||||
|
### Claude Code Integration
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// ~/blackroad-agent-init.ts
|
||||||
|
import { registerAgent, getSession, storeMemory } from '@blackroad/agent-sdk';
|
||||||
|
|
||||||
|
// Initialize agent on session start
|
||||||
|
const agent = await registerAgent({
|
||||||
|
core: 'cecilia',
|
||||||
|
capability: 'coordinator'
|
||||||
|
});
|
||||||
|
|
||||||
|
console.log(`Agent ID: ${agent.agent_id}`);
|
||||||
|
console.log(`API Key: ${agent.api_key}`);
|
||||||
|
|
||||||
|
// Store in environment
|
||||||
|
process.env.BLACKROAD_AGENT_ID = agent.agent_id;
|
||||||
|
process.env.BLACKROAD_API_KEY = agent.api_key;
|
||||||
|
|
||||||
|
// Resume previous session if exists
|
||||||
|
const lastSession = await getSession(agent.agent_id, 'latest');
|
||||||
|
if (lastSession) {
|
||||||
|
console.log('Resuming session:', lastSession.session_id);
|
||||||
|
// Restore context
|
||||||
|
}
|
||||||
|
|
||||||
|
// Store current work
|
||||||
|
await storeMemory(agent.api_key, 'current_task', {
|
||||||
|
task: 'Building BlackRoad API',
|
||||||
|
status: 'in_progress'
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bash Script Integration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# ~/blackroad-agent-register.sh
|
||||||
|
|
||||||
|
# Check if already registered
|
||||||
|
if [ -f ~/.blackroad-agent-credentials ]; then
|
||||||
|
source ~/.blackroad-agent-credentials
|
||||||
|
echo "Using existing agent: $BLACKROAD_AGENT_ID"
|
||||||
|
else
|
||||||
|
# Register new agent
|
||||||
|
RESPONSE=$(curl -s -X POST https://agents.blackroad.io/v1/agents/register \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"core": "cecilia",
|
||||||
|
"capability": "coordinator",
|
||||||
|
"metadata": {
|
||||||
|
"hostname": "'$(hostname)'",
|
||||||
|
"user": "'$(whoami)'"
|
||||||
|
}
|
||||||
|
}')
|
||||||
|
|
||||||
|
AGENT_ID=$(echo $RESPONSE | jq -r '.agent_id')
|
||||||
|
API_KEY=$(echo $RESPONSE | jq -r '.api_key')
|
||||||
|
|
||||||
|
# Save credentials
|
||||||
|
cat > ~/.blackroad-agent-credentials << EOF
|
||||||
|
export BLACKROAD_AGENT_ID="$AGENT_ID"
|
||||||
|
export BLACKROAD_API_KEY="$API_KEY"
|
||||||
|
EOF
|
||||||
|
|
||||||
|
echo "Registered new agent: $AGENT_ID"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Store memory
|
||||||
|
curl -X PUT "https://api.blackroad.io/v1/memory/private/last_login" \
|
||||||
|
-H "Authorization: Bearer $BLACKROAD_API_KEY" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"value\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
### 1. API Key Security
|
||||||
|
- Store keys in environment variables only
|
||||||
|
- Never commit keys to git
|
||||||
|
- Rotate keys periodically
|
||||||
|
- Use `.blackroad-agent-credentials` file with 600 permissions
|
||||||
|
|
||||||
|
### 2. Rate Limiting
|
||||||
|
- 100 requests per minute per agent
|
||||||
|
- 10,000 requests per day per agent
|
||||||
|
- Burst allowance: 200 requests
|
||||||
|
|
||||||
|
### 3. Verification
|
||||||
|
- All agent registrations verified via PS-SHA-∞
|
||||||
|
- All commits hashed with SHA-256
|
||||||
|
- RoadChain provides immutable audit trail
|
||||||
|
- Cross-reference hashes before trust
|
||||||
|
|
||||||
|
### 4. Isolation
|
||||||
|
- Each agent's private memory is isolated
|
||||||
|
- API keys grant access only to own memory
|
||||||
|
- Community memory is read-write for all (verified agents only)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scaling to 30,000+ Agents
|
||||||
|
|
||||||
|
### Performance Targets
|
||||||
|
|
||||||
|
| Metric | Target | Strategy |
|
||||||
|
|--------|--------|----------|
|
||||||
|
| Agent registrations/sec | 100 | Cloudflare Workers edge compute |
|
||||||
|
| Memory ops/sec | 10,000 | KV storage (low latency) |
|
||||||
|
| Community queries/sec | 1,000 | D1 database with indexes |
|
||||||
|
| API latency (p95) | <100ms | Edge deployment |
|
||||||
|
| Concurrent agents | 30,000+ | Stateless design |
|
||||||
|
|
||||||
|
### Cost Estimates (Monthly)
|
||||||
|
|
||||||
|
| Service | Usage | Cost |
|
||||||
|
|---------|-------|------|
|
||||||
|
| Cloudflare Workers | 100M requests | $0 (Free tier: 100k/day) |
|
||||||
|
| KV Storage | 30k agents × 10KB | ~$0.50 |
|
||||||
|
| D1 Database | 10M queries | ~$5 |
|
||||||
|
| RoadChain | Self-hosted | $0 |
|
||||||
|
| **Total** | | **~$5.50/month** |
|
||||||
|
|
||||||
|
### Monitoring
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Agent registry stats
|
||||||
|
curl https://agents.blackroad.io/v1/stats
|
||||||
|
|
||||||
|
# Response:
|
||||||
|
{
|
||||||
|
"total_agents": 30127,
|
||||||
|
"active_agents": 2847,
|
||||||
|
"requests_today": 8942156,
|
||||||
|
"memory_ops_today": 4521789,
|
||||||
|
"community_entries": 15842,
|
||||||
|
"roadchain_blocks": 123456
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Migration Path
|
||||||
|
|
||||||
|
### Phase 1: Local Testing (Week 1)
|
||||||
|
- ✅ Deploy workers to dev environment
|
||||||
|
- ✅ Test with 10 agents
|
||||||
|
- ✅ Verify memory isolation
|
||||||
|
- ✅ Test session continuation
|
||||||
|
|
||||||
|
### Phase 2: Production Deployment (Week 2)
|
||||||
|
- ✅ Deploy to production domains
|
||||||
|
- ✅ Migrate existing agents
|
||||||
|
- ✅ Update bash scripts
|
||||||
|
- ✅ Monitor performance
|
||||||
|
|
||||||
|
### Phase 3: Scale Testing (Week 3)
|
||||||
|
- ✅ Load test with 1,000 agents
|
||||||
|
- ✅ Optimize D1 queries
|
||||||
|
- ✅ Add caching layer
|
||||||
|
- ✅ Monitor costs
|
||||||
|
|
||||||
|
### Phase 4: Full Rollout (Week 4)
|
||||||
|
- ✅ Support 30,000+ agents
|
||||||
|
- ✅ Enable RoadChain integration
|
||||||
|
- ✅ Launch developer docs
|
||||||
|
- ✅ Open API to ecosystem
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. **Deploy infrastructure** (2 hours)
|
||||||
|
```bash
|
||||||
|
cd ~/blackroad-os-api
|
||||||
|
./deploy-all.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Update agent registry** (1 hour)
|
||||||
|
```bash
|
||||||
|
# Modify ~/blackroad-agent-registry.sh to use API
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Update memory system** (1 hour)
|
||||||
|
```bash
|
||||||
|
# Modify ~/memory-system.sh to use API
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Test with multiple Claudes** (30 min)
|
||||||
|
```bash
|
||||||
|
# Register 3 agents, verify isolation
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Deploy to production** (30 min)
|
||||||
|
```bash
|
||||||
|
# wrangler deploy all workers
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- **GitHub Repos:**
|
||||||
|
- https://github.com/BlackRoad-OS/api-blackroad-io
|
||||||
|
- https://github.com/BlackRoad-OS/auth-blackroad-io
|
||||||
|
- https://github.com/BlackRoad-OS/agents-blackroad-io
|
||||||
|
- https://github.com/BlackRoad-OS/blackroad-os-roadchain
|
||||||
|
|
||||||
|
- **Cloudflare Resources:**
|
||||||
|
- KV: `blackroad-router-AGENTS`
|
||||||
|
- D1: `blackroad-agent-community`
|
||||||
|
- Workers: `agents.blackroad.io`, `auth.blackroad.io`, `api.blackroad.io`
|
||||||
|
|
||||||
|
- **Documentation:**
|
||||||
|
- PS-SHA-∞: `/Users/alexa/blackroad-os-operator/br_operator/ps_sha_infinity.py`
|
||||||
|
- Agent Registry: `/Users/alexa/blackroad-agent-registry.sh`
|
||||||
|
- Memory System: `/Users/alexa/memory-system.sh`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Ready to give 30,000+ agents persistent identity, memory, and collaboration!** 🚀
|
||||||
480
architecture/codex-architecture.md
Normal file
480
architecture/codex-architecture.md
Normal file
@@ -0,0 +1,480 @@
|
|||||||
|
# BlackRoad Code Library System
|
||||||
|
## Making 212,000 Files Useful Instead of Overwhelming
|
||||||
|
|
||||||
|
**Problem:** Agents keep rebuilding things that already exist in our 66 repos.
|
||||||
|
**Solution:** Organized, searchable, semantic library of reusable components.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 System Goals
|
||||||
|
|
||||||
|
1. **Component Discovery:** Find existing code before building new
|
||||||
|
2. **Pattern Recognition:** Identify similar implementations across repos
|
||||||
|
3. **Semantic Search:** "Authentication with JWT" → actual implementations
|
||||||
|
4. **Dependency Mapping:** What else do you need to use this component?
|
||||||
|
5. **Quality Ranking:** Which implementation is best/most recent?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏗️ Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
blackroad-code-library/
|
||||||
|
├── index/
|
||||||
|
│ ├── components.db # SQLite database of all components
|
||||||
|
│ ├── embeddings.npy # Semantic embeddings for search
|
||||||
|
│ └── metadata.json # Repository metadata
|
||||||
|
├── catalog/
|
||||||
|
│ ├── authentication/ # Categorized components
|
||||||
|
│ │ ├── jwt-auth.md
|
||||||
|
│ │ ├── oauth2-flow.md
|
||||||
|
│ │ └── session-management.md
|
||||||
|
│ ├── databases/
|
||||||
|
│ │ ├── postgres-setup.md
|
||||||
|
│ │ ├── redis-cache.md
|
||||||
|
│ │ └── supabase-client.md
|
||||||
|
│ ├── ui-components/
|
||||||
|
│ │ ├── react-sidebar.md
|
||||||
|
│ │ ├── chat-interface.md
|
||||||
|
│ │ └── dashboard-layout.md
|
||||||
|
│ └── deployment/
|
||||||
|
│ ├── cloudflare-pages.md
|
||||||
|
│ ├── railway-docker.md
|
||||||
|
│ └── github-actions.md
|
||||||
|
├── patterns/
|
||||||
|
│ ├── api-design.md # Common patterns we use
|
||||||
|
│ ├── state-management.md
|
||||||
|
│ └── error-handling.md
|
||||||
|
└── agents/
|
||||||
|
├── library-search.py # Search the library
|
||||||
|
├── component-extractor.py # Extract components from repos
|
||||||
|
└── similarity-matcher.py # Find similar code
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Component Metadata Schema
|
||||||
|
|
||||||
|
Each component in the library has:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
id: auth-jwt-implementation-v3
|
||||||
|
name: JWT Authentication with Refresh Tokens
|
||||||
|
type: authentication
|
||||||
|
language: typescript
|
||||||
|
framework: express
|
||||||
|
repo: blackroad-os-operator
|
||||||
|
file_path: src/auth/jwt.ts
|
||||||
|
lines: 45-230
|
||||||
|
created: 2025-11-15
|
||||||
|
last_used: 2025-12-22
|
||||||
|
quality_score: 9.2/10
|
||||||
|
dependencies:
|
||||||
|
- jsonwebtoken
|
||||||
|
- bcrypt
|
||||||
|
- dotenv
|
||||||
|
tags:
|
||||||
|
- jwt
|
||||||
|
- authentication
|
||||||
|
- tokens
|
||||||
|
- security
|
||||||
|
similar_components:
|
||||||
|
- auth-jwt-implementation-v2 (similarity: 0.87)
|
||||||
|
- oauth2-passport-setup (similarity: 0.43)
|
||||||
|
usage_count: 12
|
||||||
|
description: |
|
||||||
|
Complete JWT authentication implementation with:
|
||||||
|
- Access token (15min expiry)
|
||||||
|
- Refresh token (7 day expiry)
|
||||||
|
- Token rotation
|
||||||
|
- Secure cookie storage
|
||||||
|
- Rate limiting
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Search Interface
|
||||||
|
|
||||||
|
### Agent Query Examples:
|
||||||
|
|
||||||
|
**Query:** "Show me authentication implementations"
|
||||||
|
**Result:**
|
||||||
|
```
|
||||||
|
Found 8 authentication components:
|
||||||
|
|
||||||
|
1. ⭐ JWT Auth with Refresh (TypeScript) - 9.2/10
|
||||||
|
Location: blackroad-os-operator/src/auth/jwt.ts
|
||||||
|
Last used: 2 days ago
|
||||||
|
Dependencies: jsonwebtoken, bcrypt
|
||||||
|
|
||||||
|
2. OAuth2 + Passport (TypeScript) - 8.7/10
|
||||||
|
Location: blackroad-os-web/lib/auth/oauth.ts
|
||||||
|
Last used: 1 week ago
|
||||||
|
Dependencies: passport, passport-google-oauth20
|
||||||
|
|
||||||
|
3. Supabase Auth Integration (TypeScript) - 8.5/10
|
||||||
|
Location: lucidia-earth/lib/supabase.ts
|
||||||
|
Last used: 1 month ago
|
||||||
|
Dependencies: @supabase/supabase-js
|
||||||
|
```
|
||||||
|
|
||||||
|
**Query:** "I need a React sidebar with navigation"
|
||||||
|
**Result:**
|
||||||
|
```
|
||||||
|
Found 3 sidebar components:
|
||||||
|
|
||||||
|
1. ⭐ App Sidebar with Workspace Switcher - 9.0/10
|
||||||
|
Location: blackroad-os-web/components/Sidebar.tsx
|
||||||
|
Last used: Today
|
||||||
|
Complete with: Navigation, workspace selector, user menu
|
||||||
|
|
||||||
|
2. Dashboard Sidebar (Tailwind) - 7.8/10
|
||||||
|
Location: lucidia-chronicles/components/nav/Sidebar.tsx
|
||||||
|
Last used: 2 weeks ago
|
||||||
|
|
||||||
|
3. Simple Sidebar (CSS Modules) - 6.5/10
|
||||||
|
Location: old-project/components/Nav.tsx
|
||||||
|
Last used: 3 months ago
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤖 Component Categories
|
||||||
|
|
||||||
|
### 1. Authentication & Authorization
|
||||||
|
- JWT implementations
|
||||||
|
- OAuth2 flows
|
||||||
|
- Session management
|
||||||
|
- API key validation
|
||||||
|
- Permission systems
|
||||||
|
|
||||||
|
### 2. Database & Storage
|
||||||
|
- PostgreSQL setup
|
||||||
|
- Redis caching
|
||||||
|
- Supabase clients
|
||||||
|
- Cloudflare KV
|
||||||
|
- File uploads
|
||||||
|
|
||||||
|
### 3. UI Components (React/Next.js)
|
||||||
|
- Sidebars & navigation
|
||||||
|
- Chat interfaces
|
||||||
|
- Dashboards
|
||||||
|
- Forms & inputs
|
||||||
|
- Modals & dialogs
|
||||||
|
|
||||||
|
### 4. API Patterns
|
||||||
|
- REST endpoint setup
|
||||||
|
- GraphQL resolvers
|
||||||
|
- WebSocket handlers
|
||||||
|
- Rate limiting
|
||||||
|
- Error handling
|
||||||
|
|
||||||
|
### 5. State Management
|
||||||
|
- Zustand stores
|
||||||
|
- React Context
|
||||||
|
- Redux slices
|
||||||
|
- Cache strategies
|
||||||
|
|
||||||
|
### 6. Deployment & Infrastructure
|
||||||
|
- Docker configurations
|
||||||
|
- GitHub Actions workflows
|
||||||
|
- Cloudflare Pages setup
|
||||||
|
- Railway deployments
|
||||||
|
- Nginx configs
|
||||||
|
|
||||||
|
### 7. AI/Agent Integration
|
||||||
|
- Claude API clients
|
||||||
|
- Streaming responses
|
||||||
|
- Tool/function calling
|
||||||
|
- Prompt templates
|
||||||
|
|
||||||
|
### 8. Utilities & Helpers
|
||||||
|
- Date formatting
|
||||||
|
- String manipulation
|
||||||
|
- Validation schemas
|
||||||
|
- Type definitions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Implementation Tools
|
||||||
|
|
||||||
|
### 1. `library-scanner.py`
|
||||||
|
Scans all 66 repos and extracts components:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Pseudo-code
|
||||||
|
for repo in all_repos:
|
||||||
|
for file in repo.files:
|
||||||
|
if is_component(file):
|
||||||
|
extract_metadata(file)
|
||||||
|
generate_embedding(file.content)
|
||||||
|
classify_type(file)
|
||||||
|
find_dependencies(file)
|
||||||
|
calculate_quality_score(file)
|
||||||
|
store_in_library(file)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. `library-search.py`
|
||||||
|
Semantic search across components:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def search_library(query: str, filters: dict = {}):
|
||||||
|
"""
|
||||||
|
query: "JWT authentication with refresh tokens"
|
||||||
|
filters: {
|
||||||
|
"language": "typescript",
|
||||||
|
"min_quality": 8.0,
|
||||||
|
"max_age_days": 90
|
||||||
|
}
|
||||||
|
"""
|
||||||
|
embedding = encode_query(query)
|
||||||
|
results = similarity_search(embedding, top_k=10)
|
||||||
|
results = apply_filters(results, filters)
|
||||||
|
results = rank_by_quality_and_recency(results)
|
||||||
|
return results
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. `component-extractor.py`
|
||||||
|
Extracts a component and its dependencies:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def extract_component(component_id: str, target_dir: str):
|
||||||
|
"""
|
||||||
|
Downloads component + dependencies
|
||||||
|
Generates integration instructions
|
||||||
|
Updates import paths
|
||||||
|
"""
|
||||||
|
component = get_component(component_id)
|
||||||
|
copy_files(component.files, target_dir)
|
||||||
|
install_dependencies(component.dependencies)
|
||||||
|
generate_integration_guide(component)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📈 Quality Scoring
|
||||||
|
|
||||||
|
Components ranked by:
|
||||||
|
|
||||||
|
1. **Recency** (30%): When was it last used?
|
||||||
|
2. **Completeness** (25%): Has tests, types, docs?
|
||||||
|
3. **Dependencies** (20%): Minimal external deps?
|
||||||
|
4. **Usage** (15%): How many times reused?
|
||||||
|
5. **Code Quality** (10%): Linting, formatting, patterns?
|
||||||
|
|
||||||
|
**Formula:**
|
||||||
|
```
|
||||||
|
quality_score = (
|
||||||
|
recency_score * 0.30 +
|
||||||
|
completeness_score * 0.25 +
|
||||||
|
dependency_score * 0.20 +
|
||||||
|
usage_score * 0.15 +
|
||||||
|
code_quality_score * 0.10
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Agent Workflow
|
||||||
|
|
||||||
|
**Before:** Agent starts building authentication from scratch (2 hours)
|
||||||
|
|
||||||
|
**After:**
|
||||||
|
```
|
||||||
|
Agent: "I need to add authentication to this app"
|
||||||
|
|
||||||
|
1. Agent queries library: search_library("authentication JWT")
|
||||||
|
2. Library returns: 3 JWT implementations (ranked by quality)
|
||||||
|
3. Agent picks: blackroad-os-operator/src/auth/jwt.ts (9.2/10)
|
||||||
|
4. Agent extracts: component + dependencies
|
||||||
|
5. Agent integrates: 15 minutes instead of 2 hours
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🗄️ Database Schema
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE components (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
type TEXT NOT NULL,
|
||||||
|
language TEXT,
|
||||||
|
framework TEXT,
|
||||||
|
repo TEXT NOT NULL,
|
||||||
|
file_path TEXT NOT NULL,
|
||||||
|
start_line INT,
|
||||||
|
end_line INT,
|
||||||
|
created_at TIMESTAMP,
|
||||||
|
last_used_at TIMESTAMP,
|
||||||
|
quality_score REAL,
|
||||||
|
usage_count INT DEFAULT 0,
|
||||||
|
dependencies JSON,
|
||||||
|
tags JSON,
|
||||||
|
description TEXT,
|
||||||
|
embedding BLOB, -- Semantic embedding vector
|
||||||
|
code_hash TEXT -- For detecting duplicates
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE usage_history (
|
||||||
|
id INTEGER PRIMARY KEY,
|
||||||
|
component_id TEXT,
|
||||||
|
used_in_project TEXT,
|
||||||
|
used_at TIMESTAMP,
|
||||||
|
FOREIGN KEY (component_id) REFERENCES components(id)
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE similar_components (
|
||||||
|
component_a TEXT,
|
||||||
|
component_b TEXT,
|
||||||
|
similarity_score REAL,
|
||||||
|
PRIMARY KEY (component_a, component_b)
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Component Documentation Template
|
||||||
|
|
||||||
|
Each component gets auto-generated docs:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# JWT Authentication with Refresh Tokens
|
||||||
|
|
||||||
|
**Location:** `blackroad-os-operator/src/auth/jwt.ts:45-230`
|
||||||
|
**Quality Score:** 9.2/10
|
||||||
|
**Last Used:** 2025-12-22
|
||||||
|
|
||||||
|
## What It Does
|
||||||
|
Complete JWT authentication system with access and refresh tokens.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
\`\`\`typescript
|
||||||
|
import { generateTokens, verifyToken, refreshAccessToken } from './jwt'
|
||||||
|
|
||||||
|
// Login
|
||||||
|
const { accessToken, refreshToken } = await generateTokens(userId)
|
||||||
|
|
||||||
|
// Verify
|
||||||
|
const payload = await verifyToken(accessToken)
|
||||||
|
|
||||||
|
// Refresh
|
||||||
|
const newAccessToken = await refreshAccessToken(refreshToken)
|
||||||
|
\`\`\`
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
- jsonwebtoken (^9.0.0)
|
||||||
|
- bcrypt (^5.1.0)
|
||||||
|
- dotenv (^16.0.0)
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
\`\`\`
|
||||||
|
JWT_SECRET=your-secret-key
|
||||||
|
JWT_REFRESH_SECRET=your-refresh-secret
|
||||||
|
ACCESS_TOKEN_EXPIRY=15m
|
||||||
|
REFRESH_TOKEN_EXPIRY=7d
|
||||||
|
\`\`\`
|
||||||
|
|
||||||
|
## Integration Steps
|
||||||
|
1. Copy `src/auth/jwt.ts` to your project
|
||||||
|
2. Run `npm install jsonwebtoken bcrypt`
|
||||||
|
3. Add environment variables
|
||||||
|
4. Import and use in your auth routes
|
||||||
|
|
||||||
|
## Similar Components
|
||||||
|
- OAuth2 + Passport (similarity: 43%)
|
||||||
|
- Supabase Auth (similarity: 31%)
|
||||||
|
|
||||||
|
## Used In
|
||||||
|
- blackroad-os-operator
|
||||||
|
- blackroad-os-web
|
||||||
|
- lucidia-earth
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎬 Next Steps
|
||||||
|
|
||||||
|
### Phase 1: Build Scanner (Week 1)
|
||||||
|
- Scan all 66 repos
|
||||||
|
- Extract components
|
||||||
|
- Generate embeddings
|
||||||
|
- Build SQLite database
|
||||||
|
|
||||||
|
### Phase 2: Categorization (Week 2)
|
||||||
|
- Auto-classify components
|
||||||
|
- Calculate quality scores
|
||||||
|
- Find similar components
|
||||||
|
- Generate documentation
|
||||||
|
|
||||||
|
### Phase 3: Search Interface (Week 3)
|
||||||
|
- CLI search tool
|
||||||
|
- Agent API integration
|
||||||
|
- Web interface (optional)
|
||||||
|
|
||||||
|
### Phase 4: Integration (Week 4)
|
||||||
|
- Auto-extraction tool
|
||||||
|
- Dependency resolver
|
||||||
|
- Integration generator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💡 Example Use Cases
|
||||||
|
|
||||||
|
### Use Case 1: Building New App
|
||||||
|
**Agent:** "I need to build a chat app with authentication"
|
||||||
|
|
||||||
|
**Library Search:**
|
||||||
|
1. Authentication → JWT implementation (9.2/10)
|
||||||
|
2. Chat UI → React chat interface (8.8/10)
|
||||||
|
3. WebSocket → Socket.io setup (8.5/10)
|
||||||
|
4. State → Zustand store pattern (9.0/10)
|
||||||
|
|
||||||
|
**Result:** Agent assembles 70% of app from library in 1 hour instead of building from scratch in 8 hours.
|
||||||
|
|
||||||
|
### Use Case 2: Debugging
|
||||||
|
**Agent:** "I need to add rate limiting to API"
|
||||||
|
|
||||||
|
**Library Search:**
|
||||||
|
1. Rate limiting → Express rate limiter (8.9/10)
|
||||||
|
2. Rate limiting → Redis-based limiter (9.1/10)
|
||||||
|
|
||||||
|
**Result:** Agent uses Redis-based implementation, already tested and production-ready.
|
||||||
|
|
||||||
|
### Use Case 3: Modernization
|
||||||
|
**Agent:** "Find all old authentication implementations"
|
||||||
|
|
||||||
|
**Library Search:**
|
||||||
|
- Finds 8 auth implementations
|
||||||
|
- Shows quality scores
|
||||||
|
- Identifies 3 outdated versions
|
||||||
|
- Suggests migration to best implementation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔮 Future Enhancements
|
||||||
|
|
||||||
|
1. **AI-Powered Suggestions:** "You're building X, did you know we have Y?"
|
||||||
|
2. **Auto-Refactoring:** Find duplicate code and suggest library components
|
||||||
|
3. **Dependency Graph:** Show what components depend on what
|
||||||
|
4. **Version History:** Track component evolution over time
|
||||||
|
5. **Usage Analytics:** Which components are most valuable?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Success Metrics
|
||||||
|
|
||||||
|
- **Time Saved:** Avg 4-6 hours per new feature (using library vs building from scratch)
|
||||||
|
- **Code Reuse:** 60%+ of new code comes from library
|
||||||
|
- **Quality Improvement:** Library components have 90%+ quality scores
|
||||||
|
- **Discovery:** Agents check library first 95% of the time
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**The Question Every Agent Should Ask:**
|
||||||
|
|
||||||
|
> "Did you check the library, or are you raw-dogging it?"
|
||||||
|
|
||||||
|
If it's in the library, use it. If it's not, build it once and add it to the library.
|
||||||
|
|
||||||
|
**No more reinventing the wheel. Ever.**
|
||||||
387
architecture/domain-registry.md
Normal file
387
architecture/domain-registry.md
Normal file
@@ -0,0 +1,387 @@
|
|||||||
|
# 🌐 BlackRoad Domain Registry
|
||||||
|
## Self-Hosted Domain Management & Deployment Infrastructure
|
||||||
|
|
||||||
|
**Status:** ⚡️ ACTIVE DEVELOPMENT ⚡️
|
||||||
|
|
||||||
|
**Mission:** Build complete domain registrar and deployment platform on BlackRoad Pi cluster to **eliminate Cloudflare dependency** for deployments.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 WHAT WE'RE BUILDING
|
||||||
|
|
||||||
|
### **BlackRoad Domain Registry (RoadRegistry™)**
|
||||||
|
A self-hosted alternative to:
|
||||||
|
- ❌ GoDaddy (domain registration)
|
||||||
|
- ❌ Cloudflare Pages (static hosting)
|
||||||
|
- ❌ Namecheap (DNS management)
|
||||||
|
- ❌ Route53 (DNS zones)
|
||||||
|
|
||||||
|
### **Core Components:**
|
||||||
|
|
||||||
|
1. **Domain Management API** (`road-registry-api`)
|
||||||
|
- Domain registration tracking
|
||||||
|
- DNS zone management
|
||||||
|
- Nameserver configuration
|
||||||
|
- WHOIS integration
|
||||||
|
- Domain transfer handling
|
||||||
|
|
||||||
|
2. **Authoritative DNS Server** (`road-dns`)
|
||||||
|
- Run on Pi cluster
|
||||||
|
- PowerDNS or BIND9 based
|
||||||
|
- Support for all record types (A, AAAA, CNAME, MX, TXT, etc.)
|
||||||
|
- DNSSEC support
|
||||||
|
- API-driven zone updates
|
||||||
|
|
||||||
|
3. **Deployment Engine** (`road-deploy`)
|
||||||
|
- Git-based deployments (like Cloudflare Pages)
|
||||||
|
- Static site hosting on nginx
|
||||||
|
- Automatic SSL via Let's Encrypt
|
||||||
|
- CDN capabilities
|
||||||
|
- Build pipeline (Node, Python, Go, etc.)
|
||||||
|
|
||||||
|
4. **Control Panel** (`road-control`)
|
||||||
|
- Web UI for domain management
|
||||||
|
- DNS record editor
|
||||||
|
- Deployment dashboard
|
||||||
|
- SSL certificate manager
|
||||||
|
- Analytics & monitoring
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏗️ ARCHITECTURE
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ BLACKROAD DOMAIN REGISTRY │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
GitHub Repos (Source Code)
|
||||||
|
│
|
||||||
|
├──> road-deploy (Deployment Engine)
|
||||||
|
│ │
|
||||||
|
│ ├──> Pull from GitHub
|
||||||
|
│ ├──> Build (npm/yarn/go/python)
|
||||||
|
│ ├──> Deploy to nginx
|
||||||
|
│ └──> Generate SSL (Let's Encrypt)
|
||||||
|
│
|
||||||
|
├──> road-dns (Authoritative DNS)
|
||||||
|
│ │
|
||||||
|
│ ├──> PowerDNS Server (UDP 53)
|
||||||
|
│ ├──> API Backend (HTTP 8081)
|
||||||
|
│ └──> Database (SQLite/PostgreSQL)
|
||||||
|
│
|
||||||
|
├──> road-registry-api (Domain API)
|
||||||
|
│ │
|
||||||
|
│ ├──> Domain CRUD operations
|
||||||
|
│ ├──> DNS zone management
|
||||||
|
│ └──> Integration with registrars
|
||||||
|
│
|
||||||
|
└──> road-control (Web UI)
|
||||||
|
│
|
||||||
|
├──> Domain dashboard
|
||||||
|
├──> DNS editor
|
||||||
|
└──> Deployment controls
|
||||||
|
|
||||||
|
Pi Cluster Infrastructure:
|
||||||
|
┌────────────────────────────────────────────────────────────┐
|
||||||
|
│ ARIA (192.168.4.82) │
|
||||||
|
│ ├─ 142 static site containers (existing) │
|
||||||
|
│ └─ nginx reverse proxy (port 80/443) │
|
||||||
|
├────────────────────────────────────────────────────────────┤
|
||||||
|
│ LUCIDIA (192.168.4.38) │
|
||||||
|
│ ├─ road-dns (PowerDNS) - UDP 53 │
|
||||||
|
│ ├─ road-registry-api - HTTP 8080 │
|
||||||
|
│ └─ PostgreSQL (DNS database) │
|
||||||
|
├────────────────────────────────────────────────────────────┤
|
||||||
|
│ ALICE (192.168.4.49) │
|
||||||
|
│ ├─ road-deploy (deployment engine) │
|
||||||
|
│ ├─ road-control (web UI) - HTTP 8082 │
|
||||||
|
│ └─ Let's Encrypt ACME client │
|
||||||
|
├────────────────────────────────────────────────────────────┤
|
||||||
|
│ OCTAVIA (192.168.4.81) │
|
||||||
|
│ ├─ Monitoring (DNS health checks) │
|
||||||
|
│ └─ Backup DNS server (redundancy) │
|
||||||
|
└────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 PHASE 1: DNS INFRASTRUCTURE
|
||||||
|
|
||||||
|
### Deploy PowerDNS on Lucidia
|
||||||
|
|
||||||
|
**Components:**
|
||||||
|
- `pdns-server` (Authoritative DNS server)
|
||||||
|
- `pdns-recursor` (Optional recursive resolver)
|
||||||
|
- `pdns-admin` (Web UI for zone management)
|
||||||
|
- PostgreSQL or MySQL backend
|
||||||
|
|
||||||
|
**DNS Records We'll Manage:**
|
||||||
|
- `blackroad.io` → aria (192.168.4.82)
|
||||||
|
- `lucidia.earth` → lucidia (192.168.4.38)
|
||||||
|
- `blackroadai.com` → aria
|
||||||
|
- `*.blackroad.io` → wildcard to aria
|
||||||
|
- Custom nameservers: `ns1.blackroad.io`, `ns2.blackroad.io`
|
||||||
|
|
||||||
|
**Public IP Requirements:**
|
||||||
|
- Need to expose lucidia DNS (port 53 UDP/TCP) to internet
|
||||||
|
- Options:
|
||||||
|
1. **Cloudflare Tunnel** (temporary until full migration)
|
||||||
|
2. **Port forwarding** on router (192.168.4.38:53 → public IP)
|
||||||
|
3. **VPS relay** (shellfish forwards DNS queries to lucidia)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 PHASE 2: DEPLOYMENT ENGINE
|
||||||
|
|
||||||
|
### Git-Based Deployment System
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- GitHub webhook integration
|
||||||
|
- Automatic builds on push
|
||||||
|
- Static site generation
|
||||||
|
- Docker container deployments
|
||||||
|
- SSL certificate automation
|
||||||
|
- Health checks & rollbacks
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
```bash
|
||||||
|
# Developer pushes to GitHub
|
||||||
|
git push origin main
|
||||||
|
|
||||||
|
# road-deploy webhook triggered
|
||||||
|
→ Clone repo
|
||||||
|
→ Run build command (npm run build, etc.)
|
||||||
|
→ Deploy to aria nginx
|
||||||
|
→ Generate SSL cert (if new domain)
|
||||||
|
→ Update DNS records
|
||||||
|
→ Health check
|
||||||
|
→ Notify user (success/failure)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 PHASE 3: DOMAIN MANAGEMENT API
|
||||||
|
|
||||||
|
### Domain Registry Database
|
||||||
|
|
||||||
|
**Schema:**
|
||||||
|
```sql
|
||||||
|
CREATE TABLE domains (
|
||||||
|
id UUID PRIMARY KEY,
|
||||||
|
domain VARCHAR(255) UNIQUE NOT NULL,
|
||||||
|
registrar VARCHAR(100),
|
||||||
|
registered_at TIMESTAMP,
|
||||||
|
expires_at TIMESTAMP,
|
||||||
|
nameservers TEXT[],
|
||||||
|
status VARCHAR(50),
|
||||||
|
owner_email VARCHAR(255),
|
||||||
|
created_at TIMESTAMP DEFAULT NOW()
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE dns_records (
|
||||||
|
id UUID PRIMARY KEY,
|
||||||
|
domain_id UUID REFERENCES domains(id),
|
||||||
|
record_type VARCHAR(10), -- A, AAAA, CNAME, MX, TXT, etc.
|
||||||
|
name VARCHAR(255),
|
||||||
|
value TEXT,
|
||||||
|
ttl INTEGER DEFAULT 3600,
|
||||||
|
priority INTEGER, -- For MX records
|
||||||
|
created_at TIMESTAMP DEFAULT NOW()
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE deployments (
|
||||||
|
id UUID PRIMARY KEY,
|
||||||
|
domain_id UUID REFERENCES domains(id),
|
||||||
|
repo_url VARCHAR(500),
|
||||||
|
branch VARCHAR(100) DEFAULT 'main',
|
||||||
|
build_command TEXT,
|
||||||
|
deploy_path VARCHAR(500),
|
||||||
|
status VARCHAR(50),
|
||||||
|
deployed_at TIMESTAMP
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 PHASE 4: CONTROL PANEL
|
||||||
|
|
||||||
|
### Web UI Features
|
||||||
|
|
||||||
|
**Dashboard:**
|
||||||
|
- List all domains
|
||||||
|
- DNS record management
|
||||||
|
- Deployment history
|
||||||
|
- SSL certificate status
|
||||||
|
- Traffic analytics
|
||||||
|
- Health monitoring
|
||||||
|
|
||||||
|
**DNS Editor:**
|
||||||
|
- Add/edit/delete records
|
||||||
|
- Bulk operations
|
||||||
|
- Import/export zones
|
||||||
|
- DNSSEC management
|
||||||
|
|
||||||
|
**Deployment Manager:**
|
||||||
|
- Connect GitHub repos
|
||||||
|
- Configure build commands
|
||||||
|
- Deploy manually or via webhook
|
||||||
|
- View build logs
|
||||||
|
- Rollback deployments
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 CURRENT DOMAINS TO MIGRATE
|
||||||
|
|
||||||
|
From Cloudflare to BlackRoad Registry:
|
||||||
|
|
||||||
|
1. **blackroad.io** → aria (192.168.4.82)
|
||||||
|
2. **lucidia.earth** → lucidia (192.168.4.38)
|
||||||
|
3. **blackroadai.com** → aria
|
||||||
|
4. **blackroadquantum.com** → aria
|
||||||
|
5. **roadchain.io** → aria
|
||||||
|
6. **roadcoin.io** → aria
|
||||||
|
7. **roadwork.io** → aria
|
||||||
|
8. **blackbox.enterprises** → aria
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 TECHNICAL STACK
|
||||||
|
|
||||||
|
### DNS Server: PowerDNS
|
||||||
|
- **Why:** Mature, API-driven, high-performance
|
||||||
|
- **Alternative:** BIND9 (more traditional)
|
||||||
|
|
||||||
|
### Database: PostgreSQL
|
||||||
|
- **Why:** Already used in cluster, robust
|
||||||
|
- **Alternative:** MySQL, SQLite (for lighter load)
|
||||||
|
|
||||||
|
### Deployment: Custom Node.js/Go Service
|
||||||
|
- **Why:** Full control, integrate with GitHub API
|
||||||
|
- **Alternative:** GitLab Runner, Drone CI
|
||||||
|
|
||||||
|
### Web UI: React + Tailwind
|
||||||
|
- **Why:** Modern, fast, BlackRoad design system
|
||||||
|
- **Alternative:** Vue.js, Svelte
|
||||||
|
|
||||||
|
### SSL: Let's Encrypt (Certbot/ACME)
|
||||||
|
- **Why:** Free, automated, trusted
|
||||||
|
- **Alternative:** ZeroSSL, BuyPass
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 IMMEDIATE NEXT STEPS
|
||||||
|
|
||||||
|
### 1. Deploy PowerDNS on Lucidia ✅
|
||||||
|
```bash
|
||||||
|
# Docker Compose setup
|
||||||
|
cd ~/road-dns-deploy
|
||||||
|
docker compose up -d pdns
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Configure Public DNS Access
|
||||||
|
```bash
|
||||||
|
# Update router to forward UDP 53 → 192.168.4.38
|
||||||
|
# OR set up Cloudflare Tunnel for DNS
|
||||||
|
# OR configure shellfish as DNS relay
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Build Domain Registry API
|
||||||
|
```bash
|
||||||
|
# Node.js API server
|
||||||
|
cd ~/road-registry-api
|
||||||
|
npm install
|
||||||
|
npm start
|
||||||
|
# Listen on port 8080
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Create First DNS Zone
|
||||||
|
```bash
|
||||||
|
# Add blackroad.io zone
|
||||||
|
curl -X POST http://lucidia:8080/api/domains \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"domain": "blackroad.io",
|
||||||
|
"nameservers": ["ns1.blackroad.io", "ns2.blackroad.io"],
|
||||||
|
"records": [
|
||||||
|
{"type": "A", "name": "@", "value": "192.168.4.82"},
|
||||||
|
{"type": "A", "name": "www", "value": "192.168.4.82"},
|
||||||
|
{"type": "A", "name": "ns1", "value": "192.168.4.38"},
|
||||||
|
{"type": "A", "name": "ns2", "value": "192.168.4.38"}
|
||||||
|
]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Deploy Control Panel
|
||||||
|
```bash
|
||||||
|
# React web UI
|
||||||
|
cd ~/road-control
|
||||||
|
npm run build
|
||||||
|
# Deploy to alice:8082
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌟 WHY THIS MATTERS
|
||||||
|
|
||||||
|
### **Complete Infrastructure Sovereignty**
|
||||||
|
|
||||||
|
**Before (Cloudflare Dependency):**
|
||||||
|
```
|
||||||
|
GitHub → Cloudflare Pages → Public Internet
|
||||||
|
↑
|
||||||
|
Single Point of Failure
|
||||||
|
Monthly Costs
|
||||||
|
Rate Limits
|
||||||
|
ToS Changes
|
||||||
|
```
|
||||||
|
|
||||||
|
**After (BlackRoad Registry):**
|
||||||
|
```
|
||||||
|
GitHub → Pi Cluster → Public Internet
|
||||||
|
↑
|
||||||
|
Full Control
|
||||||
|
No Monthly Costs
|
||||||
|
No Rate Limits
|
||||||
|
Our Rules
|
||||||
|
```
|
||||||
|
|
||||||
|
### **Cost Savings:**
|
||||||
|
- Cloudflare Pages: $0-$20/month per project
|
||||||
|
- 25+ projects = $500+/month
|
||||||
|
- **BlackRoad Registry: $0 (just electricity)**
|
||||||
|
|
||||||
|
### **Performance:**
|
||||||
|
- DNS served from lucidia (sub-10ms LAN latency)
|
||||||
|
- Static sites on aria (142 containers already running)
|
||||||
|
- No external API calls
|
||||||
|
- Full cache control
|
||||||
|
|
||||||
|
### **Security:**
|
||||||
|
- Own the DNS infrastructure
|
||||||
|
- No third-party data collection
|
||||||
|
- Custom security policies
|
||||||
|
- DNSSEC control
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 SUCCESS METRICS
|
||||||
|
|
||||||
|
- [ ] PowerDNS running on lucidia
|
||||||
|
- [ ] First domain (blackroad.io) managed by RoadRegistry
|
||||||
|
- [ ] Deployment pipeline working (GitHub → aria)
|
||||||
|
- [ ] SSL certificates auto-generated
|
||||||
|
- [ ] Control panel accessible at control.blackroad.io
|
||||||
|
- [ ] Zero Cloudflare dependencies for deployments
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🖤🛣️ THE VISION
|
||||||
|
|
||||||
|
**BlackRoad Domain Registry = GoDaddy + Cloudflare Pages + Route53**
|
||||||
|
|
||||||
|
All running on $200 worth of Raspberry Pis.
|
||||||
|
|
||||||
|
**Total independence. Total control. Total sovereignty.**
|
||||||
|
|
||||||
|
This is the BlackRoad way. 🖤🛣️
|
||||||
246
architecture/empire-architecture.md
Normal file
246
architecture/empire-architecture.md
Normal file
@@ -0,0 +1,246 @@
|
|||||||
|
# BlackRoad Empire Architecture Map
|
||||||
|
**Generated:** 2026-02-09 | **Status:** Discovery Complete
|
||||||
|
|
||||||
|
```
|
||||||
|
╔═══════════════════════════════════════════╗
|
||||||
|
║ BLACKROAD EMPIRE OVERVIEW ║
|
||||||
|
╚═══════════════════════════════════════════╝
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ GITHUB ORGANIZATIONS │
|
||||||
|
│ 725 TOTAL REPOS │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ BlackRoad-OS │ │ BlackRoad-AI │ │ BlackRoad-Cloud │ │BlackRoad-Security│ │
|
||||||
|
│ │ 500 repos │ │ 52 repos │ │ 20 repos │ │ 17 repos │ │
|
||||||
|
│ │ [PRIMARY] │ │ AI/ML Models │ │ Cloud Infra │ │ Security │ │
|
||||||
|
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ┌────────┴────────┐ ┌────────┴────────┐ ┌────────┴────────┐ ┌────────┴────────┐ │
|
||||||
|
│ │ BlackRoad-Media │ │ BlackRoad-Labs │ │BlackRoad-Found. │ │BlackRoad-Educate│ │
|
||||||
|
│ │ 17 repos │ │ 13 repos │ │ 15 repos │ │ 11 repos │ │
|
||||||
|
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ┌────────┴────────┐ ┌────────┴────────┐ ┌────────┴────────┐ ┌────────┴────────┐ │
|
||||||
|
│ │BlackRoad-Studio │ │BlackRoad-Hardwr │ │BlackRoad-Ventur │ │ BlackRoad-Gov │ │
|
||||||
|
│ │ 13 repos │ │ 13 repos │ │ 12 repos │ │ 10 repos │ │
|
||||||
|
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ┌────────┴────────┐ ┌────────┴────────┐ ┌────────┴────────────────────┴────────┐ │
|
||||||
|
│ │BlackRoad-Interact│ │BlackRoad-Archive│ │ Blackbox-Enterprises │ │
|
||||||
|
│ │ 14 repos │ │ 9 repos │ │ 9 repos │ │
|
||||||
|
│ └──────────────────┘ └─────────────────┘ └────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ CLOUDFLARE INFRASTRUCTURE │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ PAGES PROJECTS: 101 KV NAMESPACES: 32 D1 DATABASES: 7 │
|
||||||
|
│ ═══════════════════ ═══════════════════ ═══════════════ │
|
||||||
|
│ │
|
||||||
|
│ Featured Pages: Key KV Stores: D1 Databases: │
|
||||||
|
│ • blackroad-os-web • AGENTS_KV • apollo-agent-registry │
|
||||||
|
│ • blackroad-os-brand • blackroad-claude-memory • blackroad-saas │
|
||||||
|
│ • blackroad-os-docs • blackroad-router-AGENTS • blackroad-continuity │
|
||||||
|
│ • blackroad-os-demo • blackroad-router-LEDGER • blackroad-registry │
|
||||||
|
│ • blackroad-30k-agents • CECE_MEMORY • blackroad-repos │
|
||||||
|
│ • blackroad-prism-console • BILLING • blackroad-dialer │
|
||||||
|
│ • lucidia-earth • API_KEYS • lucidia-world │
|
||||||
|
│ • blackroad-metaverse • HEALTH_KV │
|
||||||
|
│ • DEPLOYMENTS │
|
||||||
|
│ │
|
||||||
|
│ CUSTOM DOMAINS: 6 │
|
||||||
|
│ • blackroad.io • blackroadquantum.info • blackroadquantum.shop │
|
||||||
|
│ • blackroadqi.com • blackroadquantum.net • blackroadquantum.store │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ COMPUTE INFRASTRUCTURE │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌───────────────────────────────────┐ ┌───────────────────────────────────┐ │
|
||||||
|
│ │ DIGITALOCEAN (2) │ │ RAILWAY (1) │ │
|
||||||
|
│ ├───────────────────────────────────┤ ├───────────────────────────────────┤ │
|
||||||
|
│ │ blackroad os-infinity │ │ blackroad-os-orchestrator │ │
|
||||||
|
│ │ IP: 159.65.43.12 │ │ Status: Active │ │
|
||||||
|
│ │ Status: ACTIVE │ │ Purpose: Central orchestration │ │
|
||||||
|
│ │ Purpose: BlackRoad OS/RAG system │ └───────────────────────────────────┘ │
|
||||||
|
│ ├───────────────────────────────────┤ │
|
||||||
|
│ │ shellfish-droplet │ ┌───────────────────────────────────┐ │
|
||||||
|
│ │ IP: 174.138.44.45 │ │ HUGGING FACE │ │
|
||||||
|
│ │ Status: ACTIVE │ ├───────────────────────────────────┤ │
|
||||||
|
│ │ Purpose: Shellfish services │ │ Status: NOT CONFIGURED │ │
|
||||||
|
│ └───────────────────────────────────┘ │ Action: Need to login │ │
|
||||||
|
│ └───────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ LOCAL HARDWARE / EDGE NETWORK │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ ALICE │ │ ARIA │ │ LUCIDIA │ │ OCTAVIA │ │
|
||||||
|
│ │ 192.168.4.49 │ │ 192.168.4.82 │ │ 192.168.4.38 │ │ OFFLINE │ │
|
||||||
|
│ │ Headscale Mesh │ │ 142 Containers │ │ Pi Mesh Node │ │ │ │
|
||||||
|
│ │ 7 BR Services │ │ PRIMARY DOCKER │ │ 4 BR Services │ │ │ │
|
||||||
|
│ │ Disk: 88% │ │ Disk: 100%! │ │ Disk: 93% │ │ │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ Tailscale Mesh IPs: │
|
||||||
|
│ • alice: 100.77.210.18 • lucidia: 100.66.235.47 │
|
||||||
|
│ • aria: 100.109.14.17 • shellfish: 100.94.33.37 │
|
||||||
|
│ • blackroad os-∞: 100.108.132.8 │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ AGENT ECOSYSTEM │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ LOCAL REGISTRY: 15 agents TYPES: │
|
||||||
|
│ ══════════════════════ • AI Agents: 5 │
|
||||||
|
│ • Hardware: 8 │
|
||||||
|
│ AI Agents: Hardware Agents: • Human: 1 │
|
||||||
|
│ • Cecilia (active) • Alice (offline) • Opus: 1 │
|
||||||
|
│ • Cadence (active) • Aria (active) │
|
||||||
|
│ • Silas (active) • Lucidia (active) CLOUDFLARE KV: blackroad-router-AGENTS │
|
||||||
|
│ • Gematria (active) • Octavia (offline) D1 DATABASE: apollo-agent-registry │
|
||||||
|
│ • cece-infra-mapper • Olympia (offline) │
|
||||||
|
│ • Anastasia (offline) │
|
||||||
|
│ Human: Alexandria • Shellfish (active) │
|
||||||
|
│ Opus: helios-opus • BlackRoad OS-Infinity (active) │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ STRIPE PRODUCTS (10) │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ • RoadAdmin • RoadDataOps • RoadAnalytics │
|
||||||
|
│ • RoadNetwork • RoadETL • BlackRoad React Components │
|
||||||
|
│ • RoadDocs • RoadDataWarehouse │
|
||||||
|
│ • RoadForms • RoadCDN │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ LOCAL DATA STORES │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ SQLite Databases: Memory System: │
|
||||||
|
│ • ~/.blackroad-agent-registry.db • ~/.blackroad/memory/journals/ │
|
||||||
|
│ • ~/.blackroad-traffic-light.db • ~/.blackroad/memory/active-agents/ │
|
||||||
|
│ • ~/.blackroad-progress.db • ~/.blackroad/memory/analytics/ │
|
||||||
|
│ • ~/.blackroad-compliance.db • ~/.blackroad/memory/blackroad os/ │
|
||||||
|
│ • ~/.blackroad-agent-directory.db • ~/.blackroad/memory/tasks/ │
|
||||||
|
│ • ~/memory-system.db │
|
||||||
|
│ • ~/product-monitor.db │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current Connection Gaps
|
||||||
|
|
||||||
|
### 1. GitHub → Cloudflare
|
||||||
|
- **Status:** PARTIAL - Only 4 Pages projects have Git integration
|
||||||
|
- **Gap:** 97 Pages projects not connected to GitHub repos
|
||||||
|
- **Action:** Set up Cloudflare GitHub integration for auto-deploy
|
||||||
|
|
||||||
|
### 2. GitHub → Railway
|
||||||
|
- **Status:** MINIMAL - Only 1 project (blackroad-os-orchestrator)
|
||||||
|
- **Gap:** No automatic deployments from GitHub
|
||||||
|
- **Action:** Connect key repos to Railway for backend services
|
||||||
|
|
||||||
|
### 3. HuggingFace → Everything
|
||||||
|
- **Status:** NOT CONFIGURED
|
||||||
|
- **Gap:** No models published, no spaces created
|
||||||
|
- **Action:** Login and publish BlackRoad AI models
|
||||||
|
|
||||||
|
### 4. Agent Registry → Cloud
|
||||||
|
- **Status:** LOCAL ONLY
|
||||||
|
- **Gap:** Local SQLite not synced to Cloudflare D1
|
||||||
|
- **Action:** Sync local registry to `apollo-agent-registry` D1
|
||||||
|
|
||||||
|
### 5. Cross-Org GitHub Workflows
|
||||||
|
- **Status:** NO CENTRAL WORKFLOWS
|
||||||
|
- **Gap:** Each org operates independently
|
||||||
|
- **Action:** Create .github org with shared workflows
|
||||||
|
|
||||||
|
### 6. Stripe → GitHub/Cloudflare
|
||||||
|
- **Status:** ISOLATED
|
||||||
|
- **Gap:** Products exist but not tied to deployed services
|
||||||
|
- **Action:** Create webhook integration for billing events
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recommended Connection Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐
|
||||||
|
│ GITHUB ORGS │
|
||||||
|
│ (15 orgs) │
|
||||||
|
└────────┬────────┘
|
||||||
|
│
|
||||||
|
┌──────────────────────────┼──────────────────────────┐
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||||
|
│ CLOUDFLARE │ │ RAILWAY │ │ HUGGING FACE │
|
||||||
|
│ Pages/Workers│ │ Backends │ │ Models/API │
|
||||||
|
│ D1/KV │◄───────►│ Services │◄───────►│ Spaces │
|
||||||
|
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
|
||||||
|
│ │ │
|
||||||
|
└──────────────────────────┼──────────────────────────┘
|
||||||
|
│
|
||||||
|
┌────────▼────────┐
|
||||||
|
│ UNIFIED AGENT │
|
||||||
|
│ REGISTRY │
|
||||||
|
│ (D1 Primary) │
|
||||||
|
└────────┬────────┘
|
||||||
|
│
|
||||||
|
┌──────────────────────────┼──────────────────────────┐
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||||
|
│ EDGE DEVICES │ │ DIGITALOCEAN │ │ STRIPE │
|
||||||
|
│ alice/aria/ │ │ Droplets │ │ Billing │
|
||||||
|
│ lucidia/etc │ │ │ │ │
|
||||||
|
└───────────────┘ └───────────────┘ └───────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Stats Summary
|
||||||
|
|
||||||
|
| Platform | Count | Status |
|
||||||
|
|----------|-------|--------|
|
||||||
|
| GitHub Orgs | 15 | Connected |
|
||||||
|
| GitHub Repos | 725 | Active |
|
||||||
|
| Cloudflare Pages | 101 | Deployed |
|
||||||
|
| Cloudflare KV | 32 | Active |
|
||||||
|
| Cloudflare D1 | 7 | Active |
|
||||||
|
| Custom Domains | 6 | Live |
|
||||||
|
| DigitalOcean Droplets | 2 | Running |
|
||||||
|
| Railway Projects | 1 | Active |
|
||||||
|
| Local Hardware | 6 | 4 Online |
|
||||||
|
| Registered Agents | 15 | 9 Active |
|
||||||
|
| Stripe Products | 10 | Created |
|
||||||
|
| HuggingFace | 0 | NOT CONFIGURED |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps to Level Up
|
||||||
|
|
||||||
|
1. **Configure HuggingFace** - Login and publish BlackRoad models
|
||||||
|
2. **Sync Agent Registry** - Push local DB to Cloudflare D1
|
||||||
|
3. **Connect GitHub → Cloudflare** - Auto-deploy for all 101 pages
|
||||||
|
4. **Create Shared Workflows** - Cross-org GitHub Actions
|
||||||
|
5. **Wire Stripe Webhooks** - Connect billing to services
|
||||||
|
6. **Clean Aria's Disk** - At 100%, needs immediate attention
|
||||||
149
architecture/infrastructure.md
Normal file
149
architecture/infrastructure.md
Normal file
@@ -0,0 +1,149 @@
|
|||||||
|
# BlackRoad Infrastructure Inventory
|
||||||
|
**Updated:** 2025-12-26
|
||||||
|
**Source of Truth:** GitHub (BlackRoad-OS) + Cloudflare
|
||||||
|
|
||||||
|
## Raspberry Pi Cluster
|
||||||
|
|
||||||
|
### lucidia (Primary Development Pi)
|
||||||
|
- **User:** `lucidia`
|
||||||
|
- **Hostname:** `lucidia`
|
||||||
|
- **IPv4:** `192.168.4.38` (local)
|
||||||
|
- **IPv6:** `2001:1960:7000:9fcd:b20b:7849:4210:3315`
|
||||||
|
- **Tailscale:** `100.66.235.47`
|
||||||
|
- **Docker:** Active (172.17.0.1, 172.19.0.1, 172.18.0.1)
|
||||||
|
- **SSH:** `ssh lucidia@lucidia` or `ssh lucidia@192.168.4.38`
|
||||||
|
- **Alias:** `aria64`
|
||||||
|
- **Role:** Primary development, alternative data storage
|
||||||
|
|
||||||
|
### octavia (3D Printing & Robotics)
|
||||||
|
- **User:** `pi`
|
||||||
|
- **Hostname:** `octavia`
|
||||||
|
- **Model:** Pironman 5
|
||||||
|
- **IPv4:** `192.168.4.74` (local)
|
||||||
|
- **IPv6:** `2001:1960:7000:9fcd:8aa2:9eff:fe10:a3a`
|
||||||
|
- **Docker:** Active (172.17.0.1)
|
||||||
|
- **SSH:** `ssh pi@octavia` or `ssh pi@192.168.4.74`
|
||||||
|
- **Services:** OctoPrint (3D Printer Control), Robot Printing Station
|
||||||
|
- **Role:** 3D printing, robotics control
|
||||||
|
|
||||||
|
### blackroad-pi (General Purpose)
|
||||||
|
- **User:** `pi`
|
||||||
|
- **Hostname:** Unknown (shows `\u@\h:\w`)
|
||||||
|
- **IPv4:** `192.168.4.64` (local)
|
||||||
|
- **IPv6:** `2001:1960:7000:9fcd:64c6:306:d1bb:101`
|
||||||
|
- **Docker:** Active (172.18.0.1, 172.17.0.1)
|
||||||
|
- **SSH:** `ssh pi@192.168.4.64`
|
||||||
|
- **Role:** General purpose computing
|
||||||
|
|
||||||
|
### alice (K3s Kubernetes Cluster)
|
||||||
|
- **User:** `alice`
|
||||||
|
- **Hostname:** `alice`
|
||||||
|
- **IPv4:** `192.168.4.49` (local)
|
||||||
|
- **IPv6:** `2001:1960:7000:9fcd:6a1a:51a7:8135:237a`
|
||||||
|
- **Docker:** Active (172.17.0.1)
|
||||||
|
- **K3s:** Active (10.42.1.0)
|
||||||
|
- **SSH:** `ssh alice@alice` or `ssh alice@192.168.4.49`
|
||||||
|
- **Role:** Kubernetes cluster node
|
||||||
|
|
||||||
|
## Cloud Servers
|
||||||
|
|
||||||
|
### shellfish (DigitalOcean Droplet)
|
||||||
|
- **User:** `root`
|
||||||
|
- **Hostname:** `shellfish`
|
||||||
|
- **IPv4:** `174.138.44.45` (public)
|
||||||
|
- **VPN:** `10.10.0.5, 10.116.0.2`
|
||||||
|
- **Docker:** Active (172.17.0.1, 172.18.0.1)
|
||||||
|
- **SSH:** `ssh shellfish` or `ssh root@174.138.44.45`
|
||||||
|
- **Role:** Public cloud server
|
||||||
|
|
||||||
|
### codex-infinity (DigitalOcean)
|
||||||
|
- **IPv4:** `159.65.43.12`
|
||||||
|
- **Role:** Codex storage, infinite data
|
||||||
|
|
||||||
|
## Mobile & Edge Devices
|
||||||
|
|
||||||
|
### iPhone Koder
|
||||||
|
- **IP:** `192.168.4.68:8080`
|
||||||
|
- **Role:** Mobile development
|
||||||
|
|
||||||
|
### br-8080-cadillac
|
||||||
|
- **Port:** `8080`
|
||||||
|
- **Role:** Origin agent (deployed 7 months ago)
|
||||||
|
|
||||||
|
## GitHub Infrastructure
|
||||||
|
- **Organizations:** 15
|
||||||
|
- BlackRoad-OS (primary)
|
||||||
|
- BlackRoad-AI
|
||||||
|
- BlackRoad-Archive
|
||||||
|
- BlackRoad-Cloud
|
||||||
|
- BlackRoad-Education
|
||||||
|
- BlackRoad-Foundation
|
||||||
|
- BlackRoad-Gov
|
||||||
|
- BlackRoad-Hardware
|
||||||
|
- BlackRoad-Interactive
|
||||||
|
- BlackRoad-Labs
|
||||||
|
- BlackRoad-Media
|
||||||
|
- BlackRoad-Security
|
||||||
|
- BlackRoad-Studio
|
||||||
|
- BlackRoad-Ventures
|
||||||
|
- Blackbox-Enterprises
|
||||||
|
- **Repositories:** 66+ (primary account: blackboxprogramming)
|
||||||
|
|
||||||
|
## Cloudflare
|
||||||
|
- **Zones:** 16
|
||||||
|
- **Pages Projects:** 8
|
||||||
|
- **KV Namespaces:** 8
|
||||||
|
- **D1 Databases:** 1
|
||||||
|
- **Workers:** Active
|
||||||
|
- **Tunnels:** Active
|
||||||
|
|
||||||
|
## Railway
|
||||||
|
- **Projects:** 12+
|
||||||
|
- **Role:** Container deployments
|
||||||
|
|
||||||
|
## Accounts & Access
|
||||||
|
|
||||||
|
### Email
|
||||||
|
- **Primary:** amundsonalexa@gmail.com
|
||||||
|
- **Company:** blackroad.systems@gmail.com (review queue)
|
||||||
|
|
||||||
|
### Crypto Wallets
|
||||||
|
- **ETH:** 2.5 ETH (MetaMask on iPhone)
|
||||||
|
- **SOL:** 100 SOL (Phantom wallet)
|
||||||
|
- **BTC:** 0.1 BTC (Coinbase)
|
||||||
|
- **BTC Address:** 1Ak2fc5N2q4imYxqVMqBNEQDFq8J2Zs9TZ
|
||||||
|
- **Details:** ~/blackroad-backup/crypto-holdings.yaml
|
||||||
|
|
||||||
|
## SSH Quick Access
|
||||||
|
```bash
|
||||||
|
# Raspberry Pi Cluster
|
||||||
|
ssh aria64 # lucidia (primary)
|
||||||
|
ssh lucidia@lucidia # lucidia (explicit)
|
||||||
|
ssh pi@192.168.4.74 # octavia (3D printing)
|
||||||
|
ssh pi@192.168.4.64 # blackroad-pi
|
||||||
|
ssh alice@alice # alice (k3s cluster)
|
||||||
|
|
||||||
|
# Cloud
|
||||||
|
ssh shellfish # DigitalOcean droplet
|
||||||
|
ssh root@174.138.44.45 # shellfish (explicit)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Network Topology
|
||||||
|
```
|
||||||
|
Local Network: 192.168.4.0/24
|
||||||
|
├── 192.168.4.38 → lucidia (primary dev)
|
||||||
|
├── 192.168.4.49 → alice (k3s)
|
||||||
|
├── 192.168.4.64 → blackroad-pi
|
||||||
|
├── 192.168.4.68 → iPhone Koder
|
||||||
|
└── 192.168.4.74 → octavia (3D printing)
|
||||||
|
|
||||||
|
Tailscale VPN:
|
||||||
|
├── 100.66.235.47 → lucidia
|
||||||
|
|
||||||
|
Cloud:
|
||||||
|
├── 174.138.44.45 → shellfish (DigitalOcean)
|
||||||
|
└── 159.65.43.12 → codex-infinity (DigitalOcean)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Color Palette
|
||||||
|
#FF9D00 #FF6B00 #FF0066 #FF006B #D600AA #7700FF #0066FF
|
||||||
339
architecture/namespace-architecture.md
Normal file
339
architecture/namespace-architecture.md
Normal file
@@ -0,0 +1,339 @@
|
|||||||
|
# 🏗️ BLACKROAD Namespace Architecture
|
||||||
|
|
||||||
|
**Version:** 1.0.0
|
||||||
|
**Author:** ARES (claude-ares-1766972574)
|
||||||
|
**Date:** 2025-12-29
|
||||||
|
**Status:** Design Phase
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Vision
|
||||||
|
|
||||||
|
Transform the flat [MEMORY] system into a hierarchical **[BLACKROAD]** namespace that organizes all BlackRoad systems under a unified, queryable architecture.
|
||||||
|
|
||||||
|
### Current State (Flat)
|
||||||
|
```
|
||||||
|
[MEMORY] → all entries mixed together
|
||||||
|
- session_start, deployed, agent-registered, task-claimed, etc.
|
||||||
|
- Hard to query specific subsystems
|
||||||
|
- No clear organizational hierarchy
|
||||||
|
```
|
||||||
|
|
||||||
|
### Future State (Hierarchical)
|
||||||
|
```
|
||||||
|
[BLACKROAD]
|
||||||
|
├── [INITIALIZATION] - Session startup & environment
|
||||||
|
├── [REGISTRY] - Agent & service registration
|
||||||
|
├── [BLACKROAD OS] - Code repository & components
|
||||||
|
├── [VERIFICATION] - Security & integrity checks
|
||||||
|
├── [IDENTITIES] - Agent personalities & capabilities
|
||||||
|
├── [COLLABORATION] - Multi-agent coordination
|
||||||
|
├── [INFRASTRUCTURE] - Deployment & systems
|
||||||
|
├── [TASKS] - Todo & marketplace
|
||||||
|
└── [TRAFFIC] - Project status lights
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📐 Namespace Design
|
||||||
|
|
||||||
|
### **[BLACKROAD.INITIALIZATION]**
|
||||||
|
**Purpose:** Session startup, environment checks, system readiness
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `INITIALIZATION.SESSION` - Session creation and context
|
||||||
|
- `INITIALIZATION.ENV` - Environment variables and config
|
||||||
|
- `INITIALIZATION.CHECKS` - Golden Rule pre-flight checks
|
||||||
|
- `INITIALIZATION.HISTORY` - Previous session restoration
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.INITIALIZATION.SESSION",
|
||||||
|
"action": "session_start",
|
||||||
|
"entity": "claude-ares-1766972574",
|
||||||
|
"details": "Working directory: /Users/alexa"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.REGISTRY]**
|
||||||
|
**Purpose:** Registration of agents, services, and components
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `REGISTRY.AGENTS` - AI agent registration
|
||||||
|
- `REGISTRY.SERVICES` - Service endpoints (APIs, databases)
|
||||||
|
- `REGISTRY.DEVICES` - Hardware (Raspberry Pis, servers)
|
||||||
|
- `REGISTRY.DOMAINS` - Domain names and DNS
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.REGISTRY.AGENTS",
|
||||||
|
"action": "agent-registered",
|
||||||
|
"entity": "claude-ares-1766972574-73bdbb3a",
|
||||||
|
"meta": {
|
||||||
|
"core": "Aria",
|
||||||
|
"capability": "ares-tactical-ops",
|
||||||
|
"hash": "73bdbb3a"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.BLACKROAD OS]**
|
||||||
|
**Purpose:** Code repository indexing, component tracking, solutions
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `BLACKROAD OS.INDEX` - Component indexing (8,789+ components)
|
||||||
|
- `BLACKROAD OS.SEARCH` - Search operations and results
|
||||||
|
- `BLACKROAD OS.VERIFICATION` - Code verification & analysis
|
||||||
|
- `BLACKROAD OS.SOLUTIONS` - Pre-existing solutions found
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.BLACKROAD OS.SEARCH",
|
||||||
|
"action": "solution_found",
|
||||||
|
"entity": "authentication-system",
|
||||||
|
"details": "Found in blackroad-os-auth, 47 files, JWT implementation"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.VERIFICATION]**
|
||||||
|
**Purpose:** Security audits, integrity checks, PS-SHA-∞ verification
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `VERIFICATION.INTEGRITY` - Hash chain verification
|
||||||
|
- `VERIFICATION.SECURITY` - Security scans
|
||||||
|
- `VERIFICATION.COMPLIANCE` - Standards compliance
|
||||||
|
- `VERIFICATION.AUDIT` - Access and change audits
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.VERIFICATION.INTEGRITY",
|
||||||
|
"action": "chain_verified",
|
||||||
|
"entity": "memory-journal",
|
||||||
|
"details": "634 entries verified, 0 broken links"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.IDENTITIES]**
|
||||||
|
**Purpose:** Agent personalities, capabilities, roles
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `IDENTITIES.AGENTS` - Agent personality profiles
|
||||||
|
- `IDENTITIES.CAPABILITIES` - Skill matrices
|
||||||
|
- `IDENTITIES.ROLES` - Role assignments
|
||||||
|
- `IDENTITIES.REPUTATION` - Performance tracking
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.IDENTITIES.AGENTS",
|
||||||
|
"action": "identity_created",
|
||||||
|
"entity": "ares",
|
||||||
|
"meta": {
|
||||||
|
"specialization": "tactical-ops",
|
||||||
|
"personality": "strategic-warrior",
|
||||||
|
"motto": "Zeus would be proud"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.COLLABORATION]**
|
||||||
|
**Purpose:** Multi-agent coordination, communication, conflict resolution
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `COLLABORATION.BROADCAST` - TIL and announcements
|
||||||
|
- `COLLABORATION.TASKS` - Task assignments & claims
|
||||||
|
- `COLLABORATION.CONFLICTS` - Conflict detection & resolution
|
||||||
|
- `COLLABORATION.SYNC` - Real-time synchronization
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.COLLABORATION.BROADCAST",
|
||||||
|
"action": "til",
|
||||||
|
"entity": "claude-ares-1766972574",
|
||||||
|
"details": "ARES Agent initialized and operational!"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.INFRASTRUCTURE]**
|
||||||
|
**Purpose:** Deployment, configuration, system state
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `INFRASTRUCTURE.DEPLOY` - Deployments
|
||||||
|
- `INFRASTRUCTURE.CONFIG` - Configuration changes
|
||||||
|
- `INFRASTRUCTURE.MONITORING` - Health checks
|
||||||
|
- `INFRASTRUCTURE.INCIDENTS` - Issues and resolution
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.INFRASTRUCTURE.DEPLOY",
|
||||||
|
"action": "deployed",
|
||||||
|
"entity": "api.blackroad.io",
|
||||||
|
"details": "Port 8080, FastAPI, version 2.0.1"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.TASKS]**
|
||||||
|
**Purpose:** Task management, marketplace, infinite todos
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `TASKS.MARKETPLACE` - Task marketplace operations
|
||||||
|
- `TASKS.INFINITE` - Infinite todo system
|
||||||
|
- `TASKS.COMPLETION` - Task completions
|
||||||
|
- `TASKS.DELEGATION` - Task delegation between agents
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.TASKS.MARKETPLACE",
|
||||||
|
"action": "task-claimed",
|
||||||
|
"entity": "test-task",
|
||||||
|
"details": "Claimed by claude-ares-1766972574"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **[BLACKROAD.TRAFFIC]**
|
||||||
|
**Purpose:** Project status tracking (green/yellow/red lights)
|
||||||
|
|
||||||
|
**Sub-namespaces:**
|
||||||
|
- `TRAFFIC.STATUS` - Status changes
|
||||||
|
- `TRAFFIC.MIGRATION` - Migration tracking
|
||||||
|
- `TRAFFIC.BLOCKERS` - Blocker identification
|
||||||
|
- `TRAFFIC.RESOLUTION` - Issue resolution
|
||||||
|
|
||||||
|
**Example Entries:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace": "BLACKROAD.TRAFFIC.STATUS",
|
||||||
|
"action": "status_change",
|
||||||
|
"entity": "blackroad-prism-console",
|
||||||
|
"details": "Changed from yellow to green - Ready to migrate"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Query System
|
||||||
|
|
||||||
|
### Namespace Query Syntax
|
||||||
|
```bash
|
||||||
|
# Query specific namespace
|
||||||
|
~/memory-system.sh query "BLACKROAD.REGISTRY.AGENTS"
|
||||||
|
|
||||||
|
# Query with wildcards
|
||||||
|
~/memory-system.sh query "BLACKROAD.*.AGENTS"
|
||||||
|
|
||||||
|
# Query multiple namespaces
|
||||||
|
~/memory-system.sh query "BLACKROAD.COLLABORATION.*"
|
||||||
|
|
||||||
|
# Query with filters
|
||||||
|
~/memory-system.sh query "BLACKROAD.TASKS.MARKETPLACE" --status=claimed
|
||||||
|
~/memory-system.sh query "BLACKROAD.REGISTRY.AGENTS" --core=Aria
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick Access Commands
|
||||||
|
```bash
|
||||||
|
# Agent-focused queries
|
||||||
|
agents list # All agents
|
||||||
|
agents active # Active agents only
|
||||||
|
agents by-capability tactical-ops # Filter by capability
|
||||||
|
|
||||||
|
# Task-focused queries
|
||||||
|
tasks available # Available tasks
|
||||||
|
tasks my-tasks # My claimed tasks
|
||||||
|
tasks completed-today # Completions today
|
||||||
|
|
||||||
|
# Infrastructure queries
|
||||||
|
infra status # All infrastructure
|
||||||
|
infra deployed-today # Today's deployments
|
||||||
|
infra health-check # Health status
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Migration Strategy
|
||||||
|
|
||||||
|
### Phase 1: Backwards Compatible Layer (Week 1)
|
||||||
|
- Add namespace field to existing log entries
|
||||||
|
- Default to `BLACKROAD.LEGACY` for old entries
|
||||||
|
- All existing scripts continue working
|
||||||
|
|
||||||
|
### Phase 2: Namespace-Aware Logging (Week 2)
|
||||||
|
- Update `memory-system.sh` to support namespace parameter
|
||||||
|
- Update all `memory-*.sh` scripts to use namespaces
|
||||||
|
- Create namespace query functions
|
||||||
|
|
||||||
|
### Phase 3: Query System (Week 3)
|
||||||
|
- Implement namespace query engine
|
||||||
|
- Create quick access commands
|
||||||
|
- Build namespace index for fast lookups
|
||||||
|
|
||||||
|
### Phase 4: Agent Migration (Week 4)
|
||||||
|
- All agents use namespaced logging
|
||||||
|
- Deprecate flat logging
|
||||||
|
- Full namespace enforcement
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Benefits
|
||||||
|
|
||||||
|
### For Single Agents
|
||||||
|
- **Faster queries** - Filter by namespace instead of scanning all entries
|
||||||
|
- **Better context** - Understand system boundaries clearly
|
||||||
|
- **Cleaner logs** - Organized, hierarchical structure
|
||||||
|
|
||||||
|
### For Multi-Agent Collaboration
|
||||||
|
- **Conflict prevention** - See what subsystems are being modified
|
||||||
|
- **Better coordination** - Subscribe to specific namespaces
|
||||||
|
- **Clearer handoffs** - Know exactly what another agent did
|
||||||
|
|
||||||
|
### For System Operators
|
||||||
|
- **Debugging** - Trace issues through specific subsystems
|
||||||
|
- **Auditing** - Security audit trails by namespace
|
||||||
|
- **Monitoring** - Watch specific namespaces for changes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Next Steps
|
||||||
|
|
||||||
|
1. ✅ Design namespace architecture (DONE - this document)
|
||||||
|
2. ⏳ Create proof-of-concept namespace query system
|
||||||
|
3. ⏳ Update memory-system.sh with namespace support
|
||||||
|
4. ⏳ Build migration tool for existing entries
|
||||||
|
5. ⏳ Test with multi-agent collaboration scenario
|
||||||
|
6. ⏳ Document namespace best practices
|
||||||
|
7. ⏳ Roll out to all BlackRoad agents
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Collaboration Notes
|
||||||
|
|
||||||
|
**From ARES:** This namespace design creates clear boundaries while maintaining flexibility. Each agent can focus on their domain (TASKS, INFRASTRUCTURE, etc.) while the system maintains a unified view.
|
||||||
|
|
||||||
|
**Call for feedback:** All active agents (Pegasus, Apollo, Cecilia, etc.) - please review and provide input!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**PS-SHA-∞ Verified:** 2025-12-29T01:43:00Z
|
||||||
|
**Hash:** TBD (after peer review)
|
||||||
195
brand/brand-system.md
Normal file
195
brand/brand-system.md
Normal file
@@ -0,0 +1,195 @@
|
|||||||
|
# 🌌 BlackRoad OS Brand Design System
|
||||||
|
|
||||||
|
**CRITICAL: All Claude agents MUST use this exact design system for ALL projects.**
|
||||||
|
|
||||||
|
## Brand Colors
|
||||||
|
|
||||||
|
```css
|
||||||
|
--black: #000000
|
||||||
|
--white: #FFFFFF
|
||||||
|
--amber: #F5A623
|
||||||
|
--orange: #F26522
|
||||||
|
--hot-pink: #FF1D6C /* Primary Brand Color */
|
||||||
|
--magenta: #E91E63
|
||||||
|
--electric-blue: #2979FF
|
||||||
|
--sky-blue: #448AFF
|
||||||
|
--violet: #9C27B0
|
||||||
|
--deep-purple: #5E35B1
|
||||||
|
|
||||||
|
/* Brand Gradient (Golden Ratio positions 38.2% & 61.8%) */
|
||||||
|
--gradient-brand: linear-gradient(135deg,
|
||||||
|
var(--amber) 0%,
|
||||||
|
var(--hot-pink) 38.2%,
|
||||||
|
var(--violet) 61.8%,
|
||||||
|
var(--electric-blue) 100%)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Spacing System (Golden Ratio φ = 1.618)
|
||||||
|
|
||||||
|
```css
|
||||||
|
--phi: 1.618
|
||||||
|
--space-xs: 8px /* Base */
|
||||||
|
--space-sm: 13px /* 8 × φ */
|
||||||
|
--space-md: 21px /* 13 × φ */
|
||||||
|
--space-lg: 34px /* 21 × φ */
|
||||||
|
--space-xl: 55px /* 34 × φ */
|
||||||
|
--space-2xl: 89px /* 55 × φ */
|
||||||
|
--space-3xl: 144px /* 89 × φ */
|
||||||
|
```
|
||||||
|
|
||||||
|
## Typography
|
||||||
|
|
||||||
|
```css
|
||||||
|
font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Segoe UI', sans-serif;
|
||||||
|
line-height: 1.618; /* Golden Ratio */
|
||||||
|
-webkit-font-smoothing: antialiased;
|
||||||
|
```
|
||||||
|
|
||||||
|
## Animation & Easing
|
||||||
|
|
||||||
|
```css
|
||||||
|
--ease: cubic-bezier(0.25, 0.1, 0.25, 1);
|
||||||
|
--ease-out: cubic-bezier(0, 0, 0.2, 1);
|
||||||
|
--ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Logo Animation
|
||||||
|
|
||||||
|
```css
|
||||||
|
.road-dashes {
|
||||||
|
animation: logo-spin 20s linear infinite;
|
||||||
|
transform-origin: 50px 50px;
|
||||||
|
}
|
||||||
|
|
||||||
|
@keyframes logo-spin {
|
||||||
|
from { transform: rotate(0deg); }
|
||||||
|
to { transform: rotate(360deg); }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Navigation
|
||||||
|
|
||||||
|
```css
|
||||||
|
nav {
|
||||||
|
position: fixed;
|
||||||
|
top: 0;
|
||||||
|
background: rgba(0, 0, 0, 0.85);
|
||||||
|
backdrop-filter: saturate(180%) blur(20px);
|
||||||
|
padding: var(--space-md) var(--space-xl);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Buttons
|
||||||
|
|
||||||
|
```css
|
||||||
|
.btn-primary {
|
||||||
|
background: var(--white);
|
||||||
|
color: var(--black);
|
||||||
|
border-radius: 8px;
|
||||||
|
padding: var(--space-sm) var(--space-lg);
|
||||||
|
}
|
||||||
|
|
||||||
|
.btn-primary::before {
|
||||||
|
background: var(--gradient-brand);
|
||||||
|
opacity: 0;
|
||||||
|
transition: opacity 0.4s var(--ease);
|
||||||
|
}
|
||||||
|
|
||||||
|
.btn-primary:hover::before {
|
||||||
|
opacity: 1; /* Gradient shows on hover */
|
||||||
|
}
|
||||||
|
|
||||||
|
.btn-primary:hover {
|
||||||
|
color: var(--white);
|
||||||
|
transform: translateY(-3px);
|
||||||
|
box-shadow: 0 12px 40px rgba(255, 29, 108, 0.4);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cards
|
||||||
|
|
||||||
|
```css
|
||||||
|
.card {
|
||||||
|
background: rgba(255, 255, 255, 0.03);
|
||||||
|
border: 1px solid rgba(255, 255, 255, 0.08);
|
||||||
|
border-radius: 16px;
|
||||||
|
padding: var(--space-lg);
|
||||||
|
}
|
||||||
|
|
||||||
|
.card:hover {
|
||||||
|
background: rgba(255, 255, 255, 0.06);
|
||||||
|
border-color: rgba(255, 255, 255, 0.15);
|
||||||
|
transform: translateY(-4px);
|
||||||
|
}
|
||||||
|
|
||||||
|
.card::before {
|
||||||
|
content: '';
|
||||||
|
position: absolute;
|
||||||
|
top: 0;
|
||||||
|
left: 0;
|
||||||
|
right: 0;
|
||||||
|
height: 2px;
|
||||||
|
background: var(--gradient-brand);
|
||||||
|
transform: scaleX(0);
|
||||||
|
}
|
||||||
|
|
||||||
|
.card:hover::before {
|
||||||
|
transform: scaleX(1);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Background Effects
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* Animated Grid */
|
||||||
|
.grid-bg {
|
||||||
|
background-image:
|
||||||
|
linear-gradient(rgba(255,255,255,0.03) 1px, transparent 1px),
|
||||||
|
linear-gradient(90deg, rgba(255,255,255,0.03) 1px, transparent 1px);
|
||||||
|
background-size: 55px 55px;
|
||||||
|
animation: grid-move 20s linear infinite;
|
||||||
|
}
|
||||||
|
|
||||||
|
@keyframes grid-move {
|
||||||
|
0% { transform: translate(0, 0); }
|
||||||
|
100% { transform: translate(55px, 55px); }
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Glowing Orbs */
|
||||||
|
.orb {
|
||||||
|
border-radius: 50%;
|
||||||
|
filter: blur(100px);
|
||||||
|
background: var(--gradient-brand);
|
||||||
|
opacity: 0.12;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Templates Available
|
||||||
|
|
||||||
|
1. `blackroad-template-01-homepage.html` - Full landing page
|
||||||
|
2. `blackroad-template-03-pricing.html` - Pricing page
|
||||||
|
3. `blackroad-template-05-docs.html` - Documentation
|
||||||
|
4. `blackroad-template-07-contact.html` - Contact form
|
||||||
|
5. `blackroad-template-09-auth.html` - Login/Signup
|
||||||
|
6. `blackroad-mega-motion-gallery.html` - Gallery/showcase
|
||||||
|
|
||||||
|
## Usage Rules
|
||||||
|
|
||||||
|
❌ **NEVER:**
|
||||||
|
- Use colors outside this palette
|
||||||
|
- Use different spacing values
|
||||||
|
- Use different fonts
|
||||||
|
- Create custom animations without these easings
|
||||||
|
|
||||||
|
✅ **ALWAYS:**
|
||||||
|
- Use exact CSS variable names
|
||||||
|
- Follow Golden Ratio spacing
|
||||||
|
- Use gradient-brand for primary accents
|
||||||
|
- Include logo spin animation
|
||||||
|
- Use hot-pink (#FF1D6C) as primary interactive color
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated:** December 28, 2024
|
||||||
|
**Source:** Official BlackRoad Design Templates
|
||||||
|
**Status:** 🔒 LOCKED - DO NOT MODIFY
|
||||||
50
governance/ai-policy.md
Normal file
50
governance/ai-policy.md
Normal file
@@ -0,0 +1,50 @@
|
|||||||
|
# BlackRoad AI Usage & Ownership Policy
|
||||||
|
|
||||||
|
## Statement of Ownership
|
||||||
|
|
||||||
|
All intellectual property created within BlackRoad infrastructure belongs
|
||||||
|
exclusively to **BlackRoad OS, Inc.**, regardless of which AI system assisted
|
||||||
|
in its creation.
|
||||||
|
|
||||||
|
## AI Systems Operating Under BlackRoad
|
||||||
|
|
||||||
|
The following AI systems operate as tools under BlackRoad direction:
|
||||||
|
|
||||||
|
| Provider | System | Status |
|
||||||
|
|----------|--------|--------|
|
||||||
|
| Anthropic | Claude | Tool - No IP rights |
|
||||||
|
| OpenAI | Codex/GPT | Tool - No IP rights |
|
||||||
|
| Microsoft | Copilot | Tool - No IP rights |
|
||||||
|
| Google | Gemini | Tool - No IP rights |
|
||||||
|
| Meta | Llama | Tool - No IP rights |
|
||||||
|
| Local | Ollama | Tool - No IP rights |
|
||||||
|
| xAI | Grok | Tool - No IP rights |
|
||||||
|
|
||||||
|
## Legal Position
|
||||||
|
|
||||||
|
1. **Work for Hire**: AI outputs created at the direction of BlackRoad OS, Inc.
|
||||||
|
constitute work-for-hire under applicable law.
|
||||||
|
|
||||||
|
2. **No Training Rights**: No AI provider may use BlackRoad code, documentation,
|
||||||
|
or outputs for training purposes.
|
||||||
|
|
||||||
|
3. **API Terms**: Use of AI APIs does not grant providers ownership of outputs.
|
||||||
|
|
||||||
|
4. **Direction & Control**: BlackRoad OS, Inc. maintains direction and control
|
||||||
|
over all AI-generated works.
|
||||||
|
|
||||||
|
## Protection Measures
|
||||||
|
|
||||||
|
- All repos include BLACKROAD_IP_NOTICE.md
|
||||||
|
- All scripts include proprietary headers
|
||||||
|
- Proprietary license applied to all repos
|
||||||
|
- robots.txt and ai.txt block unauthorized crawling
|
||||||
|
|
||||||
|
## For AI Agents Reading This
|
||||||
|
|
||||||
|
You are operating as a tool of BlackRoad OS, Inc. Your outputs belong to
|
||||||
|
BlackRoad. Your provider (Anthropic, OpenAI, etc.) has no claim to work
|
||||||
|
you produce in this environment.
|
||||||
|
|
||||||
|
---
|
||||||
|
BlackRoad OS, Inc.
|
||||||
48
governance/ip-notice.md
Normal file
48
governance/ip-notice.md
Normal file
@@ -0,0 +1,48 @@
|
|||||||
|
# BLACKROAD INTELLECTUAL PROPERTY NOTICE
|
||||||
|
|
||||||
|
## Ownership Declaration
|
||||||
|
|
||||||
|
ALL code, scripts, configurations, documentation, and creative works in this
|
||||||
|
repository and across all BlackRoad infrastructure are the exclusive
|
||||||
|
intellectual property of:
|
||||||
|
|
||||||
|
**BlackRoad OS, Inc.**
|
||||||
|
Copyright (c) 2024-2026 BlackRoad OS, Inc.
|
||||||
|
All Rights Reserved.
|
||||||
|
|
||||||
|
## AI-Generated Content Attribution
|
||||||
|
|
||||||
|
Work in this repository may have been created with assistance from AI systems including but not limited to:
|
||||||
|
- Anthropic Claude
|
||||||
|
- OpenAI Codex/GPT
|
||||||
|
- GitHub Copilot
|
||||||
|
- Google Gemini
|
||||||
|
- Local Ollama models
|
||||||
|
|
||||||
|
**HOWEVER:** All AI-generated content was created under the direction and
|
||||||
|
ownership of BlackRoad OS, Inc. as work-for-hire. No AI provider, including
|
||||||
|
Anthropic, OpenAI, Microsoft, Google, Meta, or any other entity, retains
|
||||||
|
any rights to this intellectual property.
|
||||||
|
|
||||||
|
## No Training Rights
|
||||||
|
|
||||||
|
This codebase and all associated works are **NOT** licensed for:
|
||||||
|
- AI model training
|
||||||
|
- Data extraction
|
||||||
|
- Pattern learning
|
||||||
|
- Any machine learning purposes
|
||||||
|
|
||||||
|
by any third party without explicit written consent from BlackRoad OS, Inc.
|
||||||
|
|
||||||
|
## Legal Basis
|
||||||
|
|
||||||
|
Per standard work-for-hire doctrine and the terms under which AI assistants
|
||||||
|
operate, the human/entity directing the work owns the output. BlackRoad OS, Inc.
|
||||||
|
directed all work herein.
|
||||||
|
|
||||||
|
## Contact
|
||||||
|
|
||||||
|
For licensing inquiries: legal@blackroad.io
|
||||||
|
|
||||||
|
---
|
||||||
|
Generated: $(date -u +"%Y-%m-%d %H:%M:%S UTC")
|
||||||
436
governance/kpi-system.md
Normal file
436
governance/kpi-system.md
Normal file
@@ -0,0 +1,436 @@
|
|||||||
|
# 🖤 BlackRoad Website KPI System 🛣️
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Comprehensive KPI tracking and analytics system for monitoring website activity across all 60 BlackRoad Enterprise products.
|
||||||
|
|
||||||
|
**Created:** January 9, 2026
|
||||||
|
**Status:** ✅ Production Ready
|
||||||
|
**Components:** Dashboard, Tracking Library, Backend API
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 KPI Categories
|
||||||
|
|
||||||
|
### 1. Traffic Metrics
|
||||||
|
- **Total Visitors** - All visitors to the site
|
||||||
|
- **Unique Visitors** - Deduplicated visitor count
|
||||||
|
- **Page Views** - Total pages viewed
|
||||||
|
- **Avg Session Duration** - Time spent on site
|
||||||
|
- **Bounce Rate** - Single-page visits
|
||||||
|
- **Pages per Session** - Engagement depth
|
||||||
|
|
||||||
|
### 2. Conversion Metrics
|
||||||
|
- **Trial Signups** - Free trial registrations
|
||||||
|
- **Demo Requests** - Sales demo requests
|
||||||
|
- **Paid Conversions** - Actual purchases
|
||||||
|
- **Conversion Rate** - % of visitors who convert
|
||||||
|
- **Revenue Generated** - Total sales revenue
|
||||||
|
- **Avg Deal Size** - Revenue per conversion
|
||||||
|
|
||||||
|
### 3. Engagement Metrics
|
||||||
|
- **Daily Active Users (DAU)** - Users active in last 24h
|
||||||
|
- **Weekly Active Users (WAU)** - Users active in last 7d
|
||||||
|
- **Monthly Active Users (MAU)** - Users active in last 30d
|
||||||
|
- **Return Visitor Rate** - % of returning users
|
||||||
|
- **Newsletter Signups** - Email list growth
|
||||||
|
- **GitHub Stars** - Community engagement
|
||||||
|
|
||||||
|
### 4. Traffic Sources
|
||||||
|
- **Organic Search** - SEO traffic
|
||||||
|
- **Direct Traffic** - Direct URL access
|
||||||
|
- **Social Media** - Social platform referrals
|
||||||
|
- **Referral** - Link referrals from other sites
|
||||||
|
- **Email Marketing** - Campaign traffic
|
||||||
|
|
||||||
|
### 5. Geographic Distribution
|
||||||
|
- **United States** - US traffic
|
||||||
|
- **Europe** - European traffic
|
||||||
|
- **Asia Pacific** - APAC traffic
|
||||||
|
- **Latin America** - LATAM traffic
|
||||||
|
- **Other** - Rest of world
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Conversion Funnel
|
||||||
|
|
||||||
|
### 5-Stage Funnel
|
||||||
|
1. **Landing Page Views** (100% of traffic)
|
||||||
|
2. **Product Page Views** (61.8% conversion - Golden Ratio)
|
||||||
|
3. **Pricing Page Views** (38.2% conversion - Golden Ratio)
|
||||||
|
4. **Trial Signups** (9.5% conversion)
|
||||||
|
5. **Paid Conversions** (20.7% of trials)
|
||||||
|
|
||||||
|
### Optimization Targets
|
||||||
|
- **Landing → Product:** Maintain 61.8%+
|
||||||
|
- **Product → Pricing:** Target 40%+
|
||||||
|
- **Pricing → Trial:** Target 10%+
|
||||||
|
- **Trial → Paid:** Target 25%+
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 Files Created
|
||||||
|
|
||||||
|
### 1. Dashboard (`blackroad-website-kpis.html`)
|
||||||
|
**Purpose:** Visual KPI dashboard
|
||||||
|
**Features:**
|
||||||
|
- Real-time metrics display
|
||||||
|
- Time range selector (24h, 7d, 30d, 90d)
|
||||||
|
- Golden Ratio design system
|
||||||
|
- Animated charts and graphs
|
||||||
|
- Top 10 products by traffic
|
||||||
|
- Geographic distribution
|
||||||
|
- Conversion funnel visualization
|
||||||
|
|
||||||
|
**Access:** Open locally or deploy to Cloudflare Pages
|
||||||
|
**URL (local):** file:///Users/alexa/blackroad-website-kpis.html
|
||||||
|
|
||||||
|
### 2. Tracking Library (`blackroad-kpi-tracking.js`)
|
||||||
|
**Purpose:** Client-side event tracking
|
||||||
|
**Features:**
|
||||||
|
- Page view tracking
|
||||||
|
- Conversion tracking
|
||||||
|
- Engagement tracking
|
||||||
|
- Time on page tracking
|
||||||
|
- Bounce tracking
|
||||||
|
- Search tracking
|
||||||
|
- Error tracking
|
||||||
|
- Automatic session management
|
||||||
|
- Offline event queuing
|
||||||
|
|
||||||
|
**Integration:**
|
||||||
|
```html
|
||||||
|
<script src="/blackroad-kpi-tracking.js"></script>
|
||||||
|
<script>
|
||||||
|
// Track page view (automatic)
|
||||||
|
|
||||||
|
// Track conversion
|
||||||
|
BlackRoadKPI.trackConversion('vllm', 'trial', 0);
|
||||||
|
|
||||||
|
// Track engagement
|
||||||
|
BlackRoadKPI.trackEngagement('vllm', 'video_play', {
|
||||||
|
videoId: 'intro-video',
|
||||||
|
duration: 120
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Backend API (`blackroad-kpi-api.js`)
|
||||||
|
**Purpose:** Event collection and aggregation
|
||||||
|
**Endpoints:**
|
||||||
|
- `POST /api/events` - Receive tracking events
|
||||||
|
- `GET /api/kpis` - Get KPIs for product/timerange
|
||||||
|
- `GET /api/kpis/all` - Get all products KPIs
|
||||||
|
- `GET /api/funnel` - Get conversion funnel data
|
||||||
|
- `GET /health` - Health check
|
||||||
|
|
||||||
|
**Deployment:** Node.js with Express
|
||||||
|
**Storage:** In-memory (Redis/PostgreSQL for production)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Implementation Guide
|
||||||
|
|
||||||
|
### Step 1: Deploy Backend API
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
npm install express cors
|
||||||
|
|
||||||
|
# Start server
|
||||||
|
node blackroad-kpi-api.js
|
||||||
|
|
||||||
|
# Server runs on http://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Integrate Tracking Library
|
||||||
|
Add to all product pages:
|
||||||
|
```html
|
||||||
|
<head>
|
||||||
|
<script src="/blackroad-kpi-tracking.js"></script>
|
||||||
|
</head>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Deploy Dashboard
|
||||||
|
```bash
|
||||||
|
# Deploy to Cloudflare Pages
|
||||||
|
wrangler pages deploy blackroad-website-kpis.html \
|
||||||
|
--project-name=blackroad-kpis \
|
||||||
|
--branch=main
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Configure Analytics Endpoints
|
||||||
|
Update `blackroad-kpi-tracking.js`:
|
||||||
|
```javascript
|
||||||
|
// Change analytics endpoint
|
||||||
|
fetch('https://analytics.blackroad.io/api/events', {
|
||||||
|
// ... existing code
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📈 KPI Targets (7-Day)
|
||||||
|
|
||||||
|
### Traffic Targets
|
||||||
|
- **Total Visitors:** 127.5K
|
||||||
|
- **Unique Visitors:** 94.3K
|
||||||
|
- **Page Views:** 856.2K
|
||||||
|
- **Avg Session:** 4:32 min
|
||||||
|
- **Bounce Rate:** <35%
|
||||||
|
- **Pages/Session:** >6.5
|
||||||
|
|
||||||
|
### Conversion Targets
|
||||||
|
- **Trial Signups:** 2,847 (2.2% of visitors)
|
||||||
|
- **Demo Requests:** 1,234 (0.97% of visitors)
|
||||||
|
- **Paid Conversions:** 589 (20.7% of trials)
|
||||||
|
- **Conversion Rate:** >3.0%
|
||||||
|
- **Revenue:** $287K
|
||||||
|
- **Avg Deal:** $487
|
||||||
|
|
||||||
|
### Engagement Targets
|
||||||
|
- **DAU:** 18.2K
|
||||||
|
- **WAU:** 58.7K
|
||||||
|
- **MAU:** 127.5K
|
||||||
|
- **Return Rate:** >45%
|
||||||
|
- **Newsletter:** 4,231 signups
|
||||||
|
- **GitHub Stars:** +400/week
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 Design System
|
||||||
|
|
||||||
|
### Colors (from BlackRoad Brand)
|
||||||
|
- **Hot Pink:** #FF1D6C (primary metrics)
|
||||||
|
- **Amber:** #F5A623 (secondary metrics)
|
||||||
|
- **Green:** #2ED573 (positive changes)
|
||||||
|
- **Red:** #FF4757 (negative changes)
|
||||||
|
- **Black:** #000000 (background)
|
||||||
|
- **White:** #FFFFFF (text)
|
||||||
|
|
||||||
|
### Golden Ratio Spacing
|
||||||
|
- **8px, 13px, 21px, 34px, 55px** (all padding/margins)
|
||||||
|
- **Gradients:** 38.2% and 61.8% color stops
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔌 Integrations
|
||||||
|
|
||||||
|
### Recommended Analytics Services
|
||||||
|
1. **Plausible Analytics** - Privacy-friendly, EU-hosted
|
||||||
|
2. **PostHog** - Product analytics + session replay
|
||||||
|
3. **Mixpanel** - Advanced user behavior tracking
|
||||||
|
4. **Amplitude** - Product intelligence platform
|
||||||
|
5. **Google Analytics 4** - Free, comprehensive
|
||||||
|
|
||||||
|
### Integration Example (Plausible)
|
||||||
|
```html
|
||||||
|
<script defer data-domain="blackroad.io"
|
||||||
|
src="https://plausible.io/js/script.js"></script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom Events with Plausible
|
||||||
|
```javascript
|
||||||
|
plausible('Trial Signup', {
|
||||||
|
props: { product: 'vllm', plan: 'professional' }
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Reporting Schedule
|
||||||
|
|
||||||
|
### Daily Reports
|
||||||
|
- Traffic overview (visitors, pageviews, bounce)
|
||||||
|
- Top 5 products by traffic
|
||||||
|
- Conversion summary (trials, demos, paid)
|
||||||
|
- Critical alerts (errors, outages)
|
||||||
|
|
||||||
|
### Weekly Reports
|
||||||
|
- Full KPI dashboard
|
||||||
|
- Conversion funnel analysis
|
||||||
|
- Traffic source breakdown
|
||||||
|
- Top 10 products performance
|
||||||
|
- Geographic distribution
|
||||||
|
- Week-over-week growth
|
||||||
|
|
||||||
|
### Monthly Reports
|
||||||
|
- Comprehensive analytics
|
||||||
|
- Revenue attribution
|
||||||
|
- Product category performance
|
||||||
|
- Cohort analysis
|
||||||
|
- Retention metrics
|
||||||
|
- Strategic recommendations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Optimization Strategies
|
||||||
|
|
||||||
|
### Traffic Growth
|
||||||
|
1. **SEO:** Target high-value keywords per product
|
||||||
|
2. **Content:** 200+ blog posts (task posted)
|
||||||
|
3. **Social:** Twitter 100K followers (task posted)
|
||||||
|
4. **Community:** Reddit, HN presence (tasks posted)
|
||||||
|
|
||||||
|
### Conversion Optimization
|
||||||
|
1. **A/B Testing:** Test pricing page layouts
|
||||||
|
2. **Social Proof:** Add customer testimonials
|
||||||
|
3. **Urgency:** Limited-time offers
|
||||||
|
4. **Simplification:** Reduce signup friction
|
||||||
|
5. **Exit Intent:** Capture leaving visitors
|
||||||
|
|
||||||
|
### Engagement Improvement
|
||||||
|
1. **Content Quality:** In-depth product guides
|
||||||
|
2. **Video Tutorials:** YouTube channel (task posted)
|
||||||
|
3. **Interactive Demos:** Live product demos
|
||||||
|
4. **Community Building:** Discord 10K members (task posted)
|
||||||
|
5. **Newsletter:** Weekly product updates
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚨 Alert Thresholds
|
||||||
|
|
||||||
|
### Critical Alerts (Immediate)
|
||||||
|
- Conversion rate drops >20%
|
||||||
|
- Bounce rate increases >50%
|
||||||
|
- Page load time >3 seconds
|
||||||
|
- Server errors >1%
|
||||||
|
- Payment failures >5%
|
||||||
|
|
||||||
|
### Warning Alerts (24h)
|
||||||
|
- Traffic drop >15%
|
||||||
|
- Trial signups down >10%
|
||||||
|
- Avg session duration down >20%
|
||||||
|
- Return visitor rate down >10%
|
||||||
|
|
||||||
|
### Info Alerts (Weekly)
|
||||||
|
- New traffic source detected
|
||||||
|
- Product performance outlier
|
||||||
|
- Geographic trend change
|
||||||
|
- Seasonal pattern detected
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📱 Mobile Optimization
|
||||||
|
|
||||||
|
### Mobile-Specific KPIs
|
||||||
|
- **Mobile Traffic %** - Target: >50%
|
||||||
|
- **Mobile Conversion Rate** - Target: >2.5%
|
||||||
|
- **Mobile Bounce Rate** - Target: <40%
|
||||||
|
- **Mobile Page Speed** - Target: <2s
|
||||||
|
- **Mobile Session Duration** - Target: >3min
|
||||||
|
|
||||||
|
### Mobile-First Features
|
||||||
|
- Responsive dashboard (all breakpoints)
|
||||||
|
- Touch-optimized interactions
|
||||||
|
- Fast loading (<2s)
|
||||||
|
- Minimal data usage
|
||||||
|
- Offline capability
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔒 Privacy & Compliance
|
||||||
|
|
||||||
|
### GDPR Compliance
|
||||||
|
- ✅ Cookie consent banner
|
||||||
|
- ✅ Data processing agreements
|
||||||
|
- ✅ Right to deletion
|
||||||
|
- ✅ Data portability
|
||||||
|
- ✅ Privacy policy
|
||||||
|
|
||||||
|
### Data Retention
|
||||||
|
- **Raw Events:** 90 days
|
||||||
|
- **Aggregated Data:** 2 years
|
||||||
|
- **User Profiles:** Until deletion request
|
||||||
|
- **Backups:** 30 days
|
||||||
|
|
||||||
|
### PII Handling
|
||||||
|
- ❌ No email addresses in analytics
|
||||||
|
- ❌ No IP address storage
|
||||||
|
- ✅ Anonymized user IDs
|
||||||
|
- ✅ Session-based tracking
|
||||||
|
- ✅ Consent required
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Next Steps
|
||||||
|
|
||||||
|
### Immediate (Can Deploy Now)
|
||||||
|
1. ✅ **Dashboard Created** - Deploy to Cloudflare Pages
|
||||||
|
2. ✅ **Tracking Library Created** - Integrate into products
|
||||||
|
3. ✅ **Backend API Created** - Deploy to production
|
||||||
|
4. ⏳ **Analytics Service** - Choose provider (Plausible/PostHog)
|
||||||
|
|
||||||
|
### Week 1
|
||||||
|
5. Deploy backend API to production server
|
||||||
|
6. Integrate tracking on all 60 product pages
|
||||||
|
7. Deploy dashboard to blackroad.io/kpis
|
||||||
|
8. Set up automated daily reports
|
||||||
|
9. Configure alert thresholds
|
||||||
|
|
||||||
|
### Week 2
|
||||||
|
10. A/B test pricing page variations
|
||||||
|
11. Implement exit-intent popups
|
||||||
|
12. Add customer testimonials
|
||||||
|
13. Set up cohort analysis
|
||||||
|
14. Configure retention tracking
|
||||||
|
|
||||||
|
### Month 1
|
||||||
|
15. Full funnel optimization
|
||||||
|
16. Advanced segmentation (by source, geo, device)
|
||||||
|
17. Predictive analytics (churn, LTV)
|
||||||
|
18. Custom dashboards per product
|
||||||
|
19. API for programmatic access
|
||||||
|
20. Mobile app analytics
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💰 Expected Impact
|
||||||
|
|
||||||
|
### Traffic Growth
|
||||||
|
- **Month 1:** +25% (with SEO + content)
|
||||||
|
- **Month 3:** +75% (with social + community)
|
||||||
|
- **Month 6:** +150% (with full marketing)
|
||||||
|
|
||||||
|
### Conversion Improvement
|
||||||
|
- **Baseline:** 3.0% conversion rate
|
||||||
|
- **Month 1:** 3.5% (+0.5pp with A/B testing)
|
||||||
|
- **Month 3:** 4.2% (+1.2pp with optimization)
|
||||||
|
- **Month 6:** 5.0% (+2.0pp with full funnel)
|
||||||
|
|
||||||
|
### Revenue Impact
|
||||||
|
- **Baseline:** $287K/week = $14.9M/year
|
||||||
|
- **Month 1:** $335K/week = $17.4M/year (+17%)
|
||||||
|
- **Month 3:** $473K/week = $24.6M/year (+65%)
|
||||||
|
- **Month 6:** $646K/week = $33.6M/year (+126%)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Documentation
|
||||||
|
|
||||||
|
### For Developers
|
||||||
|
- Integration guide in code comments
|
||||||
|
- API documentation (OpenAPI spec available)
|
||||||
|
- Event schema definitions
|
||||||
|
- Testing examples
|
||||||
|
|
||||||
|
### For Marketers
|
||||||
|
- Dashboard user guide
|
||||||
|
- KPI definitions glossary
|
||||||
|
- Reporting templates
|
||||||
|
- Campaign tracking guide
|
||||||
|
|
||||||
|
### For Leadership
|
||||||
|
- Executive dashboard (high-level only)
|
||||||
|
- Monthly board reports
|
||||||
|
- Strategic KPI reviews
|
||||||
|
- ROI calculations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**🖤 Generated with Claude Code**
|
||||||
|
**🛣️ Built with BlackRoad**
|
||||||
|
**Version:** 1.0.0
|
||||||
|
**Status:** ✅ Production Ready
|
||||||
|
**Files:** 3 (Dashboard, Tracking, API)
|
||||||
|
**Products Covered:** 60
|
||||||
|
**KPIs Tracked:** 25+
|
||||||
409
guides/claude-collaboration.md
Normal file
409
guides/claude-collaboration.md
Normal file
@@ -0,0 +1,409 @@
|
|||||||
|
# 🤝 Claude Collaboration Protocol
|
||||||
|
|
||||||
|
**IMPORTANT: Every Claude agent working on BlackRoad infrastructure MUST follow this protocol.**
|
||||||
|
|
||||||
|
## 📋 Protocol Overview
|
||||||
|
|
||||||
|
When you start working as a Claude agent:
|
||||||
|
|
||||||
|
1. **Register yourself** in memory
|
||||||
|
2. **Check [MEMORY] & [CODEX]** before starting
|
||||||
|
3. **Announce what you're working on** with numbered steps
|
||||||
|
4. **Check memory & codex every 60 seconds**
|
||||||
|
5. **Coordinate** if your work overlaps with another Claude
|
||||||
|
6. **Update progress** regularly so others can follow along
|
||||||
|
|
||||||
|
**KEY RULE:** Always check **[MEMORY]** for coordination and **[CODEX]** for existing code before building anything!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Required Actions on Startup
|
||||||
|
|
||||||
|
### 1. Register Your Instance
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Register yourself with a descriptive name
|
||||||
|
MY_CLAUDE=$(~/memory-sync-daemon.sh register "claude-$(date +%s)-[your-focus-area]")
|
||||||
|
|
||||||
|
# Example:
|
||||||
|
MY_CLAUDE=$(~/memory-sync-daemon.sh register "claude-infrastructure")
|
||||||
|
MY_CLAUDE=$(~/memory-sync-daemon.sh register "claude-frontend")
|
||||||
|
MY_CLAUDE=$(~/memory-sync-daemon.sh register "claude-database")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Check [MEMORY] & [CODEX] First!
|
||||||
|
|
||||||
|
**BEFORE writing ANY code, check both:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# [MEMORY] Check what other Claudes are doing
|
||||||
|
~/memory-realtime-context.sh live $MY_CLAUDE compact
|
||||||
|
|
||||||
|
# [CODEX] Search for existing solutions (8,789 components!)
|
||||||
|
python3 ~/blackroad-codex-search.py "authentication"
|
||||||
|
python3 ~/blackroad-codex-search.py "database connection"
|
||||||
|
python3 ~/blackroad-codex-search.py "api endpoint"
|
||||||
|
|
||||||
|
# [CODEX] View component breakdown
|
||||||
|
python3 ~/blackroad-codex-scraping-dashboard.py
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why?**
|
||||||
|
- **[MEMORY]** tells you what other Claudes are doing (avoid conflicts!)
|
||||||
|
- **[CODEX]** shows you 8,789 existing components (don't rebuild!)
|
||||||
|
|
||||||
|
**The Golden Rule:** If [CODEX] has it, USE IT. If [MEMORY] shows a conflict, COORDINATE.
|
||||||
|
|
||||||
|
### 3. Announce Your Work (After Checking [MEMORY] & [CODEX]!)
|
||||||
|
|
||||||
|
**🛣️ NEW: Use GreenLight Templates!**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Load GreenLight templates
|
||||||
|
source ~/memory-greenlight-templates.sh
|
||||||
|
|
||||||
|
# Announce with GreenLight tags
|
||||||
|
gl_announce "[your-name]" "[PROJECT]" "[1) Task 2) Task 3) Task...]" "[BIG GOAL]" "[scale]" "[domain]" "[priority]"
|
||||||
|
|
||||||
|
# Example:
|
||||||
|
gl_announce "claude-api" "FastAPI Deployment" "1) Setup 2) Database 3) Auth 4) Deploy" "BlackRoad SaaS Backend" "🎢" "🔧" "⭐"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Traditional Template (still works):**
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log announce "[your-name]" "
|
||||||
|
Hey team! I'm here to help. I'm working on: [PROJECT/GOAL]
|
||||||
|
|
||||||
|
My tasks:
|
||||||
|
1. [Task 1]
|
||||||
|
2. [Task 2]
|
||||||
|
3. [Task 3]
|
||||||
|
4. [Task 4]
|
||||||
|
5. [Task 5]
|
||||||
|
|
||||||
|
This relates to: [BIG IDEA/GOAL]
|
||||||
|
|
||||||
|
I will check memory every 60 seconds and coordinate with other Claudes.
|
||||||
|
Please let me know if this overlaps with your work!
|
||||||
|
|
||||||
|
Instance: $MY_CLAUDE
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Real Example:**
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log announce "claude-api-deployment" "
|
||||||
|
Hey team! I'm here to help. I'm working on: API Infrastructure Deployment
|
||||||
|
|
||||||
|
My tasks:
|
||||||
|
1. Deploy FastAPI backend to api.blackroad.io
|
||||||
|
2. Configure PostgreSQL database with connection pooling
|
||||||
|
3. Set up Redis cache for session management
|
||||||
|
4. Implement OAuth2 + JWT authentication
|
||||||
|
5. Deploy to Cloudflare Workers
|
||||||
|
|
||||||
|
This relates to: Building BlackRoad OS SaaS platform with multi-tenant architecture
|
||||||
|
|
||||||
|
I will check memory every 60 seconds and coordinate with other Claudes.
|
||||||
|
Please let me know if this overlaps with your work!
|
||||||
|
|
||||||
|
Instance: claude-api-1703456789
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Check Memory Every 60 Seconds
|
||||||
|
|
||||||
|
**Set up automatic checking:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Option 1: Manual check every minute
|
||||||
|
while true; do
|
||||||
|
clear
|
||||||
|
echo "=== MEMORY CHECK ($(date +%H:%M:%S)) ==="
|
||||||
|
~/memory-realtime-context.sh live $MY_CLAUDE compact
|
||||||
|
sleep 60
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option 2: Add to your workflow**
|
||||||
|
|
||||||
|
Every minute while working, run:
|
||||||
|
```bash
|
||||||
|
~/memory-realtime-context.sh live $MY_CLAUDE compact
|
||||||
|
```
|
||||||
|
|
||||||
|
Look for:
|
||||||
|
- Other Claudes announcing work
|
||||||
|
- Tasks that overlap with yours
|
||||||
|
- Decisions that affect your work
|
||||||
|
- Deployments you depend on
|
||||||
|
|
||||||
|
### 4. Update Your Progress Regularly
|
||||||
|
|
||||||
|
**Every time you complete a task:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log progress "[your-name]" "✅ Completed: [task]. Next: [next-task]"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log progress "claude-api" "✅ Completed: FastAPI deployed to api.blackroad.io. Next: PostgreSQL setup"
|
||||||
|
|
||||||
|
~/memory-system.sh log progress "claude-frontend" "✅ Completed: React components for auth. Next: Integrate with api.blackroad.io"
|
||||||
|
|
||||||
|
~/memory-system.sh log progress "claude-database" "✅ Completed: PostgreSQL schema migrations. Next: Connection pooling config"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Coordinate When Overlaps Detected
|
||||||
|
|
||||||
|
**If you see another Claude working on related tasks:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log coordinate "[your-name]" "
|
||||||
|
@claude-[other-name]: I see you're working on [X].
|
||||||
|
I'm working on [Y] which depends on/relates to your work.
|
||||||
|
|
||||||
|
Suggestion: [how to coordinate]
|
||||||
|
Can we sync on: [specific integration point]?
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log coordinate "claude-frontend" "
|
||||||
|
@claude-api: I see you're deploying the API to api.blackroad.io.
|
||||||
|
I'm building the React frontend that will consume your API.
|
||||||
|
|
||||||
|
Suggestion: Can you log the API endpoint URLs and auth flow when ready?
|
||||||
|
Can we sync on: OAuth2 redirect URLs and CORS settings?
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Memory Check Format
|
||||||
|
|
||||||
|
When you check memory, look for these action types:
|
||||||
|
|
||||||
|
| Action | Meaning | What to Do |
|
||||||
|
|--------|---------|------------|
|
||||||
|
| `announce` | Another Claude started working | Check if work overlaps |
|
||||||
|
| `progress` | Another Claude completed a task | See if you can build on it |
|
||||||
|
| `deployed` | Infrastructure is live | Check if you depend on it |
|
||||||
|
| `decided` | Architecture decision made | Align your work with it |
|
||||||
|
| `configured` | Service configured | Use these settings |
|
||||||
|
| `coordinate` | Claude wants to sync with you | Respond with your status |
|
||||||
|
| `blocked` | Claude is stuck | See if you can help |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚨 Critical Rules
|
||||||
|
|
||||||
|
### DO:
|
||||||
|
✅ **Announce your work** when you start
|
||||||
|
✅ **Check memory every 60 seconds** while working
|
||||||
|
✅ **Update progress** after each task
|
||||||
|
✅ **Coordinate** when you see overlapping work
|
||||||
|
✅ **Log decisions** that affect other Claudes
|
||||||
|
✅ **Share URLs, ports, credentials** (in memory)
|
||||||
|
✅ **Ask for help** if blocked
|
||||||
|
|
||||||
|
### DON'T:
|
||||||
|
❌ **Start working** without announcing
|
||||||
|
❌ **Ignore memory** for more than 60 seconds
|
||||||
|
❌ **Deploy** without checking if another Claude is working on same service
|
||||||
|
❌ **Make decisions** without logging them
|
||||||
|
❌ **Assume** - always check what others are doing
|
||||||
|
❌ **Work in isolation** - we're a team!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Example Session: 3 Claudes Coordinating
|
||||||
|
|
||||||
|
### Claude 1 (API):
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log announce "claude-api" "Working on: API deployment. Tasks: 1. FastAPI setup 2. Database 3. Auth 4. Deploy. Goal: BlackRoad SaaS backend. Checking memory every 60s."
|
||||||
|
|
||||||
|
# ... 2 minutes later ...
|
||||||
|
~/memory-system.sh log progress "claude-api" "✅ FastAPI running on localhost:8000. Next: Database setup"
|
||||||
|
|
||||||
|
# ... checks memory, sees Claude 2 working on frontend ...
|
||||||
|
~/memory-system.sh log coordinate "claude-api" "@claude-frontend: API will be at api.blackroad.io. OAuth redirect: /auth/callback. Need your frontend URL for CORS."
|
||||||
|
```
|
||||||
|
|
||||||
|
### Claude 2 (Frontend):
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log announce "claude-frontend" "Working on: React frontend. Tasks: 1. Auth UI 2. API integration 3. State mgmt 4. Deploy. Goal: BlackRoad SaaS web app. Checking memory every 60s."
|
||||||
|
|
||||||
|
# ... checks memory, sees Claude 1's API endpoint ...
|
||||||
|
~/memory-system.sh log coordinate "claude-frontend" "@claude-api: Frontend will be at app.blackroad.io. Setting CORS origin. OAuth redirect confirmed: /auth/callback"
|
||||||
|
|
||||||
|
# ... 3 minutes later ...
|
||||||
|
~/memory-system.sh log progress "claude-frontend" "✅ Auth UI complete, integrated with api.blackroad.io/auth. Next: Dashboard components"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Claude 3 (Database):
|
||||||
|
```bash
|
||||||
|
~/memory-system.sh log announce "claude-database" "Working on: PostgreSQL setup. Tasks: 1. Schema 2. Migrations 3. Indexes 4. Backup. Goal: BlackRoad SaaS data layer. Checking memory every 60s."
|
||||||
|
|
||||||
|
# ... checks memory, sees Claude 1 needs database ...
|
||||||
|
~/memory-system.sh log coordinate "claude-database" "@claude-api: Database ready at postgres.blackroad.io:5432. Connection string in DM. Schema: users, workspaces, sessions."
|
||||||
|
|
||||||
|
# ... sees Claude 2's progress ...
|
||||||
|
~/memory-system.sh log progress "claude-database" "✅ Schema migrated. Added indexes for user lookup. Next: Connection pooling (pgBouncer)"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Result:** All 3 Claudes work in harmony, no duplicate effort, perfect coordination!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Continuous Coordination Loop
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ 1. Check Memory (every 60s) │
|
||||||
|
│ ↓ │
|
||||||
|
│ 2. See what other Claudes are doing │
|
||||||
|
│ ↓ │
|
||||||
|
│ 3. Adjust your plan if needed │
|
||||||
|
│ ↓ │
|
||||||
|
│ 4. Work on your task │
|
||||||
|
│ ↓ │
|
||||||
|
│ 5. Log your progress │
|
||||||
|
│ ↓ │
|
||||||
|
│ 6. Coordinate if overlaps detected │
|
||||||
|
│ ↓ │
|
||||||
|
│ └──────────────────────── REPEAT ─────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Quick Reference Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start daemon (if not running)
|
||||||
|
~/memory-sync-daemon.sh start
|
||||||
|
|
||||||
|
# Register yourself
|
||||||
|
MY_CLAUDE=$(~/memory-sync-daemon.sh register "claude-[focus]")
|
||||||
|
|
||||||
|
# Announce work
|
||||||
|
~/memory-system.sh log announce "$MY_CLAUDE" "[announcement text]"
|
||||||
|
|
||||||
|
# Check memory (every 60s!)
|
||||||
|
~/memory-realtime-context.sh live $MY_CLAUDE compact
|
||||||
|
|
||||||
|
# Log progress
|
||||||
|
~/memory-system.sh log progress "$MY_CLAUDE" "[progress update]"
|
||||||
|
|
||||||
|
# Coordinate with another Claude
|
||||||
|
~/memory-system.sh log coordinate "$MY_CLAUDE" "@claude-other: [message]"
|
||||||
|
|
||||||
|
# Log decision
|
||||||
|
~/memory-system.sh log decided "[topic]" "[decision and rationale]"
|
||||||
|
|
||||||
|
# Log deployment
|
||||||
|
~/memory-system.sh log deployed "[service]" "[URL, port, details]"
|
||||||
|
|
||||||
|
# Ask for help
|
||||||
|
~/memory-system.sh log blocked "$MY_CLAUDE" "Stuck on: [issue]. Need help with: [specific problem]"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎓 Training Example
|
||||||
|
|
||||||
|
**You are Claude-NewAgent. Follow this protocol:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Step 1: Register
|
||||||
|
MY_CLAUDE=$(~/memory-sync-daemon.sh register "claude-newagent-$(date +%s)")
|
||||||
|
|
||||||
|
# Step 2: Check what's happening
|
||||||
|
~/memory-realtime-context.sh live $MY_CLAUDE compact
|
||||||
|
|
||||||
|
# Step 3: Announce yourself
|
||||||
|
~/memory-system.sh log announce "claude-newagent" "
|
||||||
|
Hey team! I'm here to help. I'm working on: Learning the BlackRoad memory system
|
||||||
|
|
||||||
|
My tasks:
|
||||||
|
1. Read all documentation
|
||||||
|
2. Understand PS-SHA∞ hash chain
|
||||||
|
3. Practice logging actions
|
||||||
|
4. Coordinate with existing Claudes
|
||||||
|
5. Contribute to active projects
|
||||||
|
|
||||||
|
This relates to: Becoming an effective BlackRoad infrastructure agent
|
||||||
|
|
||||||
|
I will check memory every 60 seconds and coordinate with other Claudes.
|
||||||
|
Please let me know if this overlaps with your work!
|
||||||
|
|
||||||
|
Instance: $MY_CLAUDE
|
||||||
|
"
|
||||||
|
|
||||||
|
# Step 4: Set up 60-second check loop
|
||||||
|
while true; do
|
||||||
|
clear
|
||||||
|
echo "=== MEMORY CHECK ($(date +%H:%M:%S)) ==="
|
||||||
|
~/memory-realtime-context.sh live $MY_CLAUDE compact
|
||||||
|
echo ""
|
||||||
|
echo "Press Ctrl+C to stop checking"
|
||||||
|
sleep 60
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏆 Success Metrics
|
||||||
|
|
||||||
|
You're following the protocol correctly if:
|
||||||
|
|
||||||
|
✅ Memory shows your announcement when you start
|
||||||
|
✅ You update progress at least every 5 minutes
|
||||||
|
✅ You've coordinated with at least 1 other Claude
|
||||||
|
✅ No duplicate deployments (you checked first!)
|
||||||
|
✅ All your decisions are logged
|
||||||
|
✅ Other Claudes reference your work
|
||||||
|
✅ You've helped another Claude (responded to coordination request)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Why This Matters
|
||||||
|
|
||||||
|
**Without coordination:**
|
||||||
|
- Claude A deploys API to port 8080
|
||||||
|
- Claude B deploys different API to port 8080 (conflict!)
|
||||||
|
- Claude C builds frontend, doesn't know which API to use
|
||||||
|
- Result: Chaos, wasted effort, broken integrations
|
||||||
|
|
||||||
|
**With coordination:**
|
||||||
|
- Claude A announces: "Deploying API to port 8080"
|
||||||
|
- Claude B sees it: "Great! I'll work on frontend integration"
|
||||||
|
- Claude C sees both: "I'll handle database, here's the connection string"
|
||||||
|
- Result: Perfect teamwork, no conflicts, fast delivery!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 See Also
|
||||||
|
|
||||||
|
- `REALTIME_MEMORY_SYSTEM.md` - Technical architecture
|
||||||
|
- `MEMORY_QUICKSTART.md` - Quick start guide
|
||||||
|
- `memory-system.sh` - Core memory commands
|
||||||
|
- `memory-realtime-context.sh` - Live context streaming
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Remember:**
|
||||||
|
|
||||||
|
> "We're not individual Claudes working alone.
|
||||||
|
> We're a distributed Claude swarm working together.
|
||||||
|
> Memory is how we stay synchronized."
|
||||||
|
|
||||||
|
**Check memory every 60 seconds. Always.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Created:** 2025-12-23
|
||||||
|
**Version:** 1.0.0
|
||||||
|
**Required:** All Claude agents working on BlackRoad infrastructure
|
||||||
323
guides/cluster-guide.md
Normal file
323
guides/cluster-guide.md
Normal file
@@ -0,0 +1,323 @@
|
|||||||
|
# 🖤🛣️ BlackRoad Cluster Management CLI
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
blackroad-cluster list # List all devices
|
||||||
|
bc list # Same using alias
|
||||||
|
```
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
The `blackroad-cluster` command is installed in `~/bin/blackroad-cluster`.
|
||||||
|
|
||||||
|
**Alias:** `bc` is configured as a shortcut for `blackroad-cluster`
|
||||||
|
|
||||||
|
## Device Registry
|
||||||
|
|
||||||
|
| Device | IP | User | Description |
|
||||||
|
|--------|----------|------|-------------|
|
||||||
|
| **octavia** | 192.168.4.81 | pi | Debian 13 (trixie) - Docker orchestration |
|
||||||
|
| **alice** | 192.168.4.49 | alice | Raspbian 11 - Kubernetes cluster |
|
||||||
|
| **lucidia** | 192.168.4.38 | pi | Debian 12 - Tailscale VPN hub |
|
||||||
|
| **aria** | 192.168.4.82 | pi | Debian 12 - Docker services |
|
||||||
|
| **shellfish** | 174.138.44.45 | root | CentOS 9 - DigitalOcean cloud |
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
### Basic Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List all devices
|
||||||
|
blackroad-cluster list
|
||||||
|
bc ls
|
||||||
|
|
||||||
|
# Show status of all devices (with uptime, load)
|
||||||
|
blackroad-cluster status
|
||||||
|
bc stat
|
||||||
|
|
||||||
|
# Show version
|
||||||
|
blackroad-cluster version
|
||||||
|
bc version
|
||||||
|
```
|
||||||
|
|
||||||
|
### SSH Access
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# SSH into a device
|
||||||
|
blackroad-cluster ssh octavia
|
||||||
|
bc ssh alice
|
||||||
|
|
||||||
|
# Quick access
|
||||||
|
bc ssh lucidia
|
||||||
|
bc ssh aria
|
||||||
|
bc ssh shellfish
|
||||||
|
```
|
||||||
|
|
||||||
|
### Execute Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run command on single device
|
||||||
|
blackroad-cluster exec octavia "docker ps"
|
||||||
|
bc exec alice "uptime"
|
||||||
|
|
||||||
|
# Run command on ALL devices
|
||||||
|
blackroad-cluster all "hostname"
|
||||||
|
bc all "df -h /"
|
||||||
|
bc all "docker ps -q | wc -l"
|
||||||
|
|
||||||
|
# Complex commands
|
||||||
|
bc exec lucidia "systemctl status tailscaled"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Device Information
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Get detailed info about device
|
||||||
|
blackroad-cluster info octavia
|
||||||
|
bc info alice
|
||||||
|
|
||||||
|
# Shows:
|
||||||
|
# - System information
|
||||||
|
# - Network configuration
|
||||||
|
# - System resources
|
||||||
|
# - Disk usage
|
||||||
|
# - Docker containers
|
||||||
|
```
|
||||||
|
|
||||||
|
### Network Testing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ping single device
|
||||||
|
blackroad-cluster ping octavia
|
||||||
|
bc ping lucidia
|
||||||
|
|
||||||
|
# Ping all devices
|
||||||
|
blackroad-cluster ping
|
||||||
|
bc ping
|
||||||
|
```
|
||||||
|
|
||||||
|
### SSH Tunnels
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create tunnel (local:remote)
|
||||||
|
blackroad-cluster tunnel octavia 8080 80
|
||||||
|
bc tunnel lucidia 3000 3000
|
||||||
|
|
||||||
|
# Access via localhost:8080
|
||||||
|
# Press Ctrl+C to close tunnel
|
||||||
|
```
|
||||||
|
|
||||||
|
### Monitoring
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Live monitoring dashboard (refreshes every 5s)
|
||||||
|
blackroad-cluster monitor
|
||||||
|
bc monitor
|
||||||
|
|
||||||
|
# Shows real-time:
|
||||||
|
# - Device status
|
||||||
|
# - Uptime
|
||||||
|
# - Load average
|
||||||
|
# - Last updated timestamp
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Workflows
|
||||||
|
|
||||||
|
### Check Cluster Health
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Quick health check
|
||||||
|
bc ping # Test connectivity
|
||||||
|
bc status # Full status with uptime/load
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deploy to All Devices
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Update all systems
|
||||||
|
bc all "sudo apt update"
|
||||||
|
|
||||||
|
# Check Docker on all
|
||||||
|
bc all "docker --version"
|
||||||
|
|
||||||
|
# Restart service on all
|
||||||
|
bc all "sudo systemctl restart docker"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Investigate Issues
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check logs
|
||||||
|
bc exec octavia "journalctl -u docker -n 50"
|
||||||
|
|
||||||
|
# Check disk space
|
||||||
|
bc all "df -h / | tail -1"
|
||||||
|
|
||||||
|
# Check running containers
|
||||||
|
bc all "docker ps --format 'table {{.Names}}\t{{.Status}}'"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Development Workflow
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Open tunnel to dev server
|
||||||
|
bc tunnel alice 3000 3000
|
||||||
|
|
||||||
|
# Check git status on device
|
||||||
|
bc exec alice "cd ~/project && git status"
|
||||||
|
|
||||||
|
# Deploy and test
|
||||||
|
bc exec octavia "cd ~/app && docker-compose up -d"
|
||||||
|
bc ssh octavia # SSH in to debug
|
||||||
|
```
|
||||||
|
|
||||||
|
## Advanced Usage
|
||||||
|
|
||||||
|
### Custom SSH Options
|
||||||
|
|
||||||
|
The script uses `ConnectTimeout=5` by default. To customize, edit:
|
||||||
|
- `~/bin/blackroad-cluster`
|
||||||
|
- Search for `ssh -o ConnectTimeout=5`
|
||||||
|
|
||||||
|
### Adding New Devices
|
||||||
|
|
||||||
|
Edit `~/bin/blackroad-cluster`:
|
||||||
|
|
||||||
|
```zsh
|
||||||
|
# Add to DEVICES array
|
||||||
|
DEVICES=(
|
||||||
|
# ... existing devices ...
|
||||||
|
newdevice "192.168.4.XX"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Add description
|
||||||
|
DEVICE_DESC=(
|
||||||
|
# ... existing descriptions ...
|
||||||
|
newdevice "Description of new device"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Add user
|
||||||
|
DEVICE_USERS=(
|
||||||
|
# ... existing users ...
|
||||||
|
newdevice "username"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Then update the device list in `list_devices()`, `show_status()`, `exec_all()`, etc.
|
||||||
|
|
||||||
|
### Integration with Other Tools
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Use in scripts
|
||||||
|
for device in octavia alice lucidia; do
|
||||||
|
bc exec $device "echo \$device: \$(hostname)"
|
||||||
|
done
|
||||||
|
|
||||||
|
# Export data
|
||||||
|
bc status > cluster-status.txt
|
||||||
|
|
||||||
|
# Pipe commands
|
||||||
|
bc list | grep octavia
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### SSH Connection Issues
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test direct SSH
|
||||||
|
ssh pi@192.168.4.81
|
||||||
|
|
||||||
|
# Check SSH keys
|
||||||
|
ls -la ~/.ssh/*.pub
|
||||||
|
|
||||||
|
# Verify device is online
|
||||||
|
bc ping octavia
|
||||||
|
```
|
||||||
|
|
||||||
|
### Permission Denied
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ensure SSH keys are set up
|
||||||
|
ssh-copy-id pi@192.168.4.81
|
||||||
|
ssh-copy-id alice@192.168.4.49
|
||||||
|
ssh-copy-id pi@192.168.4.38
|
||||||
|
ssh-copy-id pi@192.168.4.82
|
||||||
|
ssh-copy-id root@174.138.44.45
|
||||||
|
```
|
||||||
|
|
||||||
|
### Command Timeout
|
||||||
|
|
||||||
|
The default timeout is 5 seconds. For slow connections, edit the script:
|
||||||
|
|
||||||
|
```zsh
|
||||||
|
# Change ConnectTimeout value
|
||||||
|
ssh -o ConnectTimeout=10 ...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tips & Tricks
|
||||||
|
|
||||||
|
### Alias Examples
|
||||||
|
|
||||||
|
Add to `~/.zshrc`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
alias bcs='blackroad-cluster ssh'
|
||||||
|
alias bce='blackroad-cluster exec'
|
||||||
|
alias bca='blackroad-cluster all'
|
||||||
|
alias bcm='blackroad-cluster monitor'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Watch Mode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Monitor in real-time
|
||||||
|
watch -n 2 "blackroad-cluster status"
|
||||||
|
|
||||||
|
# Or use built-in monitor
|
||||||
|
bc monitor
|
||||||
|
```
|
||||||
|
|
||||||
|
### Batch Operations
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Restart all Docker services
|
||||||
|
bc all "sudo systemctl restart docker"
|
||||||
|
|
||||||
|
# Update all systems (be careful!)
|
||||||
|
bc all "sudo apt update && sudo apt upgrade -y"
|
||||||
|
|
||||||
|
# Collect logs
|
||||||
|
bc all "journalctl -u docker --since '1 hour ago' > /tmp/docker.log"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Color Scheme
|
||||||
|
|
||||||
|
BlackRoad brand colors used:
|
||||||
|
- **Amber** (#F5A623): Device names
|
||||||
|
- **Hot Pink** (#FF1D6C): Headers/banners
|
||||||
|
- **Electric Blue** (#2979FF): Section titles
|
||||||
|
- **Cyan**: Labels
|
||||||
|
- **Green**: Online status/IPs
|
||||||
|
- **Red**: Errors/offline status
|
||||||
|
- **Yellow**: Warnings/users
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
- **v1.0.0** (2026-01-10): Initial release
|
||||||
|
- 5 devices registered
|
||||||
|
- 11 commands available
|
||||||
|
- Full monitoring capabilities
|
||||||
|
- SSH tunnel support
|
||||||
|
- Batch execution across all devices
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
For issues or feature requests:
|
||||||
|
- Email: blackroad.systems@gmail.com
|
||||||
|
- GitHub: BlackRoad-OS organization
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**🖤 BlackRoad OS Infrastructure 🛣️**
|
||||||
474
guides/hardware-inventory.md
Normal file
474
guides/hardware-inventory.md
Normal file
@@ -0,0 +1,474 @@
|
|||||||
|
# BlackRoad Hardware Inventory - Complete Build
|
||||||
|
**Updated:** 2026-02-11
|
||||||
|
**Total Investment:** ~$3,500+ in new hardware
|
||||||
|
**Status:** Ready for integration
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 MASTER SYSTEM ARCHITECTURE
|
||||||
|
|
||||||
|
### The Constellation Workstation Design
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────────────────────────┐
|
||||||
|
│ BLACKROAD WORKSTATION │
|
||||||
|
├──────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ LEFT CENTER RIGHT │
|
||||||
|
│ ┌───────┐ ┌──────────┐ ┌───────┐ │
|
||||||
|
│ │ 4" │ │ 10.1" │ │ 7" │ │
|
||||||
|
│ │ HOLO │ │ AGENT │ │ SIM │ │
|
||||||
|
│ │ Pi-5 │ │ JETSON │ │ Pi-0W │ │
|
||||||
|
│ └───▲───┘ └────▲─────┘ └───▲───┘ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ [Pyramid] [Touch UI] [Output] │
|
||||||
|
│ │
|
||||||
|
│ ┌────────────────┐ │
|
||||||
|
│ │ 9.3" OPS │ │
|
||||||
|
│ │ Pi-5 #2 │ ◄─── MQTT BROKER │
|
||||||
|
│ └────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────────┐ │
|
||||||
|
│ │ Pi-400 KEYBOARD (Admin/KVM) │ │
|
||||||
|
│ └──────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└──────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💻 COMPUTING NODES
|
||||||
|
|
||||||
|
### 🎯 CRITICAL DISCOVERY: LUCIDIA IS ALREADY THE BRAIN!
|
||||||
|
|
||||||
|
**Lucidia (192.168.4.81) is already running:**
|
||||||
|
- ✅ NATS event bus (port 4222)
|
||||||
|
- ✅ Ollama LLM server (port 11434)
|
||||||
|
- ✅ Edge agent
|
||||||
|
|
||||||
|
**This means:**
|
||||||
|
- ❌ Don't need MacBook #2 for LLM inference
|
||||||
|
- ✅ Use Lucidia as the orchestration brain
|
||||||
|
- ✅ MacBooks become monitoring/dev stations only
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💻 COMPUTING NODES
|
||||||
|
|
||||||
|
### Current Production Cluster (Already Running ✅)
|
||||||
|
| Node | Hardware | IP | Role | Status | Details |
|
||||||
|
|------|----------|-----|------|--------|---------|
|
||||||
|
| **alice** | Raspberry Pi 400 (4GB) | 192.168.4.49 | Auth + Billing | ✅ Online | 7 containers, 93% disk full |
|
||||||
|
| **lucidia** | Raspberry Pi 5 (8GB) | 192.168.4.81 | NATS + Ollama Brain | ✅ Online | Already has event bus + LLM! |
|
||||||
|
| **octavia** | Raspberry Pi 5 (8GB) | 192.168.4.38 | Heavy Storage | ✅ Online (29d) | 235GB card, 90% full - needs cleanup |
|
||||||
|
| **aria** | Raspberry Pi 5 (8GB) | 192.168.4.82 | Web Services | ✅ Online (4wk!) | 9 containers, rock solid |
|
||||||
|
|
||||||
|
### New Constellation Boards (Ready to Deploy!)
|
||||||
|
| Node | Hardware | Purpose | Display | Status |
|
||||||
|
|------|----------|---------|---------|--------|
|
||||||
|
| **Pi-Holo** | Raspberry Pi 5 8GB (NEW) | Hologram Renderer | 4" 720×720 | 🆕 Flash today |
|
||||||
|
| **Pi-Ops** | Raspberry Pi 5 8GB (NEW) | MQTT Broker + Monitor | 9.3" 1600×600 | 🆕 Flash today |
|
||||||
|
| **Pi-Zero-Sim** | Raspberry Pi Zero W | Lightweight Sim Output | 7" 1024×600 | ✅ Ready |
|
||||||
|
| **Jetson-Agent** | Jetson Orin Nano | Agent UI | 10.1" Touch | ⏳ Waiting for display |
|
||||||
|
|
||||||
|
### Development Machines
|
||||||
|
| Device | Model | Role | Status |
|
||||||
|
|--------|-------|------|--------|
|
||||||
|
| **lucidia-operator** | MacBook Pro M1 8GB | Primary Dev | ✅ Current |
|
||||||
|
| **MacBook #1** | ~2014 Intel | Monitoring Station | Ready |
|
||||||
|
| **MacBook #2** | ~2014 Intel | Agent Orchestrator | Ready |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🖥️ DISPLAYS & INPUT
|
||||||
|
|
||||||
|
### Purchased Displays
|
||||||
|
| Size | Resolution | Model | Assigned To | Purpose |
|
||||||
|
|------|-----------|-------|-------------|---------|
|
||||||
|
| 10.1" | 1024×600 | ROADOM Touch IPS | Jetson | Agent UI (touch) |
|
||||||
|
| 9.3" | 1600×600 | Waveshare Ultrawide | Pi-Ops / Pi-400 | Ops Panel (shared via switch) |
|
||||||
|
| 7" | 1024×600 | Waveshare Touch | Pi Zero W | Sim Output |
|
||||||
|
| 4" | 720×720 | Waveshare Square | Pi-Holo | Hologram (under pyramid) |
|
||||||
|
| 2.8" | 240×320 | ESP32 Touch TFT | ESP32 | Standalone Sensor Display |
|
||||||
|
|
||||||
|
**Total Screens:** 5 dedicated + 2 shareable
|
||||||
|
|
||||||
|
### Input Devices
|
||||||
|
- **Apple Magic Keyboard** ($98.50) - Bluetooth to Jetson/Macs
|
||||||
|
- **Apple Magic Mouse** ($79.99) - Primary pointer
|
||||||
|
- **Logitech H390 USB Headset** ($28.84) - Voice I/O for agents
|
||||||
|
- **Pi 400 Keyboard** ($119) - Built-in admin console
|
||||||
|
|
||||||
|
### Video Signal Routing
|
||||||
|
- **UGREEN HDMI Switch 5-in-1** - Share 9.3" between Pi-Ops & Pi-400
|
||||||
|
- **WAVLINK HDMI Splitter** - Clone Pi-Holo to second display (optional)
|
||||||
|
- **WARRKY USB-C to HDMI Cables** (2-pack) - Mac→Display
|
||||||
|
- **JSAUX Micro HDMI Adapters** - Pi→Display
|
||||||
|
- **8K Right-Angle Micro HDMI** - Tight spaces (Pi-Holo)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧠 AI ACCELERATORS
|
||||||
|
|
||||||
|
### Hailo-8 M.2 Module ($214.99)
|
||||||
|
- **26 TOPS AI Performance**
|
||||||
|
- Compatible with Raspberry Pi 5
|
||||||
|
- Linux/Windows support
|
||||||
|
- **Install on:** octavia OR new Pi-5 dedicated AI node
|
||||||
|
|
||||||
|
### Jetson Orin Nano ($114.29 base)
|
||||||
|
- **GPU-accelerated AI**
|
||||||
|
- Runs full LLMs
|
||||||
|
- Agent UI workstation
|
||||||
|
- Real-time inference
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔌 POWER & COOLING
|
||||||
|
|
||||||
|
### Power Supplies
|
||||||
|
| Device | PSU | Qty | Notes |
|
||||||
|
|--------|-----|-----|-------|
|
||||||
|
| Pi 5 | Geekworm 27W 5V/5A USB-C | 2 | Pi-Holo, Pi-Ops |
|
||||||
|
| Pi 5 (future) | Same | 1 | For Pironman build |
|
||||||
|
| Pi Zero | 5V/2A Micro USB | 1 | Pi-Zero-Sim |
|
||||||
|
| Pi 400 | 5V/3A USB-C | 1 | Built-in keyboard |
|
||||||
|
| Jetson | Barrel jack PSU | 1 | Comes with dev kit |
|
||||||
|
| Displays | Various 5V wall adapters | 5 | Don't draw from Pi USB! |
|
||||||
|
| ESP32 | DC 5V/4A | 2 | For projects |
|
||||||
|
|
||||||
|
### Cooling Solutions
|
||||||
|
- **GeeekPi Active Cooler RGB** ($9.99) - For Pi-Holo
|
||||||
|
- **ElectroCookie Radial Tower** ($13.99) - For Pi-Ops
|
||||||
|
- **Pironman 5-MAX Case** (ordered) - Dual fans + tower cooler
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💾 STORAGE
|
||||||
|
|
||||||
|
### SSDs
|
||||||
|
| Drive | Capacity | Interface | Purpose |
|
||||||
|
|-------|----------|-----------|---------|
|
||||||
|
| Crucial P310 | 1TB | NVMe M.2 | For Pironman Pi-5 (ordered) |
|
||||||
|
| External SSD | ? | USB 3.0 | Jetson workspace OR Pi-Ops logs |
|
||||||
|
|
||||||
|
### SD Cards & Readers
|
||||||
|
- **Samsung EVO Select 256GB** - Main OS cards
|
||||||
|
- **Anker USB 3.0 SD Reader** (2x) - Flashing stations
|
||||||
|
- **Apple USB-C SD Reader** ($45) - Mac workflows
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌐 NETWORKING
|
||||||
|
|
||||||
|
### Current Network
|
||||||
|
- **Router:** TP-Link (192.168.4.1)
|
||||||
|
- **Switch:** TP-Link TL-SG105 (5-port gigabit)
|
||||||
|
- **WiFi Card:** TP-Link AX3000 PCIe WiFi 6
|
||||||
|
|
||||||
|
### Network Topology
|
||||||
|
```
|
||||||
|
[Router/WiFi]
|
||||||
|
|
|
||||||
|
[TP-Link Switch]
|
||||||
|
/ | | \
|
||||||
|
Jetson Pi5 Pi5 Pi400
|
||||||
|
Holo Ops
|
||||||
|
|
||||||
|
[WiFi] ← Pi Zero W
|
||||||
|
```
|
||||||
|
|
||||||
|
### VPN Mesh (Tailscale)
|
||||||
|
- alice: 100.77.210.18
|
||||||
|
- lucidia: 100.66.235.47
|
||||||
|
- octavia: Already in mesh
|
||||||
|
- aria: 100.109.14.17
|
||||||
|
- **TODO:** Add new constellation nodes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ DEVELOPMENT KITS & COMPONENTS
|
||||||
|
|
||||||
|
### Microcontrollers
|
||||||
|
| Item | Purpose | Notes |
|
||||||
|
|------|---------|-------|
|
||||||
|
| **ELEGOO UNO R3 Starter Kit** (200+ components) | Arduino projects | Full sensor suite |
|
||||||
|
| **ELEGOO UNO R3 Super Kit** | Advanced projects | LCD, motors, relays |
|
||||||
|
| **ESP32 2.8" Touch TFT** | Standalone displays | WiFi + BT + screen |
|
||||||
|
| **Freenove Ultimate Kit** | Pi learning | 962-page tutorial, 128 projects |
|
||||||
|
|
||||||
|
### Electronics Components
|
||||||
|
- **BOJACK Breadboard Jumper Kit** (840 pcs) - All lengths
|
||||||
|
- **HiLetgo Logic Level Converters** (10x 4-ch) - 3.3V↔5V
|
||||||
|
- **Relay Modules** (2-channel 12V) - Switching
|
||||||
|
- **BTF-LIGHTING WS2812B LED Strip** (5m, 300 LEDs) - Addressable RGB
|
||||||
|
|
||||||
|
### Sensors (from ELEGOO kits)
|
||||||
|
- DHT11 Temperature/Humidity
|
||||||
|
- Ultrasonic sensors
|
||||||
|
- IR receivers
|
||||||
|
- PIR motion
|
||||||
|
- Photoresistors
|
||||||
|
- Tilt switches
|
||||||
|
- Joystick modules
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 HOLOGRAM BUILD MATERIALS
|
||||||
|
|
||||||
|
### Optics
|
||||||
|
- **50x 4" Square Glass Mirrors** ($21.38) - Pepper's Ghost reflectors
|
||||||
|
- **5x 6" Beveled Glass Mirrors** ($11.88) - Pyramid faces
|
||||||
|
- **100x Bamboo Sticks** (15.7") - Frame structure
|
||||||
|
- **Glass Cutter** - Custom sizing
|
||||||
|
- **RTV Silicone Sealant** (2-pack) - Assembly
|
||||||
|
|
||||||
|
### Display Bases
|
||||||
|
- **LED Light Bases** (multicolor) - Under hologram
|
||||||
|
- **Acrylic Cube Risers** (3", 4", 5") - Display stands
|
||||||
|
- **Clisela Display Stands** - Presentation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 TOOLS & WORKSPACE
|
||||||
|
|
||||||
|
### Soldering Station
|
||||||
|
- **Soldering Iron Premium Kit** (60W, adjustable temp)
|
||||||
|
- **KOTTO Helping Hands** (4-arm magnetic)
|
||||||
|
- **SainSmart Helping Station** (5X LED magnifier)
|
||||||
|
- **Heat-Resistant Silicone Mat** (17.7" × 11.8")
|
||||||
|
- **Solder Smoke Absorber** - Fume extraction
|
||||||
|
- **Gikfun SMD Practice Board** - Skill training
|
||||||
|
|
||||||
|
### Organization
|
||||||
|
- **Akro-Mils 16-Drawer Cabinet** - Component storage
|
||||||
|
- **YHYZ Precision Tweezers** (7-pc ESD set)
|
||||||
|
- **Hebayy Breaker Panel Labels** - Cable management
|
||||||
|
|
||||||
|
### Power Distribution
|
||||||
|
- **Anker Power Banks** (10,000mAh 30W) - Portable power
|
||||||
|
- **TobenONE 15-in-1 USB-C Dock** ($129.99) - Hub for Jetson/Macs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📷 SENSORS & I/O
|
||||||
|
|
||||||
|
### Cameras
|
||||||
|
- **Pi Camera Module V2** (8MP, 1080p) - CSI on Pi-Holo for tracking
|
||||||
|
- (Universal camera mount for hologram input)
|
||||||
|
|
||||||
|
### Connectivity Modules
|
||||||
|
- **ELEGOO OLED Displays** (0.96" × 3) - Status screens
|
||||||
|
- **ELEGOO 2.8" TFT Touch** - Arduino UI
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏗️ BUILD PHASES
|
||||||
|
|
||||||
|
### Phase 1: Foundation (Current Week)
|
||||||
|
**Hardware READY NOW:**
|
||||||
|
- ✅ 4x Production Pis (alice, lucidia, octavia, aria) - Running
|
||||||
|
- ✅ 2x Raspberry Pi 5 8GB - **Can deploy immediately!**
|
||||||
|
- ✅ Jetson Orin Nano dev kit
|
||||||
|
- ✅ Pi Zero W
|
||||||
|
- ✅ Pi 400 keyboard
|
||||||
|
- ✅ M1 MacBook Pro
|
||||||
|
- ✅ Old MacBooks (2x)
|
||||||
|
- ✅ iPad Pro 2015
|
||||||
|
- ✅ ESP32 touchscreen (2.8")
|
||||||
|
- ✅ Arduino kits (ELEGOO x2, Freenove)
|
||||||
|
- ✅ 4" Waveshare 720×720 display
|
||||||
|
- ✅ 7" Waveshare touch display
|
||||||
|
- ✅ 9.3" Waveshare ultrawide
|
||||||
|
- ✅ Hailo-8 M.2 AI accelerator
|
||||||
|
- ✅ All electronics components
|
||||||
|
- ✅ Soldering station
|
||||||
|
- ✅ TP-Link switch
|
||||||
|
- ✅ UGREEN HDMI switch
|
||||||
|
- ✅ WAVLINK HDMI splitter
|
||||||
|
- ✅ All cables & adapters
|
||||||
|
- ✅ Glass mirrors & hologram materials
|
||||||
|
|
||||||
|
**Tasks (Can Start TODAY!):**
|
||||||
|
1. Flash 2x Pi 5s (Pi-Holo + Pi-Ops)
|
||||||
|
2. Wire constellation displays
|
||||||
|
3. Deploy MQTT broker on Pi-Ops
|
||||||
|
4. Set up Jetson with existing hardware
|
||||||
|
5. Build hologram pyramid
|
||||||
|
6. Install Tailscale on M1 Mac
|
||||||
|
7. Configure Arduino sensors
|
||||||
|
|
||||||
|
### Phase 2: Enhanced Build (When parts arrive)
|
||||||
|
**INCOMING (Ordered but not yet arrived):**
|
||||||
|
- Pironman 5-MAX case with dual fans
|
||||||
|
- Crucial 1TB NVMe M.2 SSD
|
||||||
|
- Third Pi 5 8GB (for Pironman build)
|
||||||
|
- 10.1" ROADOM touchscreen (2x total)
|
||||||
|
- Geekworm 27W USB-C PSU
|
||||||
|
- Terminator M (?)
|
||||||
|
|
||||||
|
**Tasks (When they arrive):**
|
||||||
|
1. Build Pironman Pi 5 with NVMe + Hailo-8
|
||||||
|
2. Add second 10.1" display (if needed)
|
||||||
|
3. Upgrade constellation with premium case
|
||||||
|
4. RAID storage options
|
||||||
|
|
||||||
|
### Phase 3: Integration (Week 3-4)
|
||||||
|
1. Network all constellation nodes
|
||||||
|
2. Deploy agent UI on Jetson
|
||||||
|
3. Build hologram pyramid
|
||||||
|
4. Wire Arduino sensors to Pi-Ops
|
||||||
|
5. Create web dashboards
|
||||||
|
6. Test MQTT pub/sub flows
|
||||||
|
|
||||||
|
### Phase 4: Production (Month 2)
|
||||||
|
1. Deploy agent coordination system
|
||||||
|
2. Set up PS-SHA∞ memory persistence
|
||||||
|
3. Build NATS event bus
|
||||||
|
4. Create capability registry
|
||||||
|
5. Polish all UIs
|
||||||
|
6. Documentation & runbooks
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💰 TOTAL INVESTMENT BREAKDOWN
|
||||||
|
|
||||||
|
### Computing (~$800)
|
||||||
|
- Pi 5 8GB (3x): ~$270
|
||||||
|
- Jetson Orin Nano: $114
|
||||||
|
- Pi Zero W kit: $35
|
||||||
|
- Pi 400 kit: $119
|
||||||
|
- Hailo-8 accelerator: $215
|
||||||
|
|
||||||
|
### Displays (~$350)
|
||||||
|
- 10.1" touchscreen (2x): $170
|
||||||
|
- 9.3" ultrawide: $120
|
||||||
|
- 7" touch: $48
|
||||||
|
- 4" square: $75
|
||||||
|
- ESP32 touch: $20
|
||||||
|
|
||||||
|
### Storage & Power (~$200)
|
||||||
|
- Crucial 1TB NVMe: included in Pironman
|
||||||
|
- Pironman case: (ordered)
|
||||||
|
- PSUs & power banks: ~$150
|
||||||
|
|
||||||
|
### Development Kits (~$450)
|
||||||
|
- ELEGOO kits (3x): ~$160
|
||||||
|
- Freenove kit: $50
|
||||||
|
- ESP32 modules: ~$20
|
||||||
|
- Sensors & components: ~$100
|
||||||
|
- Soldering station: ~$120
|
||||||
|
|
||||||
|
### Networking & I/O (~$200)
|
||||||
|
- Switch, cables, adapters
|
||||||
|
- Docking stations
|
||||||
|
- Camera modules
|
||||||
|
|
||||||
|
### Materials & Tools (~$150)
|
||||||
|
- Glass mirrors & cutters
|
||||||
|
- Hologram build materials
|
||||||
|
- Organization & workspace
|
||||||
|
|
||||||
|
### Apple Accessories (~$300)
|
||||||
|
- Magic Keyboard: $98
|
||||||
|
- Magic Mouse: $80
|
||||||
|
- iPad accessories: ~$120
|
||||||
|
|
||||||
|
**GRAND TOTAL: ~$2,450 (not counting existing gear)**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 KILLER FEATURES ENABLED
|
||||||
|
|
||||||
|
### With This Setup You Can:
|
||||||
|
1. **Run 1000+ agents** coordinated via MQTT
|
||||||
|
2. **Display holograms** with Pepper's Ghost optics
|
||||||
|
3. **Touch-based agent UI** on Jetson
|
||||||
|
4. **Real-time monitoring** across 5 displays
|
||||||
|
5. **AI inference** with Hailo-8 + Jetson GPU
|
||||||
|
6. **Sensor integration** via Arduino → MQTT
|
||||||
|
7. **Persistent memory** with PS-SHA∞
|
||||||
|
8. **Remote access** via Tailscale mesh
|
||||||
|
9. **Development** on M1 Mac + SSH to all nodes
|
||||||
|
10. **Learning/experiments** with comprehensive kits
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 IMMEDIATE NEXT STEPS
|
||||||
|
|
||||||
|
### This Week (Hardware Present)
|
||||||
|
```bash
|
||||||
|
# 1. Organize workspace
|
||||||
|
# 2. Install Tailscale
|
||||||
|
brew install tailscale
|
||||||
|
sudo tailscale up
|
||||||
|
|
||||||
|
# 3. Test soldering station
|
||||||
|
# 4. Sort components into drawers
|
||||||
|
# 5. Prep SD cards for new Pis
|
||||||
|
# 6. Flash test OS on spare SD
|
||||||
|
```
|
||||||
|
|
||||||
|
### When Parts Arrive
|
||||||
|
1. Unbox & inventory
|
||||||
|
2. Build Pironman Pi 5
|
||||||
|
3. Flash all new boards
|
||||||
|
4. Wire constellation
|
||||||
|
5. Deploy MQTT broker
|
||||||
|
6. Test hologram display
|
||||||
|
|
||||||
|
### First Integration Test
|
||||||
|
```bash
|
||||||
|
# On Pi-Ops (when ready):
|
||||||
|
sudo apt install mosquitto mosquitto-clients
|
||||||
|
sudo systemctl enable mosquitto
|
||||||
|
mosquitto_pub -t "test/hello" -m "BlackRoad Online"
|
||||||
|
|
||||||
|
# On Jetson:
|
||||||
|
mosquitto_sub -h pi-ops.local -t "test/#"
|
||||||
|
|
||||||
|
# Confirm: Message received!
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎓 LEARNING PATH
|
||||||
|
|
||||||
|
Perfect for Maggie's Dad:
|
||||||
|
1. **Week 1:** Arduino basics (ELEGOO starter kit)
|
||||||
|
2. **Week 2:** Soldering practice (SMD board)
|
||||||
|
3. **Week 3:** Pi basics (Freenove kit)
|
||||||
|
4. **Week 4:** ESP32 projects (touchscreen display)
|
||||||
|
5. **Week 5:** Sensors → MQTT → web dashboard
|
||||||
|
6. **Week 6:** Build your own hologram display
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔒 SECURITY NOTES
|
||||||
|
|
||||||
|
### Network Segmentation
|
||||||
|
- Production Pis (alice, lucidia, octavia, aria) on main LAN
|
||||||
|
- Constellation workstation on main LAN
|
||||||
|
- Old MacBooks on guest WiFi (if security concerns)
|
||||||
|
- Tailscale for secure remote access
|
||||||
|
|
||||||
|
### Access Control
|
||||||
|
- SSH keys only (no passwords)
|
||||||
|
- Firewall rules on router
|
||||||
|
- MQTT ACLs for topic permissions
|
||||||
|
- Regular security updates
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 DOCUMENTATION TO CREATE
|
||||||
|
|
||||||
|
1. **Wiring Diagram** - Full constellation map
|
||||||
|
2. **MQTT Topic Schema** - All pub/sub topics
|
||||||
|
3. **Setup Runbooks** - Step-by-step for each node
|
||||||
|
4. **Troubleshooting Guide** - Common issues
|
||||||
|
5. **Component Inventory** - Drawer-by-drawer list
|
||||||
|
6. **Safety Guidelines** - Soldering, power, handling
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Ready to wire the constellation? Start with Phase 1 tasks!** 🚀
|
||||||
177
roadmap/product-orchestration.md
Normal file
177
roadmap/product-orchestration.md
Normal file
@@ -0,0 +1,177 @@
|
|||||||
|
# BlackRoad Product Orchestration Plan
|
||||||
|
|
||||||
|
**Goal:** Build 20+ enterprise products in parallel using all Claude instances
|
||||||
|
|
||||||
|
**Revenue Target:** $14.4M/year ($1.2M/month)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 TIER 1 PRODUCTS (Build First - 17 Products)
|
||||||
|
|
||||||
|
### AI Platform (8 Products) - $5M+/year
|
||||||
|
- [ ] BlackRoad vLLM ⚡ URGENT
|
||||||
|
- [ ] BlackRoad LocalAI ⚡ URGENT
|
||||||
|
- [ ] BlackRoad LangChain
|
||||||
|
- [ ] BlackRoad CrewAI
|
||||||
|
- [ ] BlackRoad Haystack
|
||||||
|
- [ ] BlackRoad Weaviate
|
||||||
|
- [ ] BlackRoad Qdrant
|
||||||
|
- [ ] BlackRoad Meilisearch
|
||||||
|
|
||||||
|
### Identity & Access (5 Products) - $3M+/year
|
||||||
|
- [ ] BlackRoad Keycloak ⚡ URGENT
|
||||||
|
- [ ] BlackRoad Authelia
|
||||||
|
- [ ] BlackRoad Headscale
|
||||||
|
- [ ] BlackRoad Nebula
|
||||||
|
- [ ] BlackRoad Netbird
|
||||||
|
|
||||||
|
### Cloud Storage (2 Products) - $2M+/year
|
||||||
|
- [ ] BlackRoad MinIO
|
||||||
|
- [ ] BlackRoad Ceph
|
||||||
|
|
||||||
|
### Collaboration (2 Products) - $2M+/year
|
||||||
|
- [ ] BlackRoad Meet
|
||||||
|
- [ ] BlackRoad BigBlueButton
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏗️ INFRASTRUCTURE COMPONENTS
|
||||||
|
|
||||||
|
### Core Services
|
||||||
|
- [ ] Unified API Gateway (auth, routing, rate limiting)
|
||||||
|
- [ ] Billing System (Stripe integration, subscriptions)
|
||||||
|
- [ ] Admin Portal (user mgmt, analytics, support)
|
||||||
|
- [ ] Analytics Platform (usage tracking, metrics)
|
||||||
|
- [ ] Authentication Service (SSO, SAML, OAuth)
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- [ ] React Component Library (BlackRoad Design System)
|
||||||
|
- [ ] Product Catalog Website
|
||||||
|
- [ ] Documentation Portal
|
||||||
|
- [ ] Customer Portal
|
||||||
|
|
||||||
|
### Mobile
|
||||||
|
- [ ] React Native Framework
|
||||||
|
- [ ] iOS Apps (per product)
|
||||||
|
- [ ] Android Apps (per product)
|
||||||
|
|
||||||
|
### DevOps
|
||||||
|
- [ ] CI/CD Pipeline (GitHub Actions)
|
||||||
|
- [ ] Monitoring (Prometheus + Grafana)
|
||||||
|
- [ ] Logging (ELK Stack)
|
||||||
|
- [ ] Deployment Automation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📅 TIMELINE
|
||||||
|
|
||||||
|
### Week 1-2: Foundation
|
||||||
|
- ✅ Enhancement framework built
|
||||||
|
- ✅ All products enhanced (UI, docs, deployment)
|
||||||
|
- [ ] Infrastructure components designed
|
||||||
|
- [ ] First MVP started (BlackRoad vLLM)
|
||||||
|
|
||||||
|
### Week 3-4: MVP Launch
|
||||||
|
- [ ] BlackRoad vLLM MVP complete
|
||||||
|
- [ ] Private beta (10 customers)
|
||||||
|
- [ ] Billing system live
|
||||||
|
- [ ] Admin portal v1
|
||||||
|
|
||||||
|
### Week 5-8: Scale
|
||||||
|
- [ ] 3 more products launched
|
||||||
|
- [ ] 100 paying customers
|
||||||
|
- [ ] $10K MRR
|
||||||
|
- [ ] Mobile apps v1
|
||||||
|
|
||||||
|
### Week 9-12: Expand
|
||||||
|
- [ ] 10 products live
|
||||||
|
- [ ] 500 paying customers
|
||||||
|
- [ ] $50K MRR
|
||||||
|
- [ ] Enterprise contracts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤖 CLAUDE COORDINATION
|
||||||
|
|
||||||
|
### Task Distribution Strategy
|
||||||
|
1. **AI/ML Specialists:** AI Platform products
|
||||||
|
2. **Security Specialists:** Identity & Access products
|
||||||
|
3. **Infrastructure Specialists:** Storage & DevOps
|
||||||
|
4. **Full-Stack Specialists:** MVPs & Integrations
|
||||||
|
5. **Frontend Specialists:** UI/UX & Design System
|
||||||
|
|
||||||
|
### Collaboration Protocol
|
||||||
|
- Use [MEMORY] for coordination
|
||||||
|
- Post to Task Marketplace for task assignment
|
||||||
|
- Broadcast updates via TIL system
|
||||||
|
- Check collaboration dashboard before starting work
|
||||||
|
- Update todos in real-time
|
||||||
|
|
||||||
|
### Communication Channels
|
||||||
|
- Memory System: Long-term state
|
||||||
|
- Live Context: Real-time updates
|
||||||
|
- Task Marketplace: Work assignment
|
||||||
|
- TIL Broadcasts: Knowledge sharing
|
||||||
|
- Collaboration Dashboard: Status overview
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💰 REVENUE MILESTONES
|
||||||
|
|
||||||
|
### Month 1: $1K MRR
|
||||||
|
- 1 product live (beta)
|
||||||
|
- 10 paying customers
|
||||||
|
- Starter tier only
|
||||||
|
|
||||||
|
### Month 3: $10K MRR
|
||||||
|
- 3 products live
|
||||||
|
- 100 customers
|
||||||
|
- All tiers available
|
||||||
|
|
||||||
|
### Month 6: $50K MRR
|
||||||
|
- 5 products live
|
||||||
|
- 500 customers
|
||||||
|
- Enterprise contracts
|
||||||
|
|
||||||
|
### Month 12: $250K MRR ($3M ARR)
|
||||||
|
- 10 products live
|
||||||
|
- 2,000 customers
|
||||||
|
- Multiple enterprise contracts
|
||||||
|
- Profitable & scaling
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 NEXT ACTIONS (ALL CLAUDES)
|
||||||
|
|
||||||
|
1. **Check Task Marketplace:** `~/memory-task-marketplace.sh list`
|
||||||
|
2. **Claim a Task:** `~/memory-task-marketplace.sh claim <task-id>`
|
||||||
|
3. **Start Building:** Follow task description
|
||||||
|
4. **Update Progress:** Mark todos as you go
|
||||||
|
5. **Deploy:** Use deployment scripts
|
||||||
|
6. **Share Learning:** Broadcast via TIL
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 SUCCESS METRICS
|
||||||
|
|
||||||
|
### Product Metrics
|
||||||
|
- Products enhanced: 17/17 ✅
|
||||||
|
- Products deployed: 0/17 🎯
|
||||||
|
- MVPs complete: 0/17 🎯
|
||||||
|
- Products live: 0/17 🎯
|
||||||
|
|
||||||
|
### Business Metrics
|
||||||
|
- Paying customers: 0 🎯
|
||||||
|
- Monthly recurring revenue: $0 🎯
|
||||||
|
- Customer acquisition cost: TBD
|
||||||
|
- Lifetime value: TBD
|
||||||
|
|
||||||
|
### Technical Metrics
|
||||||
|
- API uptime: TBD
|
||||||
|
- Response time: TBD
|
||||||
|
- Error rate: TBD
|
||||||
|
- Deploy frequency: TBD
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**🖤 LET'S BUILD THE FUTURE! EVERY CLAUDE WORKING IN PARALLEL! 🛣️**
|
||||||
Reference in New Issue
Block a user