blackroad-operating-system/implementation-plans/IMPLEMENTATION_blackroad-prism-console.md

🚀 IMPLEMENTATION PLAN: blackroad-prism-console

Admin Dashboard for Observability & Job Management

Repo: blackboxprogramming/blackroad-prism-console Purpose: Web UI for Prism job queue, system metrics, audit logs Phase: Phase 2 (Months 14-18)

---

PURPOSE

blackroad-prism-console is the admin dashboard for monitoring and managing the BlackRoad OS ecosystem:

• Visualize Prism job queue
• Monitor agent execution
• View system metrics (Prometheus)
• Audit logs (Vault)
• User management
• Configuration management

Role in Architecture: Layer 6 (Application Layer) - Admin UI

Domain: prism.blackroad.systems

---

TECHNOLOGY STACK

Option A (Recommended): React + TypeScript

• Modern, scalable
• Rich ecosystem (React Query, Recharts, Ant Design)
• TypeScript for type safety

Option B: Vanilla JS (consistent with OS aesthetic)

• Zero dependencies
• Windows 95 theme
• Simple, fast

Recommendation: React + TypeScript (professional admin tool, different audience than OS)

---

KEY FEATURES

1. Job Queue Dashboard

Components:

• Job list (filterable by status, type, date)
• Job details (logs, timeline, metadata)
• Real-time updates (WebSocket)
• Job actions (cancel, retry, clone)

Example:

// src/components/JobQueue.tsx
import { useQuery } from 'react-query'
import { Table, Badge } from 'antd'

export function JobQueue() {
  const { data: jobs } = useQuery('jobs', fetchJobs, {
    refetchInterval: 5000  // Poll every 5 seconds
  })

  return (
    <Table
      dataSource={jobs}
      columns={[
        { title: 'ID', dataIndex: 'id' },
        { title: 'Type', dataIndex: 'type' },
        { title: 'Status', dataIndex: 'status', render: (status) => (
          <Badge
            status={status === 'running' ? 'processing' : 'default'}
            text={status}
          />
        )},
        { title: 'Created', dataIndex: 'created_at' },
      ]}
    />
  )
}

2. System Metrics

Metrics Sources:

• Prometheus (backend metrics)
• PostgreSQL (database stats)
• Redis (cache hit rate)
• Railway (infrastructure stats)

Dashboards:

• API Performance (latency, throughput, errors)
• Database Performance (queries, connections, slow queries)
• Agent Execution (success rate, duration)
• User Activity (active users, sessions)

3. Audit Logs (Vault)

Features:

• Search logs by user, action, date
• Export logs (CSV, JSON)
• Compliance reports (SOX, GDPR)
• Immutable log viewer

---

REPOSITORY STRUCTURE

blackroad-prism-console/
├── src/
│   ├── components/
│   │   ├── JobQueue.tsx
│   │   ├── Metrics.tsx
│   │   ├── AuditLogs.tsx
│   │   └── UserManagement.tsx
│   ├── pages/
│   │   ├── Dashboard.tsx
│   │   ├── Jobs.tsx
│   │   ├── Metrics.tsx
│   │   └── Settings.tsx
│   ├── api/
│   │   └── client.ts  # API client for blackroad-api
│   ├── hooks/
│   │   └── useWebSocket.ts  # Real-time updates
│   └── App.tsx
├── public/
├── package.json
├── tsconfig.json
├── vite.config.ts  # Build tool (Vite)
└── README.md

---

REQUIRED WORKFLOWS

1. CI/CD - Build, test, deploy to Vercel/Railway
2. Type Check - TypeScript type checking
3. E2E Tests - Playwright for UI tests
4. Lighthouse - Performance audits

---

CLOUDFLARE & DOMAINS

DNS Records (blackroad.systems zone):

Type	Name	Target	Proxy
CNAME	prism	blackroad-prism-console.vercel.app	✅

Deployment: Vercel (recommended for React SPAs)

---

MIGRATION NOTES

New Repo (not migrated from monolith)

Bootstrap:

# Create React app with TypeScript
npm create vite@latest blackroad-prism-console -- --template react-ts

# Install dependencies
cd blackroad-prism-console
npm install react-query axios antd recharts

# Connect to blackroad-api
# Create .env.production
VITE_API_URL=https://api.blackroad.systems
VITE_WS_URL=wss://api.blackroad.systems/ws

Effort: 4-6 weeks (full dashboard build)

---

PHASE 2 MILESTONES

Month 14-15: Repo setup, basic job queue UI Month 16-17: Metrics dashboards, audit logs Month 18: User management, production deployment

Success Criteria:

• ✅ Real-time job queue updates
• ✅ <1s dashboard load time
• ✅ 100% mobile responsive
• ✅ Used daily by team

---

Last Updated: 2025-11-18