# farheenaiml/lineage architecture

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

- Interactive diagram: https://gitdiagram.com/farheenaiml/lineage
- Repository: https://github.com/farheenaiml/lineage

## Overview

LINEAGE is a full-stack investigation platform for tracing suspected synthetic-identity abuse. Investigators authenticate, create a case, upload media for detection and fingerprinting, add sources and evidence, then examine propagation, attribution gaps, and reports; graph Q&A, geographic analysis, ML intelligence, web discovery, and case automation extend that workflow. The graph follows documented frontend routing/API boundaries and backend registration plus sampled calls. Many route-to-service implementations were not sampled, so uncertain internal links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/farheenaiml/lineage/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/lib/api.ts`](https://github.com/farheenaiml/lineage/blob/main/frontend/src/lib/api.ts) (Typed API client), [`frontend/src/App.tsx`](https://github.com/farheenaiml/lineage/blob/main/frontend/src/App.tsx) (App routing), [`backend/app/routers/web_search.py`](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/web_search.py) (Image web discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Investigator app"]
  node_app["App routing<br/>[App.tsx]"]
  node_case_context["Case state<br/>[CaseContext.tsx]"]
  node_api_client["Typed API client<br/>[api.ts]"]
  node_investigation_ui["Case workflow screens<br/>[Investigations.tsx]"]
  node_upload_ui["Media upload"]
  node_geo_ui["Propagation map<br/>[PropagationMap.tsx]"]
  node_ml_ui["ML intelligence UI<br/>[MLIntelligence.tsx]"]
  node_automation_ui["Case automation UI<br/>[CaseAutomation.tsx]"]
end

subgraph group_api["API and identity"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_auth_deps["Session authorization<br/>[deps.py]"]
end

subgraph group_case["Investigation records"]
  node_incident_routes["Investigation routes<br/>[incidents.py]"]
  node_media_routes["Media routes<br/>[media.py]"]
  node_source_evidence["Sources and evidence<br/>[sources.py]"]
  node_attribution_reports["Attribution and reports<br/>[attribution.py]"]
  node_automation_routes["Automation routes<br/>[automation.py]"]
end

subgraph group_analysis["Analysis capabilities"]
  node_geo_routes["Geographic analysis<br/>[geo.py]"]
  node_graph_routes["Investigation graph<br/>[graph.py]"]
  node_copilot["Graph RAG copilot<br/>[graph_rag.py]"]
  node_ml_routes["ML intelligence<br/>[ml.py]"]
  node_web_search["Image web discovery<br/>[web_search.py]"]
  node_face_embedding["Face fingerprinting<br/>[face_embedding.py]"]
end

subgraph group_persistence["Storage and graph"]
  node_file_storage["Encrypted media storage<br/>[file_storage.py]"]
  node_database[("SQL records<br/>[session.py]")]
  node_neo4j[("Neo4j graph store<br/>[neo4j_service.py]")]
end

node_investigator(("Investigator"))
node_web_provider["Gemini query service"]

node_investigator -->|"uses"| node_app
node_app -->|"wraps screens"| node_case_context
node_app -->|"routes to"| node_investigation_ui
node_app -->|"routes to"| node_upload_ui
node_case_context -->|"requests case data"| node_api_client
node_investigation_ui -->|"reads case state"| node_case_context
node_upload_ui -->|"uploads through"| node_case_context
node_api_client -->|"calls API"| node_backend
node_backend -->|"registers routes"| node_auth
node_backend -->|"registers routes"| node_incident_routes
node_backend -->|"registers routes"| node_media_routes
node_backend -->|"registers routes"| node_source_evidence
node_backend -->|"registers routes"| node_attribution_reports
node_backend -->|"registers routes"| node_geo_routes
node_backend -->|"registers routes"| node_graph_routes
node_backend -->|"registers routes"| node_ml_routes
node_backend -->|"registers routes"| node_automation_routes
node_backend -->|"registers routes"| node_web_search
node_backend -->|"registers route"| node_copilot
node_auth -->|"uses authorization"| node_auth_deps
node_auth_deps -->|"queries user"| node_database
node_incident_routes -->|"reads and writes"| node_database
node_geo_routes -->|"reads records"| node_database
node_web_search -->|"reads decrypted media"| node_file_storage
node_web_search -->|"requests search queries"| node_web_provider
node_web_search -->|"stores search runs"| node_database
node_backend -->|"initializes graph store"| node_neo4j
node_geo_ui -->|"requests map data"| node_api_client
node_ml_ui -->|"requests ML results"| node_api_client
node_automation_ui -->|"requests automation"| node_api_client
node_media_routes -.->|"stores encrypted uploads"| node_file_storage
node_media_routes -.->|"fingerprints media"| node_face_embedding
node_graph_routes -.->|"uses graph persistence"| node_neo4j
node_graph_routes -.->|"supplies graph context"| node_copilot

click node_app "https://github.com/farheenaiml/lineage/blob/main/frontend/src/App.tsx"
click node_case_context "https://github.com/farheenaiml/lineage/blob/main/frontend/src/context/CaseContext.tsx"
click node_api_client "https://github.com/farheenaiml/lineage/blob/main/frontend/src/lib/api.ts"
click node_investigation_ui "https://github.com/farheenaiml/lineage/blob/main/frontend/src/screens/Investigations.tsx"
click node_upload_ui "https://github.com/farheenaiml/lineage/blob/main/frontend/src/screens/UploadDetection.tsx"
click node_geo_ui "https://github.com/farheenaiml/lineage/blob/main/frontend/src/components/geo/PropagationMap.tsx"
click node_ml_ui "https://github.com/farheenaiml/lineage/blob/main/frontend/src/components/ml/MLIntelligence.tsx"
click node_automation_ui "https://github.com/farheenaiml/lineage/blob/main/frontend/src/screens/CaseAutomation.tsx"
click node_backend "https://github.com/farheenaiml/lineage/blob/main/backend/app/main.py"
click node_auth "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/auth.py"
click node_auth_deps "https://github.com/farheenaiml/lineage/blob/main/backend/app/deps.py"
click node_incident_routes "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/incidents.py"
click node_media_routes "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/media.py"
click node_source_evidence "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/sources.py"
click node_attribution_reports "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/attribution.py"
click node_automation_routes "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/automation.py"
click node_geo_routes "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/geo.py"
click node_graph_routes "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/graph.py"
click node_copilot "https://github.com/farheenaiml/lineage/blob/main/backend/app/services/graph_rag.py"
click node_ml_routes "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/ml.py"
click node_web_search "https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/web_search.py"
click node_face_embedding "https://github.com/farheenaiml/lineage/blob/main/backend/app/services/face_embedding.py"
click node_file_storage "https://github.com/farheenaiml/lineage/blob/main/backend/app/services/file_storage.py"
click node_database "https://github.com/farheenaiml/lineage/blob/main/backend/app/db/session.py"
click node_neo4j "https://github.com/farheenaiml/lineage/blob/main/backend/app/services/neo4j_service.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_case_context,node_api_client,node_investigation_ui,node_upload_ui,node_geo_ui,node_ml_ui,node_automation_ui toneBlue
class node_backend,node_auth,node_auth_deps toneAmber
class node_incident_routes,node_media_routes,node_source_evidence,node_attribution_reports,node_automation_routes toneMint
class node_geo_routes,node_graph_routes,node_copilot,node_ml_routes,node_web_search,node_face_embedding toneRose
class node_file_storage,node_database,node_neo4j,node_investigator,node_web_provider toneIndigo
```

## Components

### Investigator app

- [App routing](https://github.com/farheenaiml/lineage/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Case state](https://github.com/farheenaiml/lineage/blob/main/frontend/src/context/CaseContext.tsx): `frontend/src/context/CaseContext.tsx`
- [Typed API client](https://github.com/farheenaiml/lineage/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Case workflow screens](https://github.com/farheenaiml/lineage/blob/main/frontend/src/screens/Investigations.tsx): `frontend/src/screens/Investigations.tsx`
- [Media upload](https://github.com/farheenaiml/lineage/blob/main/frontend/src/screens/UploadDetection.tsx): `frontend/src/screens/UploadDetection.tsx`
- [Propagation map](https://github.com/farheenaiml/lineage/blob/main/frontend/src/components/geo/PropagationMap.tsx): `frontend/src/components/geo/PropagationMap.tsx`
- [ML intelligence UI](https://github.com/farheenaiml/lineage/blob/main/frontend/src/components/ml/MLIntelligence.tsx): `frontend/src/components/ml/MLIntelligence.tsx`
- [Case automation UI](https://github.com/farheenaiml/lineage/blob/main/frontend/src/screens/CaseAutomation.tsx): `frontend/src/screens/CaseAutomation.tsx`

### API and identity

- [FastAPI application](https://github.com/farheenaiml/lineage/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Session authorization](https://github.com/farheenaiml/lineage/blob/main/backend/app/deps.py): `backend/app/deps.py`

### Investigation records

- [Investigation routes](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/incidents.py): `backend/app/routers/incidents.py`
- [Media routes](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/media.py): `backend/app/routers/media.py`
- [Sources and evidence](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/sources.py): `backend/app/routers/sources.py`
- [Attribution and reports](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/attribution.py): `backend/app/routers/attribution.py`
- [Automation routes](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/automation.py): `backend/app/routers/automation.py`

### Analysis capabilities

- [Geographic analysis](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/geo.py): `backend/app/routers/geo.py`
- [Investigation graph](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/graph.py): `backend/app/routers/graph.py`
- [Graph RAG copilot](https://github.com/farheenaiml/lineage/blob/main/backend/app/services/graph_rag.py): `backend/app/services/graph_rag.py`
- [ML intelligence](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/ml.py): `backend/app/routers/ml.py`
- [Image web discovery](https://github.com/farheenaiml/lineage/blob/main/backend/app/routers/web_search.py): `backend/app/routers/web_search.py`
- [Face fingerprinting](https://github.com/farheenaiml/lineage/blob/main/backend/app/services/face_embedding.py): `backend/app/services/face_embedding.py`

### Storage and graph

- [Encrypted media storage](https://github.com/farheenaiml/lineage/blob/main/backend/app/services/file_storage.py): `backend/app/services/file_storage.py`
- [SQL records](https://github.com/farheenaiml/lineage/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Neo4j graph store](https://github.com/farheenaiml/lineage/blob/main/backend/app/services/neo4j_service.py): `backend/app/services/neo4j_service.py`

### Other components

- **Investigator**
- **Gemini query service**

## Connections

- Investigator → App routing: uses (evidence: `frontend/src/App.tsx`)
- App routing → Case state: wraps screens (evidence: `frontend/src/App.tsx`)
- App routing → Case workflow screens: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Media upload: routes to (evidence: `frontend/src/App.tsx`)
- Case state → Typed API client: requests case data (evidence: `frontend/src/context/CaseContext.tsx`)
- Case workflow screens → Case state: reads case state (evidence: `frontend/src/screens/Investigations.tsx`)
- Media upload → Case state: uploads through (evidence: `frontend/src/screens/UploadDetection.tsx`)
- Typed API client → FastAPI application: calls API (evidence: `frontend/src/lib/api.ts`)
- FastAPI application → Authentication routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Investigation routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Media routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Sources and evidence: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Attribution and reports: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Geographic analysis: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Investigation graph: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → ML intelligence: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Automation routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Image web discovery: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Graph RAG copilot: registers route (evidence: `backend/app/main.py`)
- Authentication routes → Session authorization: uses authorization (evidence: `backend/app/routers/auth.py`)
- Session authorization → SQL records: queries user (evidence: `backend/app/deps.py`)
- Investigation routes → SQL records: reads and writes (evidence: `backend/app/routers/incidents.py`)
- Geographic analysis → SQL records: reads records (evidence: `backend/app/routers/geo.py`)
- Image web discovery → Encrypted media storage: reads decrypted media (evidence: `backend/app/routers/web_search.py`)
- Image web discovery → Gemini query service: requests search queries (evidence: `backend/app/routers/web_search.py`)
- Image web discovery → SQL records: stores search runs (evidence: `backend/app/routers/web_search.py`)
- FastAPI application → Neo4j graph store: initializes graph store (evidence: `backend/app/main.py`)
- Propagation map → Typed API client: requests map data (evidence: `frontend/src/components/geo/PropagationMap.tsx`)
- ML intelligence UI → Typed API client: requests ML results (evidence: `frontend/src/components/ml/MLIntelligence.tsx`)
- Case automation UI → Typed API client: requests automation (evidence: `frontend/src/screens/CaseAutomation.tsx`)
- Media routes → Encrypted media storage: stores encrypted uploads
- Media routes → Face fingerprinting: fingerprints media
- Investigation graph → Neo4j graph store: uses graph persistence
- Investigation graph → Graph RAG copilot: supplies graph context