blackroad-os-prism-console/docs/REPOSITORY_ROLE.md

Repository Role: blackroad-os-prism-console

Overview

The blackroad-os-prism-console repository is the single-pane-of-glass administrative console for the entire BlackRoad OS ecosystem. It serves as the primary visual interface for monitoring, managing, and orchestrating agents, environments, deployments, and infrastructure across the BlackRoad OS platform.

Position in BlackRoad OS Ecosystem

Primary Organization: BlackRoad-OS

The Prism Console is a core infrastructure component within the BlackRoad-OS organization, alongside:

Core Platform:

• blackroad-os-core - Core platform logic and shared libraries
• blackroad-os-operator - Orchestration and automation agent
• blackroad-os-api - Main API backend
• blackroad-os-api-gateway - API gateway and routing

Infrastructure:

• blackroad-os-agents - Agent and pack registry
• blackroad-os-infra - Infrastructure blueprints and configurations
• blackroad-os-prism-console ← You are here

Supporting Repositories:

• blackroad-os-web - Public-facing website
• blackroad-os-docs - Documentation hub
• blackroad-os-archive - Logs and historical data
• blackroad-os-research - Research and experimental features

Related Business Entities

While Prism Console is in BlackRoad-OS, it may interface with repos from:

• Blackbox-Enterprises
• BlackRoad-AI
• BlackRoad-Gov
• BlackRoad-Hardware
• BlackRoad-Interactive
• BlackRoad-Media
• BlackRoad-Studio
• BlackRoad-Ventures

Responsibilities

Core Functions

1. Agent Monitoring & Management

   • Display real-time agent health status
   • Show agent capabilities, pack assignments, and last run times
   • Provide agent inspection interface with memory stacks and logic traces
   • Enable hot redeploys and agent swap-outs

2. Environment Monitoring

   • Track deployed environments across Railway, Vercel, Cloudflare
   • Monitor readiness endpoints and TLS states
   • Display environment labels and connectivity status
   • Show real-time deployment events

3. Job & Schedule Tracking

   • Visualize scheduled jobs and cron tasks
   • Display job execution history
   • Monitor job success/failure rates

4. Identity & Audit

   • Track PS-SHA∞ identity headers
   • Display beacon heartbeats
   • Provide audit trails for agent executions
   • Enable audit sidecar view with rewindable history

5. Lucidia Dashboard

   • Master interface for Lucidia's runtime mind
   • SIG graph visualizations
   • Interference Engine displays
   • Agent Tree Hierarchy (GEN0/GEN1/etc.)

6. Infrastructure Control

   • Railway service management
   • Cloudflare configuration toggles
   • Feature flag controls
   • Environment variable management

Technical Architecture

Tech Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Testing: Vitest + React Testing Library
• Deployment: Railway, Docker
• CI/CD: GitHub Actions

Key Modules

Per docs/PRISM_CONSOLE_PROMPT.md:

• env-monitor.ts - Environment tracking and monitoring
• agent-inspector.tsx - Agent memory, traces, and SIG traits
• console-beacon.json - Health and uptime pulse system
• lucidia-dashboard.tsx - Master runtime mind interface

API Integration

The Prism Console integrates with:

• BlackRoad OS API Gateway - Core data and operations
• Agent Registry - Agent and pack metadata from blackroad-os-agents
• Infrastructure APIs - Railway, Cloudflare, etc.

Domain Configuration

Active domains that may serve Prism Console:

• blackroad.io
• blackroad.systems
• blackroad.network
• blackroadai.com
• blackroadinc.us
• lucidia.earth
• lucidia.studio

Domain configurations are managed in blackroad-os-infra/domains/domains.yml.

Pack System Integration

The Prism Console displays and manages agents from all packs:

• pack.education - Education-focused agents
• pack.infra-devops - Infrastructure and DevOps agents
• pack.creator-studio - Content creation agents
• pack.finance - Financial services agents
• pack.legal - Legal compliance agents
• pack.research-lab - Research and experimental agents

Pack metadata is sourced from blackroad-os-agents/registry/packs.yml.

Agent Registry Integration

The console reads agent data from blackroad-os-agents/registry/agents.json:

{
  "id": "agent-id",
  "display_name": "Agent Name",
  "pack_id": "pack.example",
  "role": "Agent role",
  "skills": ["skill1", "skill2"],
  "repos": ["repo1", "repo2"],
  "environments": ["production", "staging"],
  "permissions": {
    "github": "read|write",
    "railway": "read|write",
    "cloudflare": "read"
  },
  "status": "active|inactive|degraded"
}

Deployment & Infrastructure

Railway Configuration

Configured via railway.toml and railway.json:

• Service name: prism-console
• Default port: 3000
• Environment variables from prisma-console.env.example

Docker

Dockerfile provides containerized deployment:

• Base: Node.js 20
• Next.js standalone output
• Production-optimized build

CI/CD

GitHub Actions workflow (.github/workflows/ci.yml):

• Lint, test, and build on all pushes
• Automated deployment via console-deploy.yaml

Data Flow

┌─────────────────────────────────────────┐
│   Prism Console (Frontend)              │
│   - Next.js App Router                  │
│   - React Components                    │
│   - Tailwind UI                         │
└──────────────┬──────────────────────────┘
               │
               ├─► Agent Registry API
               │   (blackroad-os-agents)
               │
               ├─► API Gateway
               │   (blackroad-os-api-gateway)
               │
               ├─► Infrastructure APIs
               │   (Railway, Cloudflare)
               │
               └─► Core Platform
                   (blackroad-os-core)

Design Philosophy

From docs/PRISM_CONSOLE_PROMPT.md:

"The visual cortex and master admin terminal of BlackRoad OS"

Inspirations:

• OpenAI's internal console
• NASA launch software
• Tron aesthetics
• VS Code interface patterns
• Stardew Valley UI clarity

Principles:

• Real-time control over a cognitive civilization
• Every component is observable and inspectable
• Graceful fallback views when data is delayed
• "Do anything from here" - comprehensive control surface

Development Guidelines

For Prism Console Changes

1. Agent Features - Tag with type:agent, team:prism
2. Pack Features - Tag with type:pack, team:prism
3. Infrastructure - Tag with type:infra, team:prism, team:infra
4. UI/UX - Tag with team:prism, team:brand

Cross-Repository Coordination

When changes involve multiple repos:

1. Agent Registry Updates - Coordinate with blackroad-os-agents
2. API Changes - Coordinate with blackroad-os-api or blackroad-os-api-gateway
3. Infrastructure - Coordinate with blackroad-os-infra
4. Documentation - Update blackroad-os-docs

Operational Boundaries

What Prism Console Does

✅ Visualize and monitor all BlackRoad OS systems ✅ Provide real-time dashboards and interfaces ✅ Enable operator controls and toggles ✅ Display agent health, traces, and audit logs ✅ Manage environment configurations

What Prism Console Does NOT Do

❌ Execute backend business logic (use blackroad-os-core or blackroad-os-api) ❌ Store persistent data (use appropriate backend services) ❌ Define agent schemas (use blackroad-os-agents) ❌ Manage infrastructure directly (use blackroad-os-infra)

Future Roadmap

From README.md:

• Wire lib/fetcher.ts to the BlackRoad OS API Gateway
• Stream deployment events over $CORE_HUB/ws
• Replace placeholder cards with live environment KPIs
• Implement Window-in-Window mode for live agent debugging
• Add scrubbable timeline UI for inference events
• Create live update map of agent deployments per region

Contact & Support

• Primary Team: team:prism
• Supporting Teams: team:web, team:infra, team:operator
• Documentation: blackroad-os-docs
• Agent Registry: blackroad-os-agents

References

• Prism Console Prompt - UX mission brief
• Contributing Guide - Development guidelines
• BlackRoad OS Docs
• Agent Registry
• Infrastructure

---

Remember: The Prism Console is the bridge of the ship - the command surface where all BlackRoad OS operations converge into observable, controllable interfaces.