# bhanuj-ai/ai-governance-oss architecture

> Architecture diagram of the GitHub repository bhanuj-ai/ai-governance-oss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhanuj-ai/ai-governance-oss
- Repository: https://github.com/bhanuj-ai/ai-governance-oss

## Overview

BHANUJ is an AI governance control plane: it observes externally owned AI activity, evaluates evidence and policy, records explainable decisions and lineage, and supports evaluation, causal audits, interventions, and controlled replay. The REST API is the central runtime entry point; the Studio and MCP clients initiate review and governance operations. The README documents major capabilities that are not individually sampled, so those subsystems are represented at their exact enclosing directories; arrows are limited to relationships visible in the README or sampled source index/excerpts.

Main entry points: [`src/ai_governance/api/app.py`](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/api/app.py) (REST control plane), [`src/ai_governance/decisions`](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/decisions) (Decision engine), [`src/ai_governance/domain/causal_audit`](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/causal_audit) (Causal audit), [`src/ai_governance/domain/agent_execution`](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/agent_execution) (Agent executions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access &amp; Control"]
  node_rest["REST control plane<br/>[app.py]"]
  node_auth_tenancy["Identity &amp; tenancy"]
  node_jobs["Async jobs"]
  node_events["Events &amp; integrations"]
  node_persistence[("Persistence adapters")]
end

subgraph group_govern["Governance Decisions"]
  node_decisions["Decision engine"]
  node_policies["Policy engine<br/>[policies.py]"]
  node_audit["Audit &amp; lineage<br/>[audit.py]"]
end

subgraph group_evidence["Knowledge &amp; Evidence"]
  node_assets["Asset registries"]
  node_ontology[("Governance ontology")]
end

subgraph group_runtime["Runtime &amp; Evaluation"]
  node_execution["Agent executions"]
  node_evaluation["Evaluation"]
  node_experiments["Experiments"]
  node_findings["Runtime findings"]
  node_causal["Causal audit"]
  node_interventions["Evidence interventions"]
  node_replay["Controlled replay"]
end

subgraph group_interfaces["Product Interfaces"]
  node_studio["AIGP Studio"]
  node_mcp["MCP server<br/>[server.py]"]
  node_graph_ui["Ontology explorer<br/>[GraphExplorer.tsx]"]
  node_causal_ui["Causal audit views"]
  node_policy_ui["Policy management"]
  node_mcp_client["MCP tool client<br/>[rest_client.py]"]
end

node_user(("Governance user"))
node_runtime_owner(("AI runtime owner"))

node_user -->|"reviews"| node_studio
node_studio -.->|"requests"| node_rest
node_rest -->|"enforces access"| node_auth_tenancy
node_runtime_owner -->|"provides evidence"| node_execution
node_rest -->|"wires services"| node_assets
node_rest -->|"routes queries"| node_ontology
node_ontology -.->|"queries graph"| node_persistence
node_rest -.->|"governs outcomes"| node_decisions
node_decisions -->|"evaluates rules"| node_policies
node_decisions -->|"preserves lineage"| node_audit
node_rest -->|"routes executions"| node_execution
node_rest -.->|"routes evaluation"| node_evaluation
node_rest -->|"wires experiments"| node_experiments
node_experiments -->|"uses evaluation"| node_evaluation
node_execution -.->|"emits findings"| node_findings
node_rest -.->|"routes audits"| node_causal
node_causal -->|"applies policy"| node_interventions
node_causal -->|"runs controlled replay"| node_replay
node_replay -->|"executes in runtime"| node_runtime_owner
node_rest -.->|"submits work"| node_jobs
node_rest -->|"installs telemetry"| node_events
node_rest -->|"wires repositories"| node_persistence
node_mcp -->|"uses REST client"| node_mcp_client
node_mcp_client -.->|"calls API"| node_rest
node_user -->|"explores lineage"| node_graph_ui
node_user -->|"reviews findings"| node_causal_ui
node_user -->|"manages policies"| node_policy_ui
node_graph_ui -.->|"queries graph"| node_rest
node_causal_ui -.->|"requests audits"| node_rest
node_policy_ui -.->|"requests policy"| node_rest

click node_studio "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/console/components"
click node_rest "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/api/app.py"
click node_auth_tenancy "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/tenancy"
click node_mcp "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/mcp/server.py"
click node_assets "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/api/dependencies"
click node_ontology "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/ontology"
click node_decisions "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/decisions"
click node_policies "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/decisions/policies.py"
click node_audit "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/api/routers/audit.py"
click node_execution "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/agent_execution"
click node_evaluation "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/evaluation"
click node_experiments "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/services/experiment_api_service.py"
click node_findings "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/runtime_findings"
click node_causal "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/causal_audit"
click node_interventions "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/domain/causal_audit/intervention_policy.py"
click node_replay "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/replay"
click node_jobs "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/jobs"
click node_events "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/events"
click node_persistence "https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/repositories"
click node_graph_ui "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/console/components/graph/GraphExplorer.tsx"
click node_causal_ui "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/console/components/agent-runtime/CausalAuditPage.tsx"
click node_policy_ui "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/console/components/policies/PolicyEnginePages.tsx"
click node_mcp_client "https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/mcp/clients/rest_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rest,node_auth_tenancy,node_jobs,node_events,node_persistence,node_user toneBlue
class node_decisions,node_policies,node_audit toneAmber
class node_assets,node_ontology toneMint
class node_execution,node_evaluation,node_experiments,node_findings,node_causal,node_interventions,node_replay toneRose
class node_studio,node_mcp,node_graph_ui,node_causal_ui,node_policy_ui,node_mcp_client,node_runtime_owner toneIndigo
```

## Components

### Access & Control

- [REST control plane](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/api/app.py): `src/ai_governance/api/app.py`
- [Identity & tenancy](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/tenancy): `src/ai_governance/tenancy`
- [Async jobs](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/jobs): `src/ai_governance/domain/jobs`
- [Events & integrations](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/events): `src/ai_governance/events`
- [Persistence adapters](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/repositories): `src/ai_governance/repositories`

### Governance Decisions

- [Decision engine](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/decisions): `src/ai_governance/decisions`
- [Policy engine](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/decisions/policies.py): `src/ai_governance/decisions/policies.py`
- [Audit & lineage](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/api/routers/audit.py): `src/ai_governance/api/routers/audit.py`

### Knowledge & Evidence

- [Asset registries](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/api/dependencies): `src/ai_governance/api/dependencies`
- [Governance ontology](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/ontology): `src/ai_governance/ontology`

### Runtime & Evaluation

- [Agent executions](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/agent_execution): `src/ai_governance/domain/agent_execution`
- [Evaluation](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/evaluation): `src/ai_governance/evaluation`
- [Experiments](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/services/experiment_api_service.py): `src/ai_governance/services/experiment_api_service.py`
- [Runtime findings](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/runtime_findings): `src/ai_governance/domain/runtime_findings`
- [Causal audit](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/causal_audit): `src/ai_governance/domain/causal_audit`
- [Evidence interventions](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/domain/causal_audit/intervention_policy.py): `src/ai_governance/domain/causal_audit/intervention_policy.py`
- [Controlled replay](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/src/ai_governance/domain/replay): `src/ai_governance/domain/replay`

### Product Interfaces

- [AIGP Studio](https://github.com/bhanuj-ai/ai-governance-oss/tree/main/console/components): `console/components`
- [MCP server](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/mcp/server.py): `src/ai_governance/mcp/server.py`
- [Ontology explorer](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/console/components/graph/GraphExplorer.tsx): `console/components/graph/GraphExplorer.tsx`
- [Causal audit views](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/console/components/agent-runtime/CausalAuditPage.tsx): `console/components/agent-runtime/CausalAuditPage.tsx`
- [Policy management](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/console/components/policies/PolicyEnginePages.tsx): `console/components/policies/PolicyEnginePages.tsx`
- [MCP tool client](https://github.com/bhanuj-ai/ai-governance-oss/blob/main/src/ai_governance/mcp/clients/rest_client.py): `src/ai_governance/mcp/clients/rest_client.py`

### Other components

- **Governance user**
- **AI runtime owner**

## Connections

- Governance user → AIGP Studio: reviews (evidence: `README.md`)
- AIGP Studio → REST control plane: requests
- REST control plane → Identity & tenancy: enforces access (evidence: `src/ai_governance/api/app.py`)
- AI runtime owner → Agent executions: provides evidence (evidence: `README.md`)
- REST control plane → Asset registries: wires services (evidence: `src/ai_governance/api/dependencies/__init__.py`)
- REST control plane → Governance ontology: routes queries (evidence: `src/ai_governance/api/app.py`)
- Governance ontology → Persistence adapters: queries graph
- REST control plane → Decision engine: governs outcomes
- Decision engine → Policy engine: evaluates rules (evidence: `README.md`)
- Decision engine → Audit & lineage: preserves lineage (evidence: `README.md`)
- REST control plane → Agent executions: routes executions (evidence: `src/ai_governance/api/app.py`)
- REST control plane → Evaluation: routes evaluation
- REST control plane → Experiments: wires experiments
- Experiments → Evaluation: uses evaluation (evidence: `src/ai_governance/services/experiment_api_service.py`)
- Agent executions → Runtime findings: emits findings
- REST control plane → Causal audit: routes audits
- Causal audit → Evidence interventions: applies policy (evidence: `README.md`)
- Causal audit → Controlled replay: runs controlled replay (evidence: `README.md`)
- Controlled replay → AI runtime owner: executes in runtime (evidence: `README.md`)
- REST control plane → Async jobs: submits work
- REST control plane → Events & integrations: installs telemetry (evidence: `src/ai_governance/api/app.py`)
- REST control plane → Persistence adapters: wires repositories
- MCP server → MCP tool client: uses REST client (evidence: `src/ai_governance/mcp/server.py`)
- MCP tool client → REST control plane: calls API
- Governance user → Ontology explorer: explores lineage (evidence: `README.md`)
- Governance user → Causal audit views: reviews findings (evidence: `README.md`)
- Governance user → Policy management: manages policies (evidence: `README.md`)
- Ontology explorer → REST control plane: queries graph
- Causal audit views → REST control plane: requests audits
- Policy management → REST control plane: requests policy
