# rahesh-supersemantics/x-verba-governed-semantic-search architecture

> Architecture diagram of the GitHub repository rahesh-supersemantics/x-verba-governed-semantic-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahesh-supersemantics/x-verba-governed-semantic-search
- Repository: https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search

## Overview

This is a web application for semantic search over a knowledge base, with VSL governance controlling whether results are served automatically, routed for human review, or suspended. The main workflow runs from the user interface through the API, retrieval, governance decision, and an approved side effect. Separate governance endpoints expose status, ledger, audit, review queue, and human-authorized resume; a terminal CLI provides conformance, integrity, audit, and certification. Source excerpts show core calls, while some UI and route behavior is supported by the README rather than sampled frontend code.

Main entry points: [`backend/app.py`](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/app.py) (FastAPI routes), [`frontend/index.html`](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/frontend/index.html) (Search UI), [`backend/actions.py`](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/actions.py) (Search actions), [`governance/gates.py`](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/gates.py) (Governance gates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_frontend["Search UI<br/>[index.html]"]
end

subgraph group_search["Search service"]
  node_api["FastAPI routes<br/>[app.py]"]
  node_retrieval["Semantic retrieval<br/>[model.py]"]
  node_artifacts[("Search artifacts")]
  node_actions["Search actions<br/>[actions.py]"]
end

subgraph group_governance["Governance"]
  node_policy["Governance policy<br/>[policy.py]"]
  node_gates["Governance gates<br/>[gates.py]"]
  node_ledger[("Audit ledger<br/>[ledger.py]")]
end

subgraph group_operations["Review and audit"]
  node_answerlog[("Served-answer log<br/>[actions.py]")]
  node_queue["Human review queue<br/>[actions.py]"]
  node_auditcli["Audit CLI<br/>[audit_cli.py]"]
end

node_user(("Search user"))
node_reviewer(("Human reviewer"))

node_user -->|"submits query"| node_frontend
node_frontend -->|"calls search API"| node_api
node_api -->|"retrieves candidates"| node_retrieval
node_retrieval -->|"loads model and documents"| node_artifacts
node_api -->|"requests decision"| node_gates
node_gates -->|"enforces constructs"| node_policy
node_gates -->|"records decisions"| node_ledger
node_api -->|"commits approved outcome"| node_actions
node_actions -->|"appends served record"| node_answerlog
node_actions -->|"creates review ticket"| node_queue
node_queue -->|"awaits review"| node_reviewer
node_reviewer -.->|"reviews ticket"| node_frontend
node_frontend -->|"requests resume"| node_api
node_api -->|"requests re-enablement"| node_gates
node_api -->|"reads audit and history"| node_ledger
node_api -->|"reads review queue"| node_actions
node_auditcli -->|"verifies and audits"| node_ledger

click node_frontend "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/frontend/index.html"
click node_api "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/app.py"
click node_retrieval "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/model.py"
click node_artifacts "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/tree/main/artifacts"
click node_policy "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/policy.py"
click node_gates "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/gates.py"
click node_ledger "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/ledger.py"
click node_actions "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/actions.py"
click node_answerlog "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/actions.py"
click node_queue "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/actions.py"
click node_auditcli "https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/audit_cli.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_frontend,node_user,node_reviewer toneBlue
class node_api,node_retrieval,node_artifacts,node_actions toneAmber
class node_policy,node_gates,node_ledger toneMint
class node_answerlog,node_queue,node_auditcli toneRose
```

## Components

### Web interface

- [Search UI](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/frontend/index.html): `frontend/index.html`

### Search service

- [FastAPI routes](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/app.py): `backend/app.py`
- [Semantic retrieval](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/model.py): `backend/model.py`
- [Search artifacts](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/tree/main/artifacts): `artifacts`
- [Search actions](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/actions.py): `backend/actions.py`

### Governance

- [Governance policy](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/policy.py): `governance/policy.py`
- [Governance gates](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/gates.py): `governance/gates.py`
- [Audit ledger](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/ledger.py): `governance/ledger.py`

### Review and audit

- [Served-answer log](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/actions.py): `backend/actions.py`
- [Human review queue](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/backend/actions.py): `backend/actions.py`
- [Audit CLI](https://github.com/rahesh-supersemantics/x-verba-governed-semantic-search/blob/main/governance/audit_cli.py): `governance/audit_cli.py`

### Other components

- **Search user**
- **Human reviewer**

## Connections

- Search user → Search UI: submits query (evidence: `README.md`)
- Search UI → FastAPI routes: calls search API (evidence: `README.md`)
- FastAPI routes → Semantic retrieval: retrieves candidates (evidence: `backend/app.py`)
- Semantic retrieval → Search artifacts: loads model and documents (evidence: `backend/model.py`)
- FastAPI routes → Governance gates: requests decision (evidence: `backend/app.py`)
- Governance gates → Governance policy: enforces constructs (evidence: `governance/gates.py`)
- Governance gates → Audit ledger: records decisions (evidence: `governance/gates.py`)
- FastAPI routes → Search actions: commits approved outcome (evidence: `README.md`)
- Search actions → Served-answer log: appends served record (evidence: `backend/actions.py`)
- Search actions → Human review queue: creates review ticket (evidence: `backend/actions.py`)
- Human review queue → Human reviewer: awaits review (evidence: `README.md`)
- Human reviewer → Search UI: reviews ticket
- Search UI → FastAPI routes: requests resume (evidence: `README.md`)
- FastAPI routes → Governance gates: requests re-enablement (evidence: `backend/app.py`)
- FastAPI routes → Audit ledger: reads audit and history (evidence: `backend/app.py`)
- FastAPI routes → Search actions: reads review queue (evidence: `backend/app.py`)
- Audit CLI → Audit ledger: verifies and audits (evidence: `governance/audit_cli.py`)
