Architecture

Platform Overview

Kavach is a governance control plane for AI systems. It records governed AI assets, evaluates AI configurations, persists execution evidence, reconstructs history, analyzes quality change, ranks experiment candidates, and produces recommendations. It does not own prompt deployment, model deployment, infrastructure orchestration, or CI/CD execution.

The architecture keeps frameworks and infrastructure at the edge. Runtime systems can call into Kavach, but Kavach is not the runtime itself.

Architectural Planes

The system is organized into independent planes. Each plane owns a single responsibility and communicates only through explicit contracts.

Audit Plane

The Audit Plane captures workflow and node-level execution records. It stores the evidence required to understand what happened during an AI workflow and to reconstruct that workflow later.

Replay Plane

The Replay Plane reconstructs historical workflow executions from persisted audit state. Replay exists to support investigation, debugging, and governance review rather than to rerun live traffic.

Evaluation Plane

The Evaluation Plane turns workflow outputs into evaluation results. Providers such as TruLens sit here behind provider contracts. Evaluation exists to create governance evidence, not to be the platform boundary.

Job Execution Plane

The Job Execution Plane records and executes long-running governance work such as evaluation, experiment, replay, and drift analysis jobs. It owns Kavach job semantics such as idempotent submission, queued/running/succeeded/failed states, worker leases, retry attempts, cancellation, and immutable result references. It is not a workflow engine.

Persistence Plane

The Persistence Plane stores governed artifacts and evidence through repository contracts. Each repository type is backed by a factory class that selects the concrete implementation based on runtime configuration. SQLite is the current durable reference implementation. The architecture treats storage as replaceable.

History Plane

The History Plane retrieves persisted evaluations and organizes them into history views, trends, summaries, and comparisons. It provides the longitudinal view needed for governance decisions.

Governance Plane

The Governance Plane analyzes change over time. It compares evaluations, calculates drift, and produces governance-oriented artifacts from historical data. This plane interprets evidence; it does not execute deployments. Governed outcomes are represented by the GovernanceDecision domain model.

Governance Ontology Plane

The Governance Ontology Plane provides a semantic graph describing relationships between governed assets. It is the authoritative business model of Kavach; all storage models, APIs, graph projections, UI views, and AI reasoning are derived representations.

Settings Control Plane

The Settings Control Plane is a typed configuration resource with explicit SYSTEM, ORGANIZATION, and PROJECT scopes. Effective configuration follows environment > project > organization > system > default. Each scoped update uses compare-and-set with an expected version.

End-to-End Data Flow

The core experiment governance flow is:

Experiment
  → Experiment Candidate
  → Evaluation Run
  → Evaluation Result
  → Evaluation History
  → Comparison / Drift
  → Ranking
  → Leaderboard
  → Recommendation

Replaceable Components

Kavach keeps provider and storage choices behind contracts:

• Evaluation providers are pluggable.
• Repository implementations are pluggable, selected via factory classes.
• SQLite is a current durable backend, not the architectural center.
• REST, CLI, SDK, or MCP adapters can sit above services and framework-neutral APIs.

REST APIs

The current REST control plane exposes:

• /health and /ready for service checks
• /api/v1/providers for provider discovery
• /api/v1/prompts, /api/v1/models, /api/v1/datasets for registry reads
• /api/v1/evaluations for synchronous evaluation submission and persisted result reads
• /api/v1/experiments for experiment creation, candidates, runs, candidate comparisons, and leaderboards
• /api/v1/governance for comparison, drift analysis, and report lookup
• /api/v1/jobs for async governance job submission, status lookup, listing, cancellation, retry, and result references
• /api/v1/settings for typed configuration management
• /api/v1/decisions for governance decision evaluation and retrieval

Non-Goals

The architecture intentionally does not make Kavach responsible for:

• Prompt deployment
• Model deployment
• Runtime promotion
• Infrastructure management
• Web-server ownership
• CI/CD orchestration

Those systems can consume Kavach recommendations, but they remain outside the platform boundary.