# himanshuupadhyay029-sys/onpremsih117 architecture

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

- Interactive diagram: https://gitdiagram.com/himanshuupadhyay029-sys/onpremsih117
- Repository: https://github.com/himanshuupadhyay029-sys/onpremsih117

## Overview

KAVACH is an on-premise engineering workbench. An operator submits a task in the React console; the FastAPI service hands work to a LangGraph agent, which plans and routes steps to local models, the knowledge vault, or task tools, then returns results for review. Separate console capabilities cover vault management, approvals, audit, and administration. PostgreSQL stores application records, while audit logs and host monitoring/firewall controls provide operational safeguards. The graph reflects documented capabilities and indexed imports; unsampled endpoint and internal details are represented only where relationships are documented.

Main entry points: [`kavach/backend/main.py`](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/main.py) (FastAPI service), [`kavach/backend/brain/agent.py`](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/agent.py) (LangGraph agent), [`kavach/backend/brain/tools_dispatch.py`](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/tools_dispatch.py) (Tool dispatch), [`kavach/frontend-react/src/App.jsx`](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/App.jsx) (React console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operator console"]
  node_console["React console<br/>[App.jsx]"]
  node_taskui["Task workspace<br/>[NewTaskScreen.jsx]"]
  node_vaultui["Vault screen"]
  node_approvalui["Approval screen"]
  node_auditui["Audit screen<br/>[AuditLogScreen.jsx]"]
  node_adminui["Admin screens"]
end

subgraph group_service["API and agent"]
  node_api["FastAPI service<br/>[main.py]"]
  node_auth["Authentication<br/>[routes.py]"]
  node_agent["LangGraph agent<br/>[agent.py]"]
  node_router["Task routing<br/>[router.py]"]
  node_dispatch["Tool dispatch<br/>[tools_dispatch.py]"]
  node_registry["Model registry<br/>[registry.py]"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_vaultingest["Vault ingestion<br/>[ingest.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieve.py]"]
  node_search["Grounded search<br/>[search.py]"]
  node_ocr["OCR<br/>[ocr.py]"]
  node_vision["Image analysis<br/>[vision.py]"]
  node_calc["Calculation<br/>[calc.py]"]
  node_code["Code execution<br/>[code.py]"]
  node_sandbox["Docker sandbox<br/>[sandbox.py]"]
  node_deliverables["Office generation<br/>[writer.py]"]
end

subgraph group_controls["Records and controls"]
  node_approval["Approval gate<br/>[approve.py]"]
  node_audit[("Hash-chain audit<br/>[logbook.py]")]
  node_database[("PostgreSQL records<br/>[models.py]")]
  node_shield["Host protections<br/>[monitor.py]"]
end

subgraph group_local["Local services"]
  node_ollama["Ollama models"]
  node_postgres[("PostgreSQL")]
  node_docker["Docker runtime"]
end

node_operator(("Operator"))

node_operator -->|"submits tasks"| node_console
node_console -->|"renders"| node_taskui
node_taskui -.->|"sends requests"| node_api
node_console -->|"checks session"| node_api
node_api -->|"invokes"| node_agent
node_agent -->|"routes tasks"| node_router
node_agent -->|"dispatches steps"| node_dispatch
node_agent -->|"selects models"| node_registry
node_registry -->|"lists models"| node_ollama
node_agent -->|"runs inference"| node_ollama
node_vaultui -.->|"manages documents"| node_api
node_api -.->|"ingests uploads"| node_vaultingest
node_vaultingest -->|"extracts scans"| node_ocr
node_search -->|"retrieves passages"| node_retrieval
node_dispatch -->|"dispatches search"| node_search
node_dispatch -->|"dispatches OCR"| node_ocr
node_dispatch -->|"dispatches vision"| node_vision
node_dispatch -->|"dispatches calculation"| node_calc
node_dispatch -->|"dispatches code"| node_code
node_code -.->|"executes in"| node_sandbox
node_sandbox -.->|"starts containers"| node_docker
node_dispatch -->|"dispatches authoring"| node_deliverables
node_agent -->|"requests review"| node_approval
node_approvalui -.->|"reviews drafts"| node_approval
node_agent -.->|"persists run state"| node_database
node_api -->|"mounts routes"| node_auth
node_auth -->|"reads users"| node_database
node_database -->|"stores records"| node_postgres
node_agent -->|"records events"| node_audit
node_approval -->|"records decisions"| node_audit
node_auditui -.->|"views audit"| node_api
node_adminui -.->|"administers users"| node_api
node_api -->|"exposes controls"| node_shield

click node_console "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/App.jsx"
click node_taskui "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/NewTaskScreen.jsx"
click node_vaultui "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/KnowledgeVaultScreen.jsx"
click node_approvalui "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/ApprovalsScreen.jsx"
click node_auditui "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/AuditLogScreen.jsx"
click node_adminui "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/UserManagementScreen.jsx"
click node_api "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/main.py"
click node_auth "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/auth/routes.py"
click node_agent "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/agent.py"
click node_router "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/router.py"
click node_dispatch "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/tools_dispatch.py"
click node_registry "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/engine/registry.py"
click node_vaultingest "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/vault/ingest.py"
click node_retrieval "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/vault/retrieve.py"
click node_search "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/search.py"
click node_ocr "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/ocr.py"
click node_vision "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/vision.py"
click node_calc "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/calc.py"
click node_code "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/code.py"
click node_sandbox "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/sandbox.py"
click node_deliverables "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/writer.py"
click node_approval "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/guard/approve.py"
click node_audit "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/audit/logbook.py"
click node_database "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/db/models.py"
click node_shield "https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/shield/monitor.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_console,node_taskui,node_vaultui,node_approvalui,node_auditui,node_adminui toneBlue
class node_api,node_auth,node_agent,node_router,node_dispatch,node_registry toneAmber
class node_vaultingest,node_retrieval,node_search,node_ocr,node_vision,node_calc,node_code,node_sandbox,node_deliverables toneMint
class node_approval,node_audit,node_database,node_shield toneRose
class node_ollama,node_postgres,node_docker,node_operator toneIndigo
```

## Components

### Operator console

- [React console](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/App.jsx): `kavach/frontend-react/src/App.jsx`
- [Task workspace](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/NewTaskScreen.jsx): `kavach/frontend-react/src/components/NewTaskScreen.jsx`
- [Vault screen](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/KnowledgeVaultScreen.jsx): `kavach/frontend-react/src/components/KnowledgeVaultScreen.jsx`
- [Approval screen](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/ApprovalsScreen.jsx): `kavach/frontend-react/src/components/ApprovalsScreen.jsx`
- [Audit screen](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/AuditLogScreen.jsx): `kavach/frontend-react/src/components/AuditLogScreen.jsx`
- [Admin screens](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/frontend-react/src/components/UserManagementScreen.jsx): `kavach/frontend-react/src/components/UserManagementScreen.jsx`

### API and agent

- [FastAPI service](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/main.py): `kavach/backend/main.py`
- [Authentication](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/auth/routes.py): `kavach/backend/auth/routes.py`
- [LangGraph agent](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/agent.py): `kavach/backend/brain/agent.py`
- [Task routing](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/router.py): `kavach/backend/brain/router.py`
- [Tool dispatch](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/brain/tools_dispatch.py): `kavach/backend/brain/tools_dispatch.py`
- [Model registry](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/engine/registry.py): `kavach/backend/engine/registry.py`

### Knowledge and tools

- [Vault ingestion](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/vault/ingest.py): `kavach/backend/vault/ingest.py`
- [Hybrid retrieval](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/vault/retrieve.py): `kavach/backend/vault/retrieve.py`
- [Grounded search](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/search.py): `kavach/backend/tools/search.py`
- [OCR](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/ocr.py): `kavach/backend/tools/ocr.py`
- [Image analysis](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/vision.py): `kavach/backend/tools/vision.py`
- [Calculation](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/calc.py): `kavach/backend/tools/calc.py`
- [Code execution](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/code.py): `kavach/backend/tools/code.py`
- [Docker sandbox](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/sandbox.py): `kavach/backend/tools/sandbox.py`
- [Office generation](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/tools/writer.py): `kavach/backend/tools/writer.py`

### Records and controls

- [Approval gate](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/guard/approve.py): `kavach/backend/guard/approve.py`
- [Hash-chain audit](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/audit/logbook.py): `kavach/backend/audit/logbook.py`
- [PostgreSQL records](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/db/models.py): `kavach/backend/db/models.py`
- [Host protections](https://github.com/himanshuupadhyay029-sys/onpremsih117/blob/main/kavach/backend/shield/monitor.py): `kavach/backend/shield/monitor.py`

### Local services

- **Ollama models**
- **PostgreSQL**
- **Docker runtime**

### Other components

- **Operator**

## Connections

- Operator → React console: submits tasks (evidence: `README.md`)
- React console → Task workspace: renders (evidence: `kavach/frontend-react/src/App.jsx`)
- Task workspace → FastAPI service: sends requests (evidence: `README.md`)
- React console → FastAPI service: checks session (evidence: `kavach/frontend-react/src/App.jsx`)
- FastAPI service → LangGraph agent: invokes (evidence: `kavach/backend/main.py`)
- LangGraph agent → Task routing: routes tasks (evidence: `kavach/backend/brain/agent.py`)
- LangGraph agent → Tool dispatch: dispatches steps (evidence: `kavach/backend/brain/agent.py`)
- LangGraph agent → Model registry: selects models (evidence: `kavach/backend/brain/agent.py`)
- Model registry → Ollama models: lists models (evidence: `kavach/backend/engine/registry.py`)
- LangGraph agent → Ollama models: runs inference (evidence: `README.md`)
- Vault screen → FastAPI service: manages documents (evidence: `README.md`)
- FastAPI service → Vault ingestion: ingests uploads (evidence: `README.md`)
- Vault ingestion → OCR: extracts scans (evidence: `kavach/backend/vault/ingest.py`)
- Grounded search → Hybrid retrieval: retrieves passages (evidence: `kavach/backend/tools/search.py`)
- Tool dispatch → Grounded search: dispatches search (evidence: `kavach/backend/brain/tools_dispatch.py`)
- Tool dispatch → OCR: dispatches OCR (evidence: `kavach/backend/brain/tools_dispatch.py`)
- Tool dispatch → Image analysis: dispatches vision (evidence: `kavach/backend/brain/tools_dispatch.py`)
- Tool dispatch → Calculation: dispatches calculation (evidence: `kavach/backend/brain/tools_dispatch.py`)
- Tool dispatch → Code execution: dispatches code (evidence: `kavach/backend/brain/tools_dispatch.py`)
- Code execution → Docker sandbox: executes in (evidence: `README.md`)
- Docker sandbox → Docker runtime: starts containers (evidence: `README.md`)
- Tool dispatch → Office generation: dispatches authoring (evidence: `kavach/backend/brain/tools_dispatch.py`)
- LangGraph agent → Approval gate: requests review (evidence: `kavach/backend/brain/agent.py`)
- Approval screen → Approval gate: reviews drafts (evidence: `README.md`)
- LangGraph agent → PostgreSQL records: persists run state (evidence: `README.md`)
- FastAPI service → Authentication: mounts routes (evidence: `kavach/backend/main.py`)
- Authentication → PostgreSQL records: reads users (evidence: `kavach/backend/auth/routes.py`)
- PostgreSQL records → PostgreSQL: stores records
- LangGraph agent → Hash-chain audit: records events (evidence: `kavach/backend/brain/agent.py`)
- Approval gate → Hash-chain audit: records decisions (evidence: `kavach/backend/guard/approve.py`)
- Audit screen → FastAPI service: views audit (evidence: `README.md`)
- Admin screens → FastAPI service: administers users (evidence: `README.md`)
- FastAPI service → Host protections: exposes controls (evidence: `kavach/backend/main.py`)
