Oracle Development Status & Transition Blueprint

This artifact summarizes the current state, remaining work, and architectural limitations/constraints for the Project Velocity - The Oracle module, based on the Master Architecture and Implementation Artifact (v1.0). It is intended to serve as a comprehensive briefing for a coding agent tasked with completing the Oracle implementation.

Note

Contextual Awareness: The current implementation_plan.md and task.md in the agent's brain directory are mapped to The Catalyst (Digital Marketing Agency module), which is a separate product vertical. The Oracle requires an independent set of execution tasks focused completely on the CRM's AI operational intelligence layer.

1. What Development is Done (Current State in Repo)

The repository currently contains the "visual shell" and technical foundation, but no production Oracle paths.

Frontend

Polished UI Shell Exists: app/src/app/oracle/page.tsx exists and provides a premium glassmorphic UI, a right-side conversation rail, and a top insight banner.
Mock Data Layer: The UI uses a single-response mock client (app/src/lib/oracleQueryClient.ts) operating on a legacy OracleQueryResult contract. It switches between fixed, hardcoded views instead of an extensible, revision-controlled canvas.

Backend

FastAPI / Python Foundation: A robust FastAPI backend is running (backend/main.py), utilizing asyncpg for PostgreSQL and JWT-based authentication.
AI Runtime Abstraction Exists: A production-grade Nemoclaw client (backend/services/nemoclaw_client.py) is already implemented and currently handles Sentinel's AI needs. This is the abstract LLM planner.
Database Baseline: backend/db/schema.sql possesses the baseline auth and Sentinel schemas, but lacks Oracle's revisioned canvas components.
Placeholders: backend/api/routes_oracle.py and backend/api/routes_crm.py exist but are entirely empty.

2. What is Remaining (Sprint 1 / MVP Blueprint)

The implementation must transition the system from "mocked single-response behavior" into "persistent, branchable, revisioned vertical JSON canvas behavior". This is broken down into Work Packages (WPs):

WP1: Contract Foundation (First Next Step)

Create JSON Schemas and API contracts (Section 6 & 13 types: CanvasPage, CanvasComponent, PromptExecution).
Deprecate the mock query client; build a typed oracleApiClient.ts.
Build the v1 Oracle router skeleton in FastAPI.

WP2: Persistence & DB Core

Implement the revision-friendly PostgreSQL database schemas outlined in Section 16.4 (oracle_canvas_pages, oracle_canvas_page_revisions, oracle_canvas_components, oracle_prompt_executions).

WP3: Prompt Orchestrator & Data Access

Wire up backend/oracle/prompt_orchestrator.py to route prompts to Nemoclaw_client.py.
Constraint: Implement strict structured parsing for Nemoclaw's output.
Build the Data Access Gateway and Policy Engine to securely query tenant PostgreSQL data based on the validated LLM plan.

WP4: Frontend Virtualized Canvas

Refactor app/src/app/oracle/page.tsx.
Create a virtualized vertical component scroller (oracle/components/CanvasViewport.tsx).
Introduce a Component Registry (oracle/components/ComponentRegistry.tsx) that translates backend JSON components (e.g., barChart, geoMap) into React views.
Make the prompt rail rely on the execution history instead of mock triggers.

WP5: Collaboration & Merge Model

Jira-Style Branching: Implement page sharing (Fork creation) instead of live shared edits.
Implement Merge Requests, 3-way component diffs, and conflict resolution UI (MergeReviewDrawer.tsx).

WP6: Component Catalog & Synthesis

Build a catalog of pre-made templates (KPI tiles, pipelines, investor geographic heatmaps).
Implement component synthesis: where an LLM generates a brand new visualization template utilizing extracted styleSignatures to match the tenant's exact design language.

3. Limitations & Constraints Imposed by the Master Artifact

The architecture document outlines very strict constraints on why parts of the system are deferred and how the remaining work must be executed.

Warning

Strict Implementation Ordering The system must be built sequentially. Do not build the frontend canvas (WP4) or Collaboration (WP5) before the API Contracts (WP1) and Persistence (WP2) are real. Quoting the document: "The first concrete move... should be to freeze the current mock Oracle query client... The second move should be to add Oracle page tables... Only after those three foundations exist should the team invest in merge review UI or template synthesis. That order keeps the product grounded in durable state rather than another generation of temporary mocks."

Structural Constraints

No Unrestricted AI Executing SQL: Nemoclaw acts only as a planner. It must never execute arbitrary SQL or touch connector APIs directly to mitigate hallucination and data leakage. It produces a JSON query plan that is executed strictly by the non-AI Data Access Gateway.
No Live Co-Editing: Overwriting another user's Oracle dashboard live is forbidden. Oracle requires an explicit asynchronous Fork & Merge collaboration structure.
Immutable Pages: Pages are append-only. When the frontend mutates a visualization, it must execute a new commit revision or a rollback revision. It must never silently overwrite a past revision log.
Synthesis is Delayed & Isolated: Auto-promotion of LLM-synthesized UI components is explicitly isolated to the originating tenant for Sprint 1. Global (cross-tenant) sharing of synthesized components is forbidden.
No Uncontrolled Fine-Tuning: Visual generation must use exemplar retrieval (a JSON dictionary styleSignature), instead of raw model-weight fine-tuning, to ensure styling remains fully deterministic.

Security / Scope Constraints

Cross-Tenant Blocking: Because of Hybrid Sovereign deployment architecture, querying across tenants is explicitly rejected and unsupported in this phase.
Connectors: MVP must rely primarily on internal Velocity PostgreSQL datasets. External CRM connectors are deferred to later phases.

4. Oracle Development Status Dashboard

Task Category	Status	Details / Scope	Specific Limitations / Constraints
Frontend UI Shell	✅ Completed	Premium glassmorphic UI, right-side conversation rail, and top insight banner are all in place (`app/src/app/oracle/page.tsx`).	N/A - Serves as visual foundation.
Backend Foundation	✅ Completed	FastAPI router base, `asyncpg` for PostgreSQL, and JWT authentication flow.	N/A - Foundation only.
AI Planner Engine	✅ Completed	`Nemoclaw` client is operational and abstracted (currently used by Sentinel).	Operates merely as a planner; the LLM cannot execute SQL directly.
Mock Data Layer	⏸️ Deprecated	Legacy `oracleQueryClient.ts` powering single-response fixed views with hardcoded data.	Cannot be used for Phase 2. Must be replaced immediately prior to frontend expansion.
WP1: Contract Foundation	⏳ Remaining	JSON Schemas (`CanvasPage`, `CanvasComponent`) and typed `oracleApiClient.ts`.	Must be built first. No UI development can proceed until the API contracts replace the legacy mocks.
WP2: Persistence & DB Core	⏳ Remaining	PostgreSQL schema implementation for `canvas_pages`, `revisions`, `components`, and `executions`.	Sequential Dependency. Must be completed immediately after WP1 to ensure all UI actions rely on durable states, avoiding fake in-memory changes.
WP3: Prompt Orchestrator	⏳ Remaining	Wire backend (`prompt_orchestrator.py`) to Nemoclaw for structured JSON retrieval and visualization planning.	Redaction & Security. The Data Access Gateway must validate the plan. Nemoclaw is forbidden from directly querying external connectors, preventing data hallucination/leakage.
WP4: Frontend Canvas	⏳ Remaining	Refactor Oracle UI into a virtualized, vertically scrolling JSON canvas with a proper Component Registry.	No Live Co-Editing. State changes (mutations) must execute explicit revision commits or rollbacks. Overwriting another user's current view directly is forbidden.
WP5: Collaboration & Merging	⏳ Remaining	Jira-style Share (Fork) workflows, Merge Requests, 3-way component diffs, and review UI.	Isolated Revisions. All sharing forces a new branch (Fork). No cross-tenant data sharing is allowed under any circumstance (Hybrid Sovereign constraint).
WP6: Catalog & Synthesis	⏳ Remaining	AI-driven synthesis of custom UI components using extracted tenant styling.	No Global Promotion. Auto-promotion of LLM-generated components is isolated to the origin tenant. Uses deterministic `styleSignatures`, avoiding uncontrolled weight fine-tuning.
WP7: Hardening & Ops	⏳ Remaining	Performance testing, telemetry, replay fixtures, and SLA tuning limiters.	Must ensure canvas scrolling maintains 60 FPS up to 5,000 components via strict virtualization limits.

9.1 KiB Raw Blame History