# utkarshhh0/head-hunters-sih26 architecture

> Architecture diagram of the GitHub repository utkarshhh0/head-hunters-sih26, 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/utkarshhh0/head-hunters-sih26
- Repository: https://github.com/utkarshhh0/head-hunters-sih26

## Overview

This is an AI-powered criminal-network analysis investigator workspace: source records are prepared into a knowledge graph, analytical patterns become reviewable findings, and investigators explore entities, timelines, evidence, and reports through a web UI. The sampled workspace service confirms pattern detection, finding synthesis, and provenance assembly; the query layer confirms bounded Neo4j reads. The tree and README identify additional pipeline and analytics stages, but their internal wiring was not sampled, so those links are omitted.

Main entry points: [`src/frontend/src/App.tsx`](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/App.tsx) (Workspace App), [`src/backend/app/services/workspace_service.py`](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/services/workspace_service.py) (Workspace Service), [`src/backend/main.py`](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/main.py) (FastAPI App), [`src/frontend/src/api/client.ts`](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/client.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Investigator UI"]
  node_app["Workspace App<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_investigation["Investigation<br/>[Investigation.tsx]"]
  node_entityui["Entity Intelligence"]
  node_networkui["Network Explorer"]
  node_timelineui["Timeline<br/>[Timeline.tsx]"]
  node_findingsui["Analytical Findings"]
  node_evidenceui["Evidence<br/>[Evidence.tsx]"]
  node_reportsui["Reports<br/>[Reports.tsx]"]
  node_client["API Client<br/>[client.ts]"]
  node_entitiesapi["Entity API<br/>[entitiesApi.ts]"]
  node_findingsapi["Findings API<br/>[findingsApi.ts]"]
  node_reportsapi["Reports API<br/>[reportsApi.ts]"]
  node_workspaceapi["Workspace API<br/>[workspaceApi.ts]"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI App<br/>[main.py]"]
  node_entityroutes["Entity Routes<br/>[entities.py]"]
  node_findingroutes["Finding Routes<br/>[findings.py]"]
  node_reportroutes["Report Routes<br/>[reports.py]"]
  node_workspaceroutes["Workspace Routes<br/>[workspace.py]"]
end

subgraph group_analysis["Analysis Workflow"]
  node_workspace["Workspace Service"]
  node_detector["Pattern Detection<br/>[patterns.py]"]
  node_analytics["Structural and Temporal Analysis<br/>[structural.py]"]
  node_synthesizer["Finding Synthesis<br/>[finding_service.py]"]
  node_reportservice["Report Generation<br/>[report_service.py]"]
end

subgraph group_data["Graph and Ingestion"]
  node_query["Graph Query Layer<br/>[query.py]"]
  node_ingestion["Source Ingestion<br/>[ingestion.py]"]
  node_extraction["Extraction<br/>[extraction.py]"]
  node_normalization["Normalization<br/>[normalization.py]"]
  node_resolution["Entity Resolution<br/>[resolution.py]"]
  node_loader["Graph Loading<br/>[loader.py]"]
end

node_investigator(("Investigator"))
node_neo4j[("Neo4j Graph")]

node_investigator -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_investigation
node_app -->|"routes to"| node_entityui
node_app -->|"routes to"| node_networkui
node_app -->|"routes to"| node_timelineui
node_app -->|"routes to"| node_findingsui
node_app -->|"routes to"| node_evidenceui
node_app -->|"routes to"| node_reportsui
node_entityui -->|"requests data"| node_entitiesapi
node_networkui -->|"requests data"| node_entitiesapi
node_findingsui -->|"requests data"| node_findingsapi
node_reportsui -->|"requests data"| node_reportsapi
node_dashboard -->|"requests data"| node_workspaceapi
node_investigation -->|"requests data"| node_workspaceapi
node_timelineui -->|"requests data"| node_entitiesapi
node_evidenceui -->|"requests data"| node_findingsapi
node_entitiesapi -->|"uses"| node_client
node_findingsapi -->|"uses"| node_client
node_reportsapi -->|"uses"| node_client
node_workspaceapi -->|"uses"| node_client
node_client -->|"HTTP requests"| node_server
node_server -->|"dispatches"| node_entityroutes
node_server -->|"dispatches"| node_findingroutes
node_server -->|"dispatches"| node_reportroutes
node_server -->|"dispatches"| node_workspaceroutes
node_workspaceroutes -->|"calls"| node_workspace
node_findingroutes -->|"calls"| node_workspace
node_reportroutes -->|"calls"| node_workspace
node_entityroutes -->|"queries"| node_query
node_workspace -->|"detects patterns"| node_detector
node_workspace -->|"synthesizes findings"| node_synthesizer
node_workspace -->|"loads provenance"| node_query
node_workspace -->|"generates reports"| node_reportservice
node_detector -.->|"uses analysis"| node_analytics
node_query -->|"reads graph"| node_neo4j
node_ingestion -->|"feeds"| node_extraction
node_extraction -->|"feeds"| node_normalization
node_normalization -->|"feeds"| node_resolution
node_resolution -->|"feeds"| node_loader
node_loader -->|"writes graph"| node_neo4j

click node_app "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/App.tsx"
click node_dashboard "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Dashboard.tsx"
click node_investigation "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Investigation.tsx"
click node_entityui "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/EntityIntelligence.tsx"
click node_networkui "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/NetworkExplorer.tsx"
click node_timelineui "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Timeline.tsx"
click node_findingsui "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/AnalyticalFindings.tsx"
click node_evidenceui "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Evidence.tsx"
click node_reportsui "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Reports.tsx"
click node_client "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/client.ts"
click node_entitiesapi "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/entitiesApi.ts"
click node_findingsapi "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/findingsApi.ts"
click node_reportsapi "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/reportsApi.ts"
click node_workspaceapi "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/workspaceApi.ts"
click node_server "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/main.py"
click node_entityroutes "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/entities.py"
click node_findingroutes "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/findings.py"
click node_reportroutes "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/reports.py"
click node_workspaceroutes "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/workspace.py"
click node_workspace "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/services/workspace_service.py"
click node_detector "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/analytics/patterns.py"
click node_analytics "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/analytics/structural.py"
click node_synthesizer "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/services/finding_service.py"
click node_reportservice "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/services/report_service.py"
click node_query "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/graph/query.py"
click node_ingestion "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/ingestion.py"
click node_extraction "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/extraction.py"
click node_normalization "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/normalization.py"
click node_resolution "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/resolution.py"
click node_loader "https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/graph/loader.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_dashboard,node_investigation,node_entityui,node_networkui,node_timelineui,node_findingsui,node_evidenceui,node_reportsui,node_client,node_entitiesapi,node_findingsapi,node_reportsapi,node_workspaceapi toneBlue
class node_server,node_entityroutes,node_findingroutes,node_reportroutes,node_workspaceroutes,node_neo4j toneAmber
class node_workspace,node_detector,node_analytics,node_synthesizer,node_reportservice toneMint
class node_query,node_ingestion,node_extraction,node_normalization,node_resolution,node_loader toneRose
class node_investigator toneIndigo
```

## Components

### Investigator UI

- [Workspace App](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/App.tsx): `src/frontend/src/App.tsx`
- [Dashboard](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Dashboard.tsx): `src/frontend/src/pages/Dashboard.tsx`
- [Investigation](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Investigation.tsx): `src/frontend/src/pages/Investigation.tsx`
- [Entity Intelligence](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/EntityIntelligence.tsx): `src/frontend/src/pages/EntityIntelligence.tsx`
- [Network Explorer](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/NetworkExplorer.tsx): `src/frontend/src/pages/NetworkExplorer.tsx`
- [Timeline](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Timeline.tsx): `src/frontend/src/pages/Timeline.tsx`
- [Analytical Findings](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/AnalyticalFindings.tsx): `src/frontend/src/pages/AnalyticalFindings.tsx`
- [Evidence](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Evidence.tsx): `src/frontend/src/pages/Evidence.tsx`
- [Reports](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/pages/Reports.tsx): `src/frontend/src/pages/Reports.tsx`
- [API Client](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/client.ts): `src/frontend/src/api/client.ts`
- [Entity API](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/entitiesApi.ts): `src/frontend/src/api/entitiesApi.ts`
- [Findings API](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/findingsApi.ts): `src/frontend/src/api/findingsApi.ts`
- [Reports API](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/reportsApi.ts): `src/frontend/src/api/reportsApi.ts`
- [Workspace API](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/frontend/src/api/workspaceApi.ts): `src/frontend/src/api/workspaceApi.ts`

### Backend API

- [FastAPI App](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/main.py): `src/backend/main.py`
- [Entity Routes](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/entities.py): `src/backend/app/api/v1/entities.py`
- [Finding Routes](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/findings.py): `src/backend/app/api/v1/findings.py`
- [Report Routes](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/reports.py): `src/backend/app/api/v1/reports.py`
- [Workspace Routes](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/api/v1/workspace.py): `src/backend/app/api/v1/workspace.py`

### Analysis Workflow

- [Workspace Service](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/services/workspace_service.py): `src/backend/app/services/workspace_service.py`
- [Pattern Detection](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/analytics/patterns.py): `src/backend/app/analytics/patterns.py`
- [Structural and Temporal Analysis](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/analytics/structural.py): `src/backend/app/analytics/structural.py`
- [Finding Synthesis](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/services/finding_service.py): `src/backend/app/services/finding_service.py`
- [Report Generation](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/services/report_service.py): `src/backend/app/services/report_service.py`

### Graph and Ingestion

- [Graph Query Layer](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/graph/query.py): `src/backend/app/graph/query.py`
- [Source Ingestion](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/ingestion.py): `src/backend/app/pipeline/ingestion.py`
- [Extraction](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/extraction.py): `src/backend/app/pipeline/extraction.py`
- [Normalization](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/normalization.py): `src/backend/app/pipeline/normalization.py`
- [Entity Resolution](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/pipeline/resolution.py): `src/backend/app/pipeline/resolution.py`
- [Graph Loading](https://github.com/utkarshhh0/head-hunters-sih26/blob/main/src/backend/app/graph/loader.py): `src/backend/app/graph/loader.py`

### Other components

- **Investigator**
- **Neo4j Graph**

## Connections

- Investigator → Workspace App: uses
- Workspace App → Dashboard: routes to
- Workspace App → Investigation: routes to
- Workspace App → Entity Intelligence: routes to
- Workspace App → Network Explorer: routes to
- Workspace App → Timeline: routes to
- Workspace App → Analytical Findings: routes to
- Workspace App → Evidence: routes to
- Workspace App → Reports: routes to
- Entity Intelligence → Entity API: requests data
- Network Explorer → Entity API: requests data
- Analytical Findings → Findings API: requests data
- Reports → Reports API: requests data
- Dashboard → Workspace API: requests data
- Investigation → Workspace API: requests data
- Timeline → Entity API: requests data
- Evidence → Findings API: requests data
- Entity API → API Client: uses
- Findings API → API Client: uses
- Reports API → API Client: uses
- Workspace API → API Client: uses
- API Client → FastAPI App: HTTP requests
- FastAPI App → Entity Routes: dispatches
- FastAPI App → Finding Routes: dispatches
- FastAPI App → Report Routes: dispatches
- FastAPI App → Workspace Routes: dispatches
- Workspace Routes → Workspace Service: calls
- Finding Routes → Workspace Service: calls
- Report Routes → Workspace Service: calls
- Entity Routes → Graph Query Layer: queries
- Workspace Service → Pattern Detection: detects patterns
- Workspace Service → Finding Synthesis: synthesizes findings
- Workspace Service → Graph Query Layer: loads provenance
- Workspace Service → Report Generation: generates reports
- Pattern Detection → Structural and Temporal Analysis: uses analysis
- Graph Query Layer → Neo4j Graph: reads graph
- Source Ingestion → Extraction: feeds
- Extraction → Normalization: feeds
- Normalization → Entity Resolution: feeds
- Entity Resolution → Graph Loading: feeds
- Graph Loading → Neo4j Graph: writes graph