# ascend-x/vidhaan architecture

> Architecture diagram of the GitHub repository ascend-x/vidhaan, 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/ascend-x/vidhaan
- Repository: https://github.com/ascend-x/vidhaan

## Overview

VIDHAAN is a digital evidence and case-management platform for law-enforcement and judicial workflows. Officers use the React application to manage cases, upload and search evidence, collaborate across departments, and review audit and compliance information; a separate victim portal supports privacy-conscious access. Document processing connects storage, AI analysis, search, and ledger integrity services. The graph follows the README’s documented architecture and upload lifecycle; several service implementations were not sampled, so their internal behavior is not inferred.

Main entry points: [`web/src/App.jsx`](https://github.com/ascend-x/vidhaan/blob/main/web/src/App.jsx) (React application), [`services/document-service/src/routes/documents.js`](https://github.com/ascend-x/vidhaan/blob/main/services/document-service/src/routes/documents.js) (Document management), [`services/ai-service/main.py`](https://github.com/ascend-x/vidhaan/blob/main/services/ai-service/main.py) (AI analysis), [`services/audit-service/src/index.js`](https://github.com/ascend-x/vidhaan/blob/main/services/audit-service/src/index.js) (Audit trail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client applications"]
  node_web["React application<br/>[App.jsx]"]
  node_portal["Victim portal UI<br/>[VictimPortal.jsx]"]
  node_api["API client<br/>[api.js]"]
end

subgraph group_identity["Access and gateway"]
  node_auth["Auth gateway<br/>[index.js]"]
  node_keycloak["Keycloak SSO"]
end

subgraph group_domain["Casework services"]
  node_cases["Case management<br/>[cases.js]"]
  node_documents["Document management<br/>[documents.js]"]
  node_workflow["Department workflows<br/>[index.js]"]
  node_notifications["Notifications<br/>[index.js]"]
  node_victimservice["Victim portal service<br/>[index.js]"]
end

subgraph group_processing["Evidence processing"]
  node_ai["AI analysis<br/>[main.py]"]
  node_search["Hybrid search<br/>[index.js]"]
  node_signing["Digital signing<br/>[main.py]"]
  node_ledger["Integrity ledger<br/>[index.js]"]
  node_audit["Audit trail<br/>[index.js]"]
  node_migration["Legacy migration<br/>[index.js]"]
  node_graph["Relationship graph<br/>[index.js]"]
end

subgraph group_platform["Data and integrations"]
  node_postgres[("PostgreSQL")]
  node_minio[("WORM object store")]
  node_kafka["Event bus"]
  node_opensearch[("OpenSearch")]
  node_trillian["Google Trillian"]
  node_neo4j[("Neo4j")]
end

node_officer(("Officer"))

node_officer -->|"uses"| node_web
node_web -->|"calls API"| node_api
node_api -.->|"routes via gateway"| node_auth
node_auth -->|"authenticates with"| node_keycloak
node_web -->|"routes requests"| node_cases
node_web -->|"uploads evidence"| node_documents
node_web -->|"searches evidence"| node_search
node_web -->|"starts handoffs"| node_workflow
node_web -->|"reviews activity"| node_audit
node_portal -->|"uses"| node_victimservice
node_documents -->|"stores evidence"| node_minio
node_documents -->|"requests analysis"| node_ai
node_documents -->|"writes records"| node_postgres
node_documents -->|"publishes events"| node_kafka
node_kafka -->|"delivers events"| node_ai
node_ai -->|"fetches files"| node_minio
node_ai -->|"indexes vectors"| node_opensearch
node_kafka -->|"delivers events"| node_ledger
node_ledger -->|"anchors hashes"| node_trillian
node_cases -->|"reads and writes"| node_postgres
node_workflow -->|"stores workflow data"| node_postgres
node_cases -->|"records activity"| node_audit
node_documents -->|"records activity"| node_audit
node_workflow -->|"records activity"| node_audit
node_search -->|"queries index"| node_opensearch
node_graph -->|"uses graph store"| node_neo4j
node_signing -->|"stores signing data"| node_postgres
node_signing -->|"uses object storage"| node_minio

click node_web "https://github.com/ascend-x/vidhaan/blob/main/web/src/App.jsx"
click node_portal "https://github.com/ascend-x/vidhaan/blob/main/web/src/pages/VictimPortal.jsx"
click node_api "https://github.com/ascend-x/vidhaan/blob/main/web/src/utils/api.js"
click node_auth "https://github.com/ascend-x/vidhaan/blob/main/services/auth-gateway/src/index.js"
click node_cases "https://github.com/ascend-x/vidhaan/blob/main/services/case-service/src/routes/cases.js"
click node_documents "https://github.com/ascend-x/vidhaan/blob/main/services/document-service/src/routes/documents.js"
click node_workflow "https://github.com/ascend-x/vidhaan/blob/main/services/workflow-service/src/index.js"
click node_notifications "https://github.com/ascend-x/vidhaan/blob/main/services/notification-service/src/index.js"
click node_victimservice "https://github.com/ascend-x/vidhaan/blob/main/services/victim-portal-service/src/index.js"
click node_ai "https://github.com/ascend-x/vidhaan/blob/main/services/ai-service/main.py"
click node_search "https://github.com/ascend-x/vidhaan/blob/main/services/search-service/src/index.js"
click node_signing "https://github.com/ascend-x/vidhaan/blob/main/services/signing-service/main.py"
click node_ledger "https://github.com/ascend-x/vidhaan/blob/main/services/ledger-service/src/index.js"
click node_audit "https://github.com/ascend-x/vidhaan/blob/main/services/audit-service/src/index.js"
click node_migration "https://github.com/ascend-x/vidhaan/blob/main/services/migration-service/src/index.js"
click node_graph "https://github.com/ascend-x/vidhaan/blob/main/services/graph-service/src/index.js"

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_web,node_portal,node_api toneBlue
class node_auth,node_keycloak toneAmber
class node_cases,node_documents,node_workflow,node_notifications,node_victimservice toneMint
class node_ai,node_search,node_signing,node_ledger,node_audit,node_migration,node_graph toneRose
class node_postgres,node_minio,node_kafka,node_opensearch,node_trillian,node_neo4j,node_officer toneIndigo
```

## Components

### Client applications

- [React application](https://github.com/ascend-x/vidhaan/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Victim portal UI](https://github.com/ascend-x/vidhaan/blob/main/web/src/pages/VictimPortal.jsx): `web/src/pages/VictimPortal.jsx`
- [API client](https://github.com/ascend-x/vidhaan/blob/main/web/src/utils/api.js): `web/src/utils/api.js`

### Access and gateway

- [Auth gateway](https://github.com/ascend-x/vidhaan/blob/main/services/auth-gateway/src/index.js): `services/auth-gateway/src/index.js`
- **Keycloak SSO**

### Casework services

- [Case management](https://github.com/ascend-x/vidhaan/blob/main/services/case-service/src/routes/cases.js): `services/case-service/src/routes/cases.js`
- [Document management](https://github.com/ascend-x/vidhaan/blob/main/services/document-service/src/routes/documents.js): `services/document-service/src/routes/documents.js`
- [Department workflows](https://github.com/ascend-x/vidhaan/blob/main/services/workflow-service/src/index.js): `services/workflow-service/src/index.js`
- [Notifications](https://github.com/ascend-x/vidhaan/blob/main/services/notification-service/src/index.js): `services/notification-service/src/index.js`
- [Victim portal service](https://github.com/ascend-x/vidhaan/blob/main/services/victim-portal-service/src/index.js): `services/victim-portal-service/src/index.js`

### Evidence processing

- [AI analysis](https://github.com/ascend-x/vidhaan/blob/main/services/ai-service/main.py): `services/ai-service/main.py`
- [Hybrid search](https://github.com/ascend-x/vidhaan/blob/main/services/search-service/src/index.js): `services/search-service/src/index.js`
- [Digital signing](https://github.com/ascend-x/vidhaan/blob/main/services/signing-service/main.py): `services/signing-service/main.py`
- [Integrity ledger](https://github.com/ascend-x/vidhaan/blob/main/services/ledger-service/src/index.js): `services/ledger-service/src/index.js`
- [Audit trail](https://github.com/ascend-x/vidhaan/blob/main/services/audit-service/src/index.js): `services/audit-service/src/index.js`
- [Legacy migration](https://github.com/ascend-x/vidhaan/blob/main/services/migration-service/src/index.js): `services/migration-service/src/index.js`
- [Relationship graph](https://github.com/ascend-x/vidhaan/blob/main/services/graph-service/src/index.js): `services/graph-service/src/index.js`

### Data and integrations

- **PostgreSQL**
- **WORM object store**
- **Event bus**
- **OpenSearch**
- **Google Trillian**
- **Neo4j**

### Other components

- **Officer**

## Connections

- Officer → React application: uses (evidence: `README.md`)
- React application → API client: calls API (evidence: `web/src/App.jsx`)
- API client → Auth gateway: routes via gateway
- Auth gateway → Keycloak SSO: authenticates with (evidence: `README.md`)
- React application → Case management: routes requests (evidence: `README.md`)
- React application → Document management: uploads evidence (evidence: `README.md`)
- React application → Hybrid search: searches evidence (evidence: `README.md`)
- React application → Department workflows: starts handoffs (evidence: `README.md`)
- React application → Audit trail: reviews activity (evidence: `README.md`)
- Victim portal UI → Victim portal service: uses (evidence: `README.md`)
- Document management → WORM object store: stores evidence (evidence: `README.md`)
- Document management → AI analysis: requests analysis (evidence: `services/document-service/src/routes/documents.js`)
- Document management → PostgreSQL: writes records (evidence: `README.md`)
- Document management → Event bus: publishes events (evidence: `README.md`)
- Event bus → AI analysis: delivers events (evidence: `README.md`)
- AI analysis → WORM object store: fetches files (evidence: `README.md`)
- AI analysis → OpenSearch: indexes vectors (evidence: `README.md`)
- Event bus → Integrity ledger: delivers events (evidence: `README.md`)
- Integrity ledger → Google Trillian: anchors hashes (evidence: `README.md`)
- Case management → PostgreSQL: reads and writes (evidence: `README.md`)
- Department workflows → PostgreSQL: stores workflow data (evidence: `README.md`)
- Case management → Audit trail: records activity (evidence: `README.md`)
- Document management → Audit trail: records activity (evidence: `README.md`)
- Department workflows → Audit trail: records activity (evidence: `README.md`)
- Hybrid search → OpenSearch: queries index (evidence: `README.md`)
- Relationship graph → Neo4j: uses graph store (evidence: `README.md`)
- Digital signing → PostgreSQL: stores signing data (evidence: `README.md`)
- Digital signing → WORM object store: uses object storage (evidence: `README.md`)
