Kavach Studio

Overview

Studio is intentionally thin: REST DTOs are the frontend contract. Graph traversal, ontology validation, Neo4j access, lineage, and governance semantics stay in the Python backend. React Flow renders backend-provided nodes and relationships. Frontend filters are passed to graph query APIs instead of deriving hidden ontology semantics in the browser.

Local Development

cd console
pnpm install
pnpm dev

Studio reads the API base URL from NEXT_PUBLIC_KAVACH_API_BASE_URL (defaults to http://localhost:8000). Graph canvas colors can be adjusted with:

NEXT_PUBLIC_GRAPH_INPUT_COLOR=#eceae4
NEXT_PUBLIC_GRAPH_OUTPUT_COLOR=#a2e1db
NEXT_PUBLIC_GRAPH_ROOT_COLOR=#e1f7e7

Docker

docker compose up --build

This starts kavach-platform on port 8000, kavach-studio on port 3000, and Neo4j on bolt://localhost:7687. Studio calls the Python REST API only; it does not connect to Neo4j.

Experiment Management

The /experiments area is the Studio workflow for controlled evaluation of governed AI configurations. It provides a paginated experiment inventory, backend-driven candidate registration, evaluation run inspection, candidate comparison, and leaderboard review.

Replay Management

The /replays area creates and inspects governed reproductions of historical workflow executions. It uses a paginated source-execution search rather than loading an unbounded list of IDs, then validates and freezes source evidence before submission.

Replay detail shows execution, evaluation, comparison, drift, result, audit, and lineage evidence. Its lineage graph supports local node repositioning, reset, and node metadata inspection; the browser never derives execution or governance outcomes. See the Replay Management tutorial for the end-to-end workflow.

The Experiment Management tutorial covers the complete workflow and includes placeholders for the tab screenshots.

Policy Engine

The /policies area is the Studio authoring surface for governance policy definitions and policy versions. It uses backend-owned policy administration contracts and does not evaluate conditions in React.

Routes:

• /policies
• /policies/new
• /policies/[policyId]
• /policies/[policyId]/versions/[version]
• /policies/[policyId]/versions/[version]/edit
• /policies/[policyId]/versions/[version]/simulate

Supports searchable and filterable policy inventory, definition creation, read-only version inspection, draft-only rule editing, explicit activation and archival actions, and backend simulation with matched conditions and trace output.

Jobs

The /jobs area is the Studio operations surface for asynchronous governance work. It renders backend job control-plane state and does not implement worker leasing, scheduling, or execution logic in React.

Local/dev demo seeding populates the Jobs page with ten representative jobs across queued, running, succeeded, failed, and cancelled states.

Supports submitted status and job_type filters, status summary lanes, paginated run inventory, selected run detail with attempts and result reference, job submission through backend idempotency contracts, and cancel and retry lifecycle actions.

The Runs view refreshes every five seconds by default. Operators can choose Off, 5s, 10s, or 30s for the current browser session; this preference is not persisted.

MCP Audit

The /audit area is the Studio inspection surface for MCP execution audit records. It is backed by a dedicated REST read model instead of requiring the browser to fan out across low-level MCP audit endpoints.

Local/dev demo seeding populates the audit store with representative MCP write audit records across succeeded, failed, dry-run, and interrupted states. The Studio audit read model returns summary metrics, available filter values, paginated audit inventory with search and derived interruption state, and audit detail with request metadata and linked job context.

Graph Explorer

The /graph page supports entity type and entity ID lookup, bounded depth (capped at backend limit of 5), relationship type filters, optional node type filters for neighbourhood queries, incoming/outgoing and bidirectional traversal modes, node and edge selection details, and manual node rearrangement with reset back to generated layout.

Decision Visual Inspection

The /decisions/[decisionId] page provides an end-to-end read-only inspection view for one persisted governance decision. It is designed for operators who already have a decision ID from an API response, MCP tool result, audit trail, or investigation workflow.

The page includes:

• Decision summary and target metadata
• Outcome status, confidence, latest job/audit status, and metric scores
• Policy evaluation outcomes from the persisted reasoning read model
• Evidence graph rendered with React Flow
• Deterministic reasoning explanation timeline
• Ontology lineage graph rendered separately from the evidence graph
• Audit records and request/correlation metadata

Studio intentionally does not reconstruct policy or evidence semantics in the browser. It consumes backend read models and renders them directly.

Reviewing a Decision

A decision review should move from the outcome to the evidence and then back through ontology lineage. This keeps the operational question (“what happened?”) separate from the reasoning question (“why?”) and the traceability question (“what governed it?”).

1. Open /decisions and filter by status, target, or correlation ID.
2. Confirm the target, decision type, confidence, policy outcomes, and timestamps.
3. Use the evidence graph to inspect the facts and evaluation results used by the reasoning engine.
4. Read the explanation timeline and check that each policy outcome is supported by visible evidence.
5. Use Decision Lineage to follow the decision to its candidate, policy, actor, jobs, and other governed assets.
6. Check audit records and request/correlation metadata before recording a review conclusion.

Evidence and lineage answer different questions. The evidence graph is the bounded reasoning input for the decision; lineage is the broader ontology projection showing how the decision relates to governed entities. A graph node being present does not replace checking the persisted decision summary, policy result, or audit trail.

Access & Themes

Organization → Access presents actors as a searchable, paginated list. Selecting an actor shows friendly identity information, organization and project assignments, role descriptions, and assignment actions. This keeps large actor sets manageable without a single oversized dropdown.

Studio also includes a persistent light/dark theme toggle and remembers the collapsed sidebar across route changes. The account menu closes when the user clicks outside it or presses Escape; sign-out is an explicit action.