Orchestrata Ultimate › Plans › plan_vizint_implementation › implementation-plan

VizInt Command Center — Detailed Implementation Plan

Source: plans/plan_vizint_implementation/implementation-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-05-26 · 1041 lines.

Prose pending.

Plan text

VizInt Command Center — Detailed Implementation Plan

Spec: 016-vizint-command-center
Status: Gap Analysis Complete → Implementation Planned
Plan Version: 1.0.0
Created: 2026-05-26
Estimated Duration: 8–10 weeks (1 engineer full-time)
Parallelizable: Phases 0–1 can overlap; Phases 2–4 have internal parallel tracks

Table of Contents

1. Executive Summary
2. Current State Snapshot
3. Phase 0: Foundation & Backend Hardening
4. Phase 1: Portal Framework Core
5. Phase 2: P1 Production Gadgets (Batch A)
6. Phase 3: P1 Production Gadgets (Batch B) + Gateway Integration
7. Phase 4: P2 Gadgets & Personal Productivity
8. Phase 5: Testing, Compliance & Performance
9. Appendix A: Dependency Graph
10. Appendix B: Risk Register
11. Appendix C: Definition of Done
12. Appendix D: Traceability Matrix

1. Executive Summary

Problem

The VizInt Command Center (Spec 016) is the unified dashboard for Orchestrata. The backend gateway handlers exist but the entire JavaScript frontend is missing from the repository. Additionally:

• A conflicting older spec (051) describes a different architecture (FastAPI + HTMX)
• Gateway SessionHandler.handle_active() returns hardcoded mock data
• 117 of 294 requirements are incomplete (40% gap)
• 0% constitutional compliance verified
• No contract tests between frontend expectations and backend RPC schemas

Solution

Implement the frontend in 5 phases over 8–10 weeks:

Success Criteria

• All 294 requirements in specs/016-vizint-command-center/checklists/requirements.md marked [x]
• Constitutional compliance ≥ 90% (128/142 items)
• Test coverage: 59 unit tests + 8 contract + 8 integration + 5 perf + 11 E2E = 91 tests minimum
• Performance: initial render < 100ms, WebSocket reconnect < 3s, memory < 100MB (10 gadgets)
• Frontend code committed to vizint-ui/ with its own package.json, Vitest, Playwright

2. Current State Snapshot

What Exists ✅

src/orchestrata_ultimate/gateway/
├── handlers/session.py       # SessionHandler — 7 RPC methods (stubbed active)
├── handlers/projects.py      # ProjectsHandler — 4 RPC methods (real Neo4j)
├── handlers/volk.py          # VolkHandler — list, lifecycle
├── handlers/cxp.py           # CXPFeed handler
├── handlers/knowledge.py     # Knowledge graph queries
├── handlers/governance.py    # Governance decisions
├── rpc.py                    # RPC router wiring all handlers
├── server.py                 # WebSocket server (SPEC-014)
└── pubsub.py                 # Pub/sub subscription manager

What Is Missing ❌

vizint-ui/                          # ENTIRE DIRECTORY MISSING
├── index.html                      # Entry point with import maps
├── app.js                          # CommandCenterApp
├── lib/
│   ├── portal.js                   # Gadget lifecycle
│   ├── bus.js                      # EventBus (CustomEvents)
│   ├── registry.js                 # Dynamic ES module loading
│   ├── chrome.js                   # Gadget window chrome
│   ├── shared.js                   # Utilities (debounce, formatTimestamp)
│   ├── atlas.js                    # Geolocation
│   └── chronus.js                  # Time engine
├── bridge/
│   ├── websocket-bridge.js         # JSON-RPC 2.0 over WS
│   ├── gadget-bridge.js            # bus <-> RPC translation
│   ├── state-sync.js               # localStorage + remote sync
│   └── notification-manager.js     # Desktop + in-app notifications
├── gadgets/                        # 31 gadgets (ALL MISSING)
├── styles/
│   ├── common.css                  # CSS variables, themes
│   └── command-center.css          # Layout, chrome, badges
├── providers/                      # Chronus providers
├── configs/
│   └── command-center.json         # Runtime config
└── tests/
    ├── vitest.config.js
    ├── unit/                       # 48 unit tests
    ├── e2e/                        # 11 Playwright tests
    └── helpers/ws-test-server.js   # Mock JSON-RPC server

Phase 0: Foundation & Backend Hardening

Duration: Week 1
Goal: Eliminate blockers before frontend development starts
Parallelizable: Yes — backend tasks can run alongside Phase 1 scaffolding

0.1 Deprecate SPEC-051

Task: Consolidate the two VizInt specs into one canonical source of truth.

Deliverable: Single canonical spec (016). No references to 051 in active docs.

0.2 Harden Gateway SessionHandler

Task: Remove hardcoded mock data from gateway/handlers/session.py.

Deliverable: All 7 session RPC methods return real data from Neo4j/SessionController.

0.3 Write Contract Tests

Task: Create schema-validated contract tests that pin frontend expectations to backend behavior.

Deliverable: 8 contract tests passing. Schemas are the API contract between frontend and backend.

0.4 Create vizint-ui/ Scaffold

Task: Set up the frontend directory structure and toolchain.

Deliverable: vizint-ui/ is a runnable Node.js project with test tooling.

Phase 0 Exit Criteria

• [ ] SPEC-051 deprecation notice committed
• [ ] SessionHandler.handle_active() returns real Neo4j data (no hardcoded values)
• [ ] 8 contract tests pass against real gateway
• [ ] vizint-ui/ directory scaffolded with npm install, npm test, npm run e2e all working
• [ ] Gateway handlers have @traces on all public methods

Phase 1: Portal Framework Core

Duration: Weeks 1–3
Goal: Implement the core infrastructure that all gadgets depend on
Risk: Low — these are well-specified utility modules with clear interfaces

1.1 Shared Utilities (lib/shared.js)

Deliverable: lib/shared.js with 100% unit test coverage.

1.2 EventBus (lib/bus.js)

Deliverable: lib/bus.js — 8 unit tests passing.

1.3 WebSocketBridge (bridge/websocket-bridge.js)

Deliverable: bridge/websocket-bridge.js — 12 unit tests passing.

1.4 StateSync (bridge/state-sync.js)

Deliverable: bridge/state-sync.js — 8 unit tests passing.

1.5 GadgetRegistry (lib/registry.js)

Deliverable: lib/registry.js — 5+ unit tests passing.

1.6 Gadget Chrome (lib/chrome.js)

Deliverable: lib/chrome.js — 4+ unit tests passing.

1.7 GadgetBridge (bridge/gadget-bridge.js)

Deliverable: bridge/gadget-bridge.js — tested via integration.

1.8 NotificationManager (bridge/notification-manager.js)

Deliverable: bridge/notification-manager.js — 7+ unit tests passing.

1.9 CommandCenterApp (app.js)

Deliverable: app.js — E2E tests for page load, header, theme, layout, connection status.

1.10 HTML Entry Point & Styles

Deliverable: index.html loads in browser with correct theme, grid, and header.

Phase 1 Exit Criteria

• [ ] All 59 unit tests from testing.md passing
• [ ] 11 E2E tests passing (page load, header, theme, layout, WebSocket, gadget loading)
• [ ] vizint-ui/ runs with npm run dev (static file server)
• [ ] code-review.py passes on all new JS files (ES2024, no var, no eval, etc.)
• [ ] Performance: initial render < 100ms, theme switch < 50ms

Phase 2: P1 Production Gadgets (Batch A)

Duration: Weeks 3–5
Goal: Implement the 4 most critical observability gadgets
Parallelizable: Yes — 4 gadgets can be developed in parallel by different engineers

2.1 ProjectExplorer Gadget (gadgets/project-explorer/)

Requirements: US-001, FR-008, REQ-016-001 to 020
Estimated LOC: 173
Priority: Critical

Deferred to Phase 5: Sparkline trends (REQ-016-012), iteration summary (REQ-016-005, 017), click-through to SessionManager/IterationBrowser (REQ-016-018, 019).

2.2 SessionManager Gadget (gadgets/session-manager/)

Requirements: US-002, FR-009, REQ-016-021 to 052
Estimated LOC: 198
Priority: Critical

Deferred to Phase 5: Deferred work management (REQ-016-033 to 039), work logging (REQ-016-040 to 042), history search/filter (REQ-016-048 to 050).

2.3 CXPFeed Gadget (gadgets/cxp-feed/)

Requirements: US-003, FR-012, REQ-016-051 to 074
Estimated LOC: 161
Priority: Critical

Deferred to Phase 5: JSON syntax highlighting (REQ-016-058), subject glob filter (REQ-016-062), active filter count (REQ-016-065), jump-to-bottom button (REQ-016-070, 071), throughput indicator (REQ-016-073, 074).

2.4 VolkStatus Gadget (gadgets/volk-status/)

Requirements: US-004, FR-013, REQ-016-075 to 093
Estimated LOC: 192
Priority: Critical

Deferred to Phase 5: Detail panel (REQ-016-085 to 089), compact mode (REQ-016-091 to 093), slide-in animations (REQ-016-082, 083).

Phase 2 Exit Criteria

• [ ] All 4 gadgets render real data from gateway
• [ ] E2E tests for each gadget: mount, data display, real-time updates
• [ ] Integration tests: gateway → WebSocketBridge → GadgetBridge → gadget render
• [ ] No console errors, no unhandled rejections
• [ ] Gadgets functional when gateway disconnected (cached data, read-only mode)

Phase 3: P1 Production Gadgets (Batch B) + Gateway Hardening

Duration: Weeks 5–7
Goal: Complete remaining P1 gadgets + ensure backend feeds real data
Parallelizable: Gadget development parallel; gateway hardening can be separate track

3.1 ClaudeChat Gadget (gadgets/claude-chat/)

Requirements: US-005, FR-016, REQ-016-094 to 118
Estimated LOC: 226

Deferred: Thread selector (REQ-016-110, 111), cross-device sync (REQ-016-113), message search (REQ-016-118), timestamps on hover (REQ-016-098).

3.2 TaskBoard Gadget (gadgets/task-board/)

Requirements: US-006, FR-010, FR-017, REQ-016-119 to 144
Estimated LOC: 224

Deferred: Deferred column (REQ-016-123), touch drag-drop (REQ-016-127), undo (REQ-016-128), task detail panel (REQ-016-137 to 141), bidirectional sync (REQ-016-142 to 144).

3.3 QADashboard Gadget (gadgets/qa-dashboard/)

Requirements: US-007, FR-014, REQ-016-145 to 168
Estimated LOC: 179
Priority: Currently only 21% complete — biggest gap

Deferred: Metric cards with delta (REQ-016-149), slowest tests highlight (REQ-016-161), duration trend sparkline (REQ-016-150 related).

3.4 AuditTrail Gadget (gadgets/audit-trail/)

Requirements: US-008, FR-015, REQ-016-169 to 188
Estimated LOC: 202

Deferred: Date range picker (REQ-016-175), article filter (REQ-016-179), escalation chains (REQ-016-182, 183), CSV/JSON export (REQ-016-185 to 188).

3.5 Gateway Hardening (Backend Track)

Deliverable: All gateway handlers return real data. No stubs or hardcoded values remain.

Phase 3 Exit Criteria

• [ ] All 8 P1 gadgets render real data
• [ ] QADashboard completion ≥ 80% (was 21%)
• [ ] Gateway has zero hardcoded responses
• [ ] Contract tests expanded to cover new RPC methods (tests.run, metrics.current)
• [ ] Integration tests: full stack (backend → WS → frontend → render)

Phase 4: P2 Gadgets & Personal Productivity

Duration: Weeks 7–8
Goal: Complete remaining gadgets + personal productivity features
Parallelizable: Yes — personal gadgets are independent

4.1 KGExplorer Gadget (gadgets/kg-explorer/)

Requirements: US-009, FR-019, REQ-016-189 to 208

Deferred: Auto-complete (REQ-016-204), query history (REQ-016-207), full-text search (FR-019 related).

4.2 NotificationCenter Gadget (gadgets/notification-center/)

Requirements: US-010, FR-005, REQ-016-209 to 230

4.3 Personal Productivity Gadgets

4.4 Theme & Layout Polish

Phase 4 Exit Criteria

• [ ] All 31 gadgets implemented and mountable
• [ ] All personal gadgets work offline (gateway disconnected)
• [ ] Theme/layout customization fully functional
• [ ] E2E tests for each new gadget

Phase 5: Testing, Compliance & Performance

Duration: Weeks 8–10
Goal: Validate the entire system against spec, constitution, and performance budget
Parallelizable: Test categories can run in parallel

5.1 Contract & Integration Tests

5.2 Performance Tests

5.3 Accessibility Tests

5.4 Security Tests

5.5 Failure Scenario Tests

5.6 Constitutional Compliance Review

Target: 128/142 (90%) constitutional items verified.

5.7 Performance Budget Validation

Phase 5 Exit Criteria

• [ ] All 294 requirements checked [x] in requirements.md
• [ ] Constitutional compliance ≥ 90% (128/142)
• [ ] 91+ tests passing: 59 unit + 8 contract + 8 integration + 5 perf + 11 E2E
• [ ] All performance metrics within budget
• [ ] Accessibility audit passes WCAG 2.1 AA
• [ ] Security audit: 0 XSS vectors, CSP enforced
• [ ] vizint-ui/ committed with working npm test, npm run e2e

Appendix A: Dependency Graph

Phase 0 ──────────────────────────────────────────────────────────────►
  │
  ├──► Spec consolidation (0.1) ──┐
  │                                 │
  ├──► Gateway hardening (0.2) ────┼──► Phase 1 ──► Phase 2 ──► Phase 3 ──► Phase 4 ──► Phase 5
  │                                 │     ▲           ▲           ▲           ▲           ▲
  ├──► Contract tests (0.3) ───────┘     │           │           │           │           │
  │                                      │           │           │           │           │
  └──► Scaffold (0.4) ──────────────────┘           │           │           │           │
                                                    │           │           │           │
Phase 1: Portal Framework ──────────────────────────┘           │           │           │
  ├── lib/shared.js                                             │           │           │
  ├── lib/bus.js                                                │           │           │
  ├── bridge/websocket-bridge.js                                │           │           │
  ├── bridge/state-sync.js                                      │           │           │
  ├── lib/registry.js                                           │           │           │
  ├── lib/chrome.js                                             │           │           │
  ├── bridge/gadget-bridge.js                                   │           │           │
  ├── bridge/notification-manager.js                            │           │           │
  ├── app.js                                                    │           │           │
  └── index.html + styles                                       │           │           │
                                                                │           │           │
Phase 2: P1 Batch A ────────────────────────────────────────────┘           │           │
  ├── gadgets/project-explorer/                                             │           │
  ├── gadgets/session-manager/                                              │           │
  ├── gadgets/cxp-feed/                                                     │           │
  └── gadgets/volk-status/                                                  │           │
                                                                            │           │
Phase 3: P1 Batch B + Gateway ──────────────────────────────────────────────┘           │
  ├── gadgets/claude-chat/                                                              │
  ├── gadgets/task-board/                                                               │
  ├── gadgets/qa-dashboard/                                                             │
  ├── gadgets/audit-trail/                                                              │
  └── backend: volk.list, cxp.traffic, tests.run, metrics.current                       │
                                                                                        │
Phase 4: P2 Gadgets ────────────────────────────────────────────────────────────────────┘
  ├── gadgets/kg-explorer/
  ├── gadgets/notification-center/
  ├── gadgets/prayer-times/
  ├── gadgets/flashcards/
  ├── gadgets/iqama-countdown/
  ├── gadgets/time-to-poi/
  ├── gadgets/chronus-sequencer/
  ├── gadgets/settings/
  ├── gadgets/embed/
  └── theme/layout polish

Phase 5: Validation
  ├── contract tests
  ├── integration tests
  ├── performance tests
  ├── accessibility tests
  ├── security tests
  ├── failure scenarios
  └── constitutional compliance

Appendix B: Risk Register

Appendix C: Definition of Done

Per-Task Definition of Done

1. Code complete: Implementation matches spec requirement IDs
2. Tests pass: Unit + E2E tests for the feature pass in CI
3. Lint clean: ESLint + Prettier pass with zero warnings
4. Traceability: @traces decorator on all new Python classes/methods
5. No stubs: All data from real backend (Neo4j, gateway, runtime)
6. Documented: JSDoc on all public JS classes/methods
7. Reviewed: Code review approval (pre-commit hook passes)

Per-Phase Definition of Done

1. All phase exit criteria met (see each phase)
2. Contract tests pass for all RPC methods touched in the phase
3. Integration tests pass for end-to-end flows
4. No console errors in browser during E2E test run
5. Performance budget not exceeded for new features
6. Commit to git with session tracking (session work ...)

Per-Project Definition of Done

1. All 294 requirements in requirements.md marked [x]
2. Constitutional compliance ≥ 90% (128/142)
3. 91+ tests passing across all categories
4. Performance budget validated
5. Accessibility audit passes WCAG 2.1 AA
6. Security audit: 0 critical vulnerabilities
7. SPEC-051 deprecated and archived
8. vizint-ui/ committed with README, package.json, and CI config

Appendix D: Traceability Matrix

Appendix E: File Inventory

New Files to Create

vizint-ui/
├── package.json
├── package-lock.json
├── vitest.config.js
├── playwright.config.js
├── .eslintrc.json
├── .prettierrc
├── index.html
├── app.js
├── lib/
│   ├── portal.js
│   ├── bus.js
│   ├── registry.js
│   ├── chrome.js
│   ├── shared.js
│   ├── atlas.js
│   └── chronus.js
├── bridge/
│   ├── websocket-bridge.js
│   ├── gadget-bridge.js
│   ├── state-sync.js
│   └── notification-manager.js
├── gadgets/
│   ├── project-explorer/
│   │   └── gadget.js
│   ├── session-manager/
│   │   └── gadget.js
│   ├── cxp-feed/
│   │   └── gadget.js
│   ├── volk-status/
│   │   └── gadget.js
│   ├── claude-chat/
│   │   └── gadget.js
│   ├── task-board/
│   │   └── gadget.js
│   ├── qa-dashboard/
│   │   └── gadget.js
│   ├── audit-trail/
│   │   └── gadget.js
│   ├── kg-explorer/
│   │   └── gadget.js
│   ├── notification-center/
│   │   └── gadget.js
│   ├── flashcards/
│   │   ├── gadget.js
│   │   └── data.csv
│   ├── iqama-countdown/
│   │   └── gadget.js
│   ├── prayer-times/
│   │   └── gadget.js
│   ├── time-to-poi/
│   │   └── gadget.js
│   ├── chronus-sequencer/
│   │   └── gadget.js
│   ├── settings/
│   │   └── gadget.js
│   ├── embed/
│   │   └── gadget.js
│   ├── embed-web/
│   │   └── gadget.js
│   ├── runway-viewport/
│   │   └── gadget.js
│   ├── chronus-dev/
│   │   └── gadget.js
│   ├── atlas-debug/
│   │   └── gadget.js
│   ├── helloworld/
│   │   └── gadget.js
│   ├── helloworld2/
│   │   └── gadget.js
│   ├── helloworld-settings/
│   │   └── gadget.js
│   ├── daily/
│   │   └── gadget.js
│   ├── worldtz/
│   │   └── gadget.js
│   ├── eom/
│   │   └── gadget.js
│   └── prayertimes-chronus/
│       └── gadget.js
├── styles/
│   ├── common.css
│   └── command-center.css
├── providers/
│   ├── chronus_civil_provider.js
│   └── chronus_prayerTimes_provider.js
├── configs/
│   └── command-center.json
└── tests/
    ├── unit/
    │   ├── shared.test.js
    │   ├── bus.test.js
    │   ├── websocket-bridge.test.js
    │   ├── state-sync.test.js
    │   ├── registry.test.js
    │   ├── chrome.test.js
    │   └── notification-manager.test.js
    ├── e2e/
    │   └── dashboard.spec.js
    ├── contracts/
    │   ├── session.schema.json
    │   ├── projects.schema.json
    │   └── rpc.contract.test.js
    └── helpers/
        └── ws-test-server.js

Existing Files to Modify

specs/051-vizint-ui/spec.md                        # Add deprecation notice
specs/016-vizint-command-center/checklists/
  ├── requirements.md                               # Mark items [x] as completed
  ├── constitutional.md                             # Mark items [x] as completed
  └── testing.md                                    # Mark items [x] as completed
src/orchestrata_ultimate/gateway/handlers/session.py  # Remove hardcoded data
src/orchestrata_ultimate/gateway/handlers/volk.py     # Add lifecycle pub/sub
src/orchestrata_ultimate/gateway/handlers/cxp.py      # Add traffic streaming
src/orchestrata_ultimate/gateway/rpc.py              # Add new RPC methods
.github/workflows/
  └── ci.yml                                         # Add vizint-ui test steps

Appendix F: Effort Summary

End of Implementation Plan

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks