# pritam-x11/forensai architecture

> Architecture diagram of the GitHub repository pritam-x11/forensai, 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/pritam-x11/forensai
- Repository: https://github.com/pritam-x11/forensai

## Overview

ForensAI is a forensic face-matching product with a React investigator interface, a Spring backend for authentication and evidence/results handling, and a FastAPI service for photo, sketch, and video analysis. The user workflow is to sign in, submit evidence, and review ranked, explainable candidate matches; investigator and facial-record capabilities are also represented. The AI routes and selected backend services are excerpted or indexed; relationships involving unsampled modules are omitted or marked unverified rather than inferred.

Main entry points: [`ai-service/routers/photo.py`](https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/photo.py) (Photo analysis), [`ai-service/routers/sketch.py`](https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/sketch.py) (Sketch analysis), [`ai-service/routers/video.py`](https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/video.py) (Video analysis), [`ai-service/main.py`](https://github.com/pritam-x11/forensai/blob/main/ai-service/main.py) (AI API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Investigator UI"]
  node_ui["Forensic workspace<br/>[App.jsx]"]
end

subgraph group_backend["Backend services"]
  node_backend_app["Spring application"]
  node_auth["Authentication"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_evidence_controller["Evidence handling"]
  node_ai_client["AI service client"]
  node_match_service["Match result service"]
  node_match_store[("Match result repository")]
  node_match_entity["Match result model"]
  node_investigator_controller["Investigator operations"]
  node_facial_record_controller["Facial records"]
end

subgraph group_ai_routes["AI workflows"]
  node_api_app["AI API router<br/>[main.py]"]
  node_photo["Photo analysis<br/>[photo.py]"]
  node_sketch["Sketch analysis<br/>[sketch.py]"]
  node_video["Video analysis<br/>[video.py]"]
  node_investigator_route["Investigator route<br/>[investigator.py]"]
end

subgraph group_ai_services["Analysis and retrieval"]
  node_face_detect["Face detection<br/>[scrfd_service.py]"]
  node_preprocess["Image preprocessing"]
  node_alignment["Face alignment"]
  node_face_quality["Face quality"]
  node_identity_features["Identity features<br/>[arcface_service.py]"]
  node_visual_features["Visual features<br/>[dinov3_service.py]"]
  node_feature_layer["Feature representation"]
  node_multi_cue["Evidence cues"]
  node_quality_weight["Quality weighting"]
  node_uncertainty["Uncertainty"]
  node_identity_retrieval["Identity retrieval"]
  node_faiss["FAISS index<br/>[faiss_service.py]"]
  node_visual_retrieval["Visual retrieval"]
  node_gallery["Candidate gallery"]
  node_top_candidates["Candidate selection"]
  node_reranking["Evidence reranking"]
  node_explanation["Explainable results"]
end

node_investigator(("Investigator"))

node_investigator -->|"uses"| node_ui
node_ui -.->|"calls API"| node_backend_app
node_backend_app -.->|"forwards analysis"| node_api_app
node_api_app -->|"registers route"| node_photo
node_api_app -->|"registers route"| node_investigator_route
node_api_app -->|"registers route"| node_video
node_api_app -->|"registers route"| node_sketch
node_photo -->|"preprocesses"| node_preprocess
node_photo -->|"detects faces"| node_face_detect
node_photo -->|"aligns faces"| node_alignment
node_photo -->|"scores quality"| node_face_quality
node_photo -->|"extracts identity"| node_identity_features
node_photo -->|"extracts visuals"| node_visual_features
node_photo -->|"builds features"| node_feature_layer
node_photo -->|"builds evidence"| node_multi_cue
node_photo -->|"weights quality"| node_quality_weight
node_photo -->|"calculates uncertainty"| node_uncertainty
node_photo -->|"searches identities"| node_identity_retrieval
node_photo -->|"selects candidates"| node_top_candidates
node_photo -->|"reranks matches"| node_reranking
node_photo -->|"explains results"| node_explanation
node_sketch -->|"detects faces"| node_face_detect
node_sketch -->|"uses identity features"| node_identity_features
node_sketch -->|"aligns faces"| node_alignment
node_sketch -->|"uses visual features"| node_visual_features
node_sketch -->|"builds evidence"| node_multi_cue
node_sketch -->|"weights quality"| node_quality_weight
node_sketch -->|"calculates uncertainty"| node_uncertainty
node_sketch -->|"retrieves identities"| node_identity_retrieval
node_sketch -->|"retrieves visuals"| node_visual_retrieval
node_sketch -->|"selects candidates"| node_top_candidates
node_sketch -->|"reranks matches"| node_reranking
node_video -->|"detects faces"| node_face_detect
node_video -->|"extracts identity"| node_identity_features
node_video -->|"aligns faces"| node_alignment
node_video -->|"scores quality"| node_face_quality
node_video -->|"builds evidence"| node_multi_cue
node_video -->|"weights quality"| node_quality_weight
node_video -->|"calculates uncertainty"| node_uncertainty
node_video -->|"retrieves identities"| node_identity_retrieval
node_video -->|"selects candidates"| node_top_candidates
node_video -->|"reranks matches"| node_reranking
node_video -->|"explains results"| node_explanation
node_identity_retrieval -->|"indexes vectors"| node_faiss
node_visual_retrieval -->|"indexes vectors"| node_faiss
node_photo -->|"loads candidates"| node_gallery
node_sketch -->|"loads candidates"| node_gallery
node_video -->|"loads candidates"| node_gallery

click node_ui "https://github.com/pritam-x11/forensai/blob/main/forensai-frontend/src/App.jsx"
click node_api_app "https://github.com/pritam-x11/forensai/blob/main/ai-service/main.py"
click node_photo "https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/photo.py"
click node_sketch "https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/sketch.py"
click node_video "https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/video.py"
click node_investigator_route "https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/investigator.py"
click node_face_detect "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/scrfd_service.py"
click node_preprocess "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/preprocessing_service.py"
click node_alignment "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/face_alignment_service.py"
click node_face_quality "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/face_quality_service.py"
click node_identity_features "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/arcface_service.py"
click node_visual_features "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/dinov3_service.py"
click node_feature_layer "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/feature_layer_service.py"
click node_multi_cue "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/multi_cue_evidence_service.py"
click node_quality_weight "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/quality_weight_service.py"
click node_uncertainty "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/uncertainty_service.py"
click node_identity_retrieval "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/identity_retrieval_service.py"
click node_faiss "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/faiss_service.py"
click node_visual_retrieval "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/visual_retrieval_service.py"
click node_gallery "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/candidate_gallery_service.py"
click node_top_candidates "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/top_candidates_service.py"
click node_reranking "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/evidence_reranking_service.py"
click node_explanation "https://github.com/pritam-x11/forensai/blob/main/ai-service/services/explainable_results_service.py"
click node_backend_app "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/ForensaibackendApplication.java"
click node_auth "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/AuthController.java"
click node_jwt "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/config/JwtService.java"
click node_evidence_controller "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/EvidenceController.java"
click node_ai_client "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/service/AiServiceClient.java"
click node_match_service "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/service/MatchingResultService.java"
click node_match_store "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/repository/MatchingResultRepository.java"
click node_match_entity "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/entity/MatchingResult.java"
click node_investigator_controller "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/InvestigatorController.java"
click node_facial_record_controller "https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/FacialRecordController.java"

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_ui toneBlue
class node_backend_app,node_auth,node_jwt,node_evidence_controller,node_ai_client,node_match_service,node_match_store,node_match_entity,node_investigator_controller,node_facial_record_controller toneAmber
class node_api_app,node_photo,node_sketch,node_video,node_investigator_route toneMint
class node_face_detect,node_preprocess,node_alignment,node_face_quality,node_identity_features,node_visual_features,node_feature_layer,node_multi_cue,node_quality_weight,node_uncertainty,node_identity_retrieval,node_faiss,node_visual_retrieval,node_gallery,node_top_candidates,node_reranking,node_explanation toneRose
class node_investigator toneIndigo
```

## Components

### Investigator UI

- [Forensic workspace](https://github.com/pritam-x11/forensai/blob/main/forensai-frontend/src/App.jsx): `forensai-frontend/src/App.jsx`

### Backend services

- [Spring application](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/ForensaibackendApplication.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/ForensaibackendApplication.java`
- [Authentication](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/AuthController.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/controller/AuthController.java`
- [JWT service](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/config/JwtService.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/config/JwtService.java`
- [Evidence handling](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/EvidenceController.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/controller/EvidenceController.java`
- [AI service client](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/service/AiServiceClient.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/service/AiServiceClient.java`
- [Match result service](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/service/MatchingResultService.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/service/MatchingResultService.java`
- [Match result repository](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/repository/MatchingResultRepository.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/repository/MatchingResultRepository.java`
- [Match result model](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/entity/MatchingResult.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/entity/MatchingResult.java`
- [Investigator operations](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/InvestigatorController.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/controller/InvestigatorController.java`
- [Facial records](https://github.com/pritam-x11/forensai/blob/main/forensaibackend/src/main/java/com/forensai/forensaibackend/controller/FacialRecordController.java): `forensaibackend/src/main/java/com/forensai/forensaibackend/controller/FacialRecordController.java`

### AI workflows

- [AI API router](https://github.com/pritam-x11/forensai/blob/main/ai-service/main.py): `ai-service/main.py`
- [Photo analysis](https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/photo.py): `ai-service/routers/photo.py`
- [Sketch analysis](https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/sketch.py): `ai-service/routers/sketch.py`
- [Video analysis](https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/video.py): `ai-service/routers/video.py`
- [Investigator route](https://github.com/pritam-x11/forensai/blob/main/ai-service/routers/investigator.py): `ai-service/routers/investigator.py`

### Analysis and retrieval

- [Face detection](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/scrfd_service.py): `ai-service/services/scrfd_service.py`
- [Image preprocessing](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/preprocessing_service.py): `ai-service/services/preprocessing_service.py`
- [Face alignment](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/face_alignment_service.py): `ai-service/services/face_alignment_service.py`
- [Face quality](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/face_quality_service.py): `ai-service/services/face_quality_service.py`
- [Identity features](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/arcface_service.py): `ai-service/services/arcface_service.py`
- [Visual features](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/dinov3_service.py): `ai-service/services/dinov3_service.py`
- [Feature representation](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/feature_layer_service.py): `ai-service/services/feature_layer_service.py`
- [Evidence cues](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/multi_cue_evidence_service.py): `ai-service/services/multi_cue_evidence_service.py`
- [Quality weighting](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/quality_weight_service.py): `ai-service/services/quality_weight_service.py`
- [Uncertainty](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/uncertainty_service.py): `ai-service/services/uncertainty_service.py`
- [Identity retrieval](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/identity_retrieval_service.py): `ai-service/services/identity_retrieval_service.py`
- [FAISS index](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/faiss_service.py): `ai-service/services/faiss_service.py`
- [Visual retrieval](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/visual_retrieval_service.py): `ai-service/services/visual_retrieval_service.py`
- [Candidate gallery](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/candidate_gallery_service.py): `ai-service/services/candidate_gallery_service.py`
- [Candidate selection](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/top_candidates_service.py): `ai-service/services/top_candidates_service.py`
- [Evidence reranking](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/evidence_reranking_service.py): `ai-service/services/evidence_reranking_service.py`
- [Explainable results](https://github.com/pritam-x11/forensai/blob/main/ai-service/services/explainable_results_service.py): `ai-service/services/explainable_results_service.py`

### Other components

- **Investigator**

## Connections

- Investigator → Forensic workspace: uses
- Forensic workspace → Spring application: calls API
- Spring application → AI API router: forwards analysis
- AI API router → Photo analysis: registers route (evidence: `ai-service/main.py`)
- AI API router → Investigator route: registers route (evidence: `ai-service/main.py`)
- AI API router → Video analysis: registers route (evidence: `ai-service/main.py`)
- AI API router → Sketch analysis: registers route (evidence: `ai-service/main.py`)
- Photo analysis → Image preprocessing: preprocesses (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Face detection: detects faces (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Face alignment: aligns faces (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Face quality: scores quality (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Identity features: extracts identity (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Visual features: extracts visuals (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Feature representation: builds features (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Evidence cues: builds evidence (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Quality weighting: weights quality (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Uncertainty: calculates uncertainty (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Identity retrieval: searches identities (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Candidate selection: selects candidates (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Evidence reranking: reranks matches (evidence: `ai-service/routers/photo.py`)
- Photo analysis → Explainable results: explains results (evidence: `ai-service/routers/photo.py`)
- Sketch analysis → Face detection: detects faces (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Identity features: uses identity features (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Face alignment: aligns faces (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Visual features: uses visual features (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Evidence cues: builds evidence (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Quality weighting: weights quality (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Uncertainty: calculates uncertainty (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Identity retrieval: retrieves identities (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Visual retrieval: retrieves visuals (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Candidate selection: selects candidates (evidence: `ai-service/routers/sketch.py`)
- Sketch analysis → Evidence reranking: reranks matches (evidence: `ai-service/routers/sketch.py`)
- Video analysis → Face detection: detects faces (evidence: `ai-service/routers/video.py`)
- Video analysis → Identity features: extracts identity (evidence: `ai-service/routers/video.py`)
- Video analysis → Face alignment: aligns faces (evidence: `ai-service/routers/video.py`)
- Video analysis → Face quality: scores quality (evidence: `ai-service/routers/video.py`)
- Video analysis → Evidence cues: builds evidence (evidence: `ai-service/routers/video.py`)
- Video analysis → Quality weighting: weights quality (evidence: `ai-service/routers/video.py`)
- Video analysis → Uncertainty: calculates uncertainty (evidence: `ai-service/routers/video.py`)
- Video analysis → Identity retrieval: retrieves identities (evidence: `ai-service/routers/video.py`)
- Video analysis → Candidate selection: selects candidates (evidence: `ai-service/routers/video.py`)
- Video analysis → Evidence reranking: reranks matches (evidence: `ai-service/routers/video.py`)
- Video analysis → Explainable results: explains results (evidence: `ai-service/routers/video.py`)
- Identity retrieval → FAISS index: indexes vectors (evidence: `ai-service/services/identity_retrieval_service.py`)
- Visual retrieval → FAISS index: indexes vectors (evidence: `ai-service/services/visual_retrieval_service.py`)
- Photo analysis → Candidate gallery: loads candidates (evidence: `ai-service/routers/photo.py`)
- Sketch analysis → Candidate gallery: loads candidates (evidence: `ai-service/routers/sketch.py`)
- Video analysis → Candidate gallery: loads candidates (evidence: `ai-service/routers/video.py`)
