# aakarsh1506/evidex architecture

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

- Interactive diagram: https://gitdiagram.com/aakarsh1506/evidex
- Repository: https://github.com/aakarsh1506/evidex

## Overview

EVIDEX is a criminal-record and network-analysis application: officers authenticate, browse profiles and case statistics, upload documents or database exports, review extracted entities and links, then save reviewed records for network analysis and investigator search. The React application calls the FastAPI API; the README also documents an Express alternative, which is not present in this file tree. Document processing is an asynchronous, review-gated workflow, with PostgreSQL for records and job state and Neo4j for graph relationships. Major analysis and AI capabilities are represented at their documented module boundaries; unsampled route wiring is not expanded.

Main entry points: [`backend/services/ingestion.py`](https://github.com/aakarsh1506/evidex/blob/main/backend/services/ingestion.py) (Ingestion worker), [`backend/app.py`](https://github.com/aakarsh1506/evidex/blob/main/backend/app.py) (FastAPI app), [`backend/routes/documents.py`](https://github.com/aakarsh1506/evidex/blob/main/backend/routes/documents.py) (Document routes), [`backend/routes`](https://github.com/aakarsh1506/evidex/tree/main/backend/routes) (Workspace and stats)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Officer application"]
  node_app["React app<br/>[App.jsx]"]
  node_pages["Officer pages"]
  node_api_client["API clients"]
end

subgraph group_api["API and identity"]
  node_api_app["FastAPI app<br/>[app.py]"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_document_routes["Document routes<br/>[documents.py]"]
  node_record_routes["Record routes<br/>[criminals.py]"]
  node_other_routes["Workspace and stats"]
end

subgraph group_docs["Document processing"]
  node_ingestion["Ingestion worker<br/>[ingestion.py]"]
  node_document_text["Text extraction<br/>[document_text.py]"]
  node_database_import["Export import<br/>[database_import.py]"]
  node_extraction["Entity extraction<br/>[extraction.py]"]
  node_review["Review and resolution<br/>[entity_review.py]"]
  node_ingestion_store["Record and graph writes<br/>[ingestion_store.py]"]
  node_document_files["Document files<br/>[document_files.py]"]
end

subgraph group_analysis["Records and analysis"]
  node_profiles["Criminal profiles<br/>[profile_record.py]"]
  node_network["Network analysis<br/>[network.py]"]
  node_investigator["Investigator analysis"]
  node_insight["AI insights<br/>[insight.py]"]
end

subgraph group_stores["Persistence and AI"]
  node_postgres[("PostgreSQL<br/>[db.py]")]
  node_neo4j[("Neo4j graph<br/>[neo4j_driver.py]")]
  node_rag["Document search<br/>[rag.py]"]
end

node_officer(("Officer"))
node_ollama["Ollama"]
node_groq["Groq"]

node_officer -->|"uses"| node_app
node_app -->|"renders"| node_pages
node_pages -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"dispatches"| node_auth_routes
node_api_app -->|"dispatches"| node_document_routes
node_api_app -->|"dispatches"| node_record_routes
node_api_app -->|"dispatches"| node_other_routes
node_auth_routes -->|"reads officers"| node_postgres
node_document_routes -->|"queues jobs"| node_ingestion
node_ingestion -->|"loads files"| node_document_files
node_ingestion -->|"extracts text"| node_document_text
node_ingestion -->|"parses exports"| node_database_import
node_ingestion -->|"extracts entities"| node_extraction
node_ingestion -->|"indexes text"| node_rag
node_ingestion -->|"persists review"| node_ingestion_store
node_ingestion -->|"queues and updates"| node_postgres
node_ingestion_store -->|"writes records"| node_postgres
node_ingestion_store -->|"syncs graph"| node_neo4j
node_document_routes -->|"reviews identities"| node_review
node_record_routes -->|"serves profiles"| node_profiles
node_other_routes -->|"serves analysis"| node_network
node_other_routes -->|"serves queries"| node_investigator
node_investigator -->|"searches documents"| node_rag
node_investigator -->|"queries graph"| node_neo4j
node_insight -.->|"uses model"| node_ollama
node_insight -.->|"uses model"| node_groq

click node_app "https://github.com/aakarsh1506/evidex/blob/main/frontend/src/App.jsx"
click node_pages "https://github.com/aakarsh1506/evidex/tree/main/frontend/src/pages"
click node_api_client "https://github.com/aakarsh1506/evidex/tree/main/frontend/src/api"
click node_api_app "https://github.com/aakarsh1506/evidex/blob/main/backend/app.py"
click node_auth_routes "https://github.com/aakarsh1506/evidex/blob/main/backend/routes/auth.py"
click node_document_routes "https://github.com/aakarsh1506/evidex/blob/main/backend/routes/documents.py"
click node_record_routes "https://github.com/aakarsh1506/evidex/blob/main/backend/routes/criminals.py"
click node_other_routes "https://github.com/aakarsh1506/evidex/tree/main/backend/routes"
click node_ingestion "https://github.com/aakarsh1506/evidex/blob/main/backend/services/ingestion.py"
click node_document_text "https://github.com/aakarsh1506/evidex/blob/main/backend/services/document_text.py"
click node_database_import "https://github.com/aakarsh1506/evidex/blob/main/backend/services/database_import.py"
click node_extraction "https://github.com/aakarsh1506/evidex/blob/main/backend/services/extraction.py"
click node_review "https://github.com/aakarsh1506/evidex/blob/main/backend/services/entity_review.py"
click node_ingestion_store "https://github.com/aakarsh1506/evidex/blob/main/backend/services/ingestion_store.py"
click node_document_files "https://github.com/aakarsh1506/evidex/blob/main/backend/services/document_files.py"
click node_profiles "https://github.com/aakarsh1506/evidex/blob/main/backend/services/profile_record.py"
click node_network "https://github.com/aakarsh1506/evidex/blob/main/backend/services/network.py"
click node_investigator "https://github.com/aakarsh1506/evidex/blob/main/backend/services/investigator_chat.py"
click node_insight "https://github.com/aakarsh1506/evidex/blob/main/backend/services/insight.py"
click node_postgres "https://github.com/aakarsh1506/evidex/blob/main/backend/db.py"
click node_neo4j "https://github.com/aakarsh1506/evidex/blob/main/backend/neo4j_driver.py"
click node_rag "https://github.com/aakarsh1506/evidex/blob/main/backend/services/rag.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_app,node_pages,node_api_client toneBlue
class node_api_app,node_auth_routes,node_document_routes,node_record_routes,node_other_routes toneAmber
class node_ingestion,node_document_text,node_database_import,node_extraction,node_review,node_ingestion_store,node_document_files toneMint
class node_profiles,node_network,node_investigator,node_insight toneRose
class node_postgres,node_neo4j,node_rag,node_officer,node_ollama,node_groq toneIndigo
```

## Components

### Officer application

- [React app](https://github.com/aakarsh1506/evidex/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Officer pages](https://github.com/aakarsh1506/evidex/tree/main/frontend/src/pages): `frontend/src/pages`
- [API clients](https://github.com/aakarsh1506/evidex/tree/main/frontend/src/api): `frontend/src/api`

### API and identity

- [FastAPI app](https://github.com/aakarsh1506/evidex/blob/main/backend/app.py): `backend/app.py`
- [Authentication](https://github.com/aakarsh1506/evidex/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Document routes](https://github.com/aakarsh1506/evidex/blob/main/backend/routes/documents.py): `backend/routes/documents.py`
- [Record routes](https://github.com/aakarsh1506/evidex/blob/main/backend/routes/criminals.py): `backend/routes/criminals.py`
- [Workspace and stats](https://github.com/aakarsh1506/evidex/tree/main/backend/routes): `backend/routes`

### Document processing

- [Ingestion worker](https://github.com/aakarsh1506/evidex/blob/main/backend/services/ingestion.py): `backend/services/ingestion.py`
- [Text extraction](https://github.com/aakarsh1506/evidex/blob/main/backend/services/document_text.py): `backend/services/document_text.py`
- [Export import](https://github.com/aakarsh1506/evidex/blob/main/backend/services/database_import.py): `backend/services/database_import.py`
- [Entity extraction](https://github.com/aakarsh1506/evidex/blob/main/backend/services/extraction.py): `backend/services/extraction.py`
- [Review and resolution](https://github.com/aakarsh1506/evidex/blob/main/backend/services/entity_review.py): `backend/services/entity_review.py`
- [Record and graph writes](https://github.com/aakarsh1506/evidex/blob/main/backend/services/ingestion_store.py): `backend/services/ingestion_store.py`
- [Document files](https://github.com/aakarsh1506/evidex/blob/main/backend/services/document_files.py): `backend/services/document_files.py`

### Records and analysis

- [Criminal profiles](https://github.com/aakarsh1506/evidex/blob/main/backend/services/profile_record.py): `backend/services/profile_record.py`
- [Network analysis](https://github.com/aakarsh1506/evidex/blob/main/backend/services/network.py): `backend/services/network.py`
- [Investigator analysis](https://github.com/aakarsh1506/evidex/blob/main/backend/services/investigator_chat.py): `backend/services/investigator_chat.py`
- [AI insights](https://github.com/aakarsh1506/evidex/blob/main/backend/services/insight.py): `backend/services/insight.py`

### Persistence and AI

- [PostgreSQL](https://github.com/aakarsh1506/evidex/blob/main/backend/db.py): `backend/db.py`
- [Neo4j graph](https://github.com/aakarsh1506/evidex/blob/main/backend/neo4j_driver.py): `backend/neo4j_driver.py`
- [Document search](https://github.com/aakarsh1506/evidex/blob/main/backend/services/rag.py): `backend/services/rag.py`

### Other components

- **Officer**
- **Ollama**
- **Groq**

## Connections

- Officer → React app: uses
- React app → Officer pages: renders
- Officer pages → API clients: requests
- API clients → FastAPI app: calls API
- FastAPI app → Authentication: dispatches
- FastAPI app → Document routes: dispatches
- FastAPI app → Record routes: dispatches
- FastAPI app → Workspace and stats: dispatches
- Authentication → PostgreSQL: reads officers
- Document routes → Ingestion worker: queues jobs
- Ingestion worker → Document files: loads files
- Ingestion worker → Text extraction: extracts text
- Ingestion worker → Export import: parses exports
- Ingestion worker → Entity extraction: extracts entities
- Ingestion worker → Document search: indexes text
- Ingestion worker → Record and graph writes: persists review
- Ingestion worker → PostgreSQL: queues and updates
- Record and graph writes → PostgreSQL: writes records
- Record and graph writes → Neo4j graph: syncs graph
- Document routes → Review and resolution: reviews identities
- Record routes → Criminal profiles: serves profiles
- Workspace and stats → Network analysis: serves analysis
- Workspace and stats → Investigator analysis: serves queries
- Investigator analysis → Document search: searches documents
- Investigator analysis → Neo4j graph: queries graph
- AI insights → Ollama: uses model
- AI insights → Groq: uses model