blackroad-os/blackroad-os-prism-console
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
68208afcfdb819b584f3018d483b7ad620e7cd19
blackroad-os-prism-console/docs/REPOSITORY_ROLE.md
copilot-swe-agent[bot] 9777d02994 Add GitHub project management templates and ecosystem documentation 
- Add issue templates for agents, packs, features, bugs, infra, and docs
- Add labels.yml with BlackRoad OS standard labels (team, type, prio, status)
- Add PR template with atomic commit guidelines
- Add CONTRIBUTING.md with development guidelines
- Add docs/REPOSITORY_ROLE.md documenting this repo's ecosystem role
- Update README.md with badges, ecosystem links, and comprehensive docs

Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
2025-11-24 16:26:03 +00:00

284 lines
8.8 KiB
Markdown
Raw Blame History

# 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`:
```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](./PRISM_CONSOLE_PROMPT.md) - UX mission brief
- [Contributing Guide](../CONTRIBUTING.md) - Development guidelines
- [BlackRoad OS Docs](https://github.com/BlackRoad-OS/blackroad-os-docs)
- [Agent Registry](https://github.com/BlackRoad-OS/blackroad-os-agents)
- [Infrastructure](https://github.com/BlackRoad-OS/blackroad-os-infra)
---
**Remember:** The Prism Console is the bridge of the ship - the command surface where all BlackRoad OS operations converge into observable, controllable interfaces.
Reference in New Issue View Git Blame Copy Permalink