# sahinurrahman-debug/docsherlock architecture

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

- Interactive diagram: https://gitdiagram.com/sahinurrahman-debug/docsherlock
- Repository: https://github.com/sahinurrahman-debug/docsherlock

## Overview

DocSherlock is an evidence-grounded document investigation app. Analysts upload mixed-format files, which the backend extracts, chunks, indexes, and later searches to answer questions with verified citations, confidence and conflict handling. The UI also exposes workspace-wide case findings, timelines, dispute boards, red-team checks, evidence-pack exports, and Trust Lab. The graph preserves these documented capabilities; some service-to-service links rely on README descriptions or the SOURCE INDEX, since much of the implementation was not excerpted.

Main entry points: [`backend/app/main.py`](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/ingestion.py`](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/ingestion.py) (Ingestion pipeline), [`frontend/src/App.tsx`](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/App.tsx) (Web app), [`backend/app/api/conflicts.py`](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/conflicts.py) (Conflict routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Analyst interface"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_workspace["Workspace state<br/>[workspace.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_documents_ui["Documents view<br/>[Documents.tsx]"]
  node_investigation_ui["Investigation views<br/>[Investigation.tsx]"]
  node_trust_ui["Trust Lab view<br/>[TrustLab.tsx]"]
  node_board_ui["Case board<br/>[BoardView.tsx]"]
  node_timeline_ui["Timeline view<br/>[TimelineView.tsx]"]
end

subgraph group_api["API and workspace"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_document_routes["Document routes<br/>[documents.py]"]
  node_question_routes["Question routes<br/>[questions.py]"]
  node_conflict_routes["Conflict routes<br/>[conflicts.py]"]
  node_investigation_routes["Investigation routes<br/>[investigations.py]"]
  node_trust_routes["Trust Lab routes<br/>[trustlab.py]"]
end

subgraph group_ingest["Ingestion and indexing"]
  node_ingestion["Ingestion pipeline<br/>[ingestion.py]"]
  node_extractor["Format extraction<br/>[extractor.py]"]
  node_chunker["Passage chunking<br/>[chunker.py]"]
  node_claims["Claim extraction<br/>[claims.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
end

subgraph group_investigate["Evidence investigation"]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
  node_qa["Answer generation<br/>[qa.py]"]
  node_llm["LLM service<br/>[llm.py]"]
  node_citations["Citation verification<br/>[citations.py]"]
  node_conflict_detector["Conflict detection"]
  node_comparison["Document comparison<br/>[comparison.py]"]
  node_timeline["Time travel<br/>[timeline.py]"]
  node_board["Board assembly<br/>[board.py]"]
  node_casefile["Case file findings<br/>[casefile.py]"]
  node_redteam["Answer red-team<br/>[redteam.py]"]
  node_evidencepack["Evidence PDF<br/>[evidencepack.py]"]
end

subgraph group_state["Persistence and models"]
  node_vectorstore[("Vector index<br/>[vectorstore.py]")]
  node_sql_db[("SQL database<br/>[database.py]")]
end

node_analyst(("Analyst"))

node_analyst -->|"uses"| node_webapp
node_webapp -->|"provides state"| node_workspace
node_webapp -->|"routes to"| node_dashboard
node_webapp -->|"routes to"| node_documents_ui
node_webapp -->|"routes to"| node_investigation_ui
node_webapp -->|"routes to"| node_trust_ui
node_workspace -->|"calls"| node_api_client
node_dashboard -->|"uses"| node_workspace
node_documents_ui -->|"uploads via"| node_api_client
node_investigation_ui -->|"renders"| node_board_ui
node_investigation_ui -->|"renders"| node_timeline_ui
node_board_ui -->|"loads data"| node_api_client
node_timeline_ui -->|"loads data"| node_api_client
node_api_client -->|"HTTP requests"| node_api_app
node_api_app -->|"mounts"| node_document_routes
node_api_app -->|"mounts"| node_question_routes
node_api_app -->|"mounts"| node_conflict_routes
node_api_app -->|"mounts"| node_investigation_routes
node_api_app -->|"mounts"| node_trust_routes
node_document_routes -->|"starts ingestion"| node_ingestion
node_ingestion -->|"extracts files"| node_extractor
node_ingestion -->|"chunks pages"| node_chunker
node_ingestion -->|"extracts claims"| node_claims
node_ingestion -->|"embeds passages"| node_embeddings
node_ingestion -->|"indexes passages"| node_vectorstore
node_ingestion -->|"stores records"| node_sql_db
node_question_routes -->|"answers with"| node_qa
node_qa -.->|"retrieves evidence"| node_retriever
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"searches index"| node_vectorstore
node_qa -.->|"generates answer"| node_llm
node_qa -.->|"verifies quotes"| node_citations
node_qa -.->|"checks disputes"| node_conflict_detector
node_conflict_routes -->|"compares sources"| node_comparison
node_conflict_routes -->|"requests timeline"| node_timeline
node_conflict_routes -->|"assembles board"| node_board
node_conflict_routes -->|"reads workspace"| node_sql_db
node_document_routes -.->|"reports findings"| node_casefile
node_question_routes -->|"tests answers"| node_redteam
node_question_routes -->|"exports evidence"| node_evidencepack
node_trust_routes -.->|"runs attacks"| node_redteam
node_api_app -->|"warms models"| node_embeddings

click node_webapp "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/App.tsx"
click node_workspace "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/context/workspace.tsx"
click node_api_client "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/lib/api.ts"
click node_dashboard "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/Dashboard.tsx"
click node_documents_ui "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/Documents.tsx"
click node_investigation_ui "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/Investigation.tsx"
click node_trust_ui "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/TrustLab.tsx"
click node_board_ui "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/components/BoardView.tsx"
click node_timeline_ui "https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/components/TimelineView.tsx"
click node_api_app "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/main.py"
click node_document_routes "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/documents.py"
click node_question_routes "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/questions.py"
click node_conflict_routes "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/conflicts.py"
click node_investigation_routes "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/investigations.py"
click node_trust_routes "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/trustlab.py"
click node_ingestion "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/ingestion.py"
click node_extractor "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/extractor.py"
click node_chunker "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/chunker.py"
click node_claims "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/claims.py"
click node_embeddings "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/embeddings.py"
click node_vectorstore "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/vectorstore.py"
click node_sql_db "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/core/database.py"
click node_retriever "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/retriever.py"
click node_qa "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/qa.py"
click node_llm "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/llm.py"
click node_citations "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/citations.py"
click node_conflict_detector "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/conflict_detector.py"
click node_comparison "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/comparison.py"
click node_timeline "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/timeline.py"
click node_board "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/board.py"
click node_casefile "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/casefile.py"
click node_redteam "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/redteam.py"
click node_evidencepack "https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/evidencepack.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_webapp,node_workspace,node_api_client,node_dashboard,node_documents_ui,node_investigation_ui,node_trust_ui,node_board_ui,node_timeline_ui toneBlue
class node_api_app,node_document_routes,node_question_routes,node_conflict_routes,node_investigation_routes,node_trust_routes toneAmber
class node_ingestion,node_extractor,node_chunker,node_claims,node_embeddings toneMint
class node_retriever,node_qa,node_llm,node_citations,node_conflict_detector,node_comparison,node_timeline,node_board,node_casefile,node_redteam,node_evidencepack toneRose
class node_vectorstore,node_sql_db,node_analyst toneIndigo
```

## Components

### Analyst interface

- [Web app](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Workspace state](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/context/workspace.tsx): `frontend/src/context/workspace.tsx`
- [API client](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Dashboard](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Documents view](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/Documents.tsx): `frontend/src/pages/Documents.tsx`
- [Investigation views](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/Investigation.tsx): `frontend/src/pages/Investigation.tsx`
- [Trust Lab view](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/pages/TrustLab.tsx): `frontend/src/pages/TrustLab.tsx`
- [Case board](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/components/BoardView.tsx): `frontend/src/components/BoardView.tsx`
- [Timeline view](https://github.com/sahinurrahman-debug/docsherlock/blob/main/frontend/src/components/TimelineView.tsx): `frontend/src/components/TimelineView.tsx`

### API and workspace

- [FastAPI application](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/main.py): `backend/app/main.py`
- [Document routes](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Question routes](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/questions.py): `backend/app/api/questions.py`
- [Conflict routes](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/conflicts.py): `backend/app/api/conflicts.py`
- [Investigation routes](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/investigations.py): `backend/app/api/investigations.py`
- [Trust Lab routes](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/api/trustlab.py): `backend/app/api/trustlab.py`

### Ingestion and indexing

- [Ingestion pipeline](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Format extraction](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/extractor.py): `backend/app/services/extractor.py`
- [Passage chunking](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/chunker.py): `backend/app/services/chunker.py`
- [Claim extraction](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/claims.py): `backend/app/services/claims.py`
- [Embeddings](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`

### Evidence investigation

- [Hybrid retrieval](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/retriever.py): `backend/app/services/retriever.py`
- [Answer generation](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/qa.py): `backend/app/services/qa.py`
- [LLM service](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`
- [Citation verification](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/citations.py): `backend/app/services/citations.py`
- [Conflict detection](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/conflict_detector.py): `backend/app/services/conflict_detector.py`
- [Document comparison](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/comparison.py): `backend/app/services/comparison.py`
- [Time travel](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/timeline.py): `backend/app/services/timeline.py`
- [Board assembly](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/board.py): `backend/app/services/board.py`
- [Case file findings](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/casefile.py): `backend/app/services/casefile.py`
- [Answer red-team](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/redteam.py): `backend/app/services/redteam.py`
- [Evidence PDF](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/evidencepack.py): `backend/app/services/evidencepack.py`

### Persistence and models

- [Vector index](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/services/vectorstore.py): `backend/app/services/vectorstore.py`
- [SQL database](https://github.com/sahinurrahman-debug/docsherlock/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Analyst**

## Connections

- Analyst → Web app: uses
- Web app → Workspace state: provides state (evidence: `frontend/src/App.tsx`)
- Web app → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Web app → Documents view: routes to (evidence: `frontend/src/App.tsx`)
- Web app → Investigation views: routes to (evidence: `frontend/src/App.tsx`)
- Web app → Trust Lab view: routes to (evidence: `frontend/src/App.tsx`)
- Workspace state → API client: calls (evidence: `frontend/src/context/workspace.tsx`)
- Dashboard → Workspace state: uses (evidence: `frontend/src/pages/Dashboard.tsx`)
- Documents view → API client: uploads via (evidence: `frontend/src/pages/Documents.tsx`)
- Investigation views → Case board: renders (evidence: `frontend/src/pages/Investigation.tsx`)
- Investigation views → Timeline view: renders (evidence: `frontend/src/pages/Investigation.tsx`)
- Case board → API client: loads data (evidence: `frontend/src/components/BoardView.tsx`)
- Timeline view → API client: loads data (evidence: `frontend/src/components/TimelineView.tsx`)
- API client → FastAPI application: HTTP requests (evidence: `frontend/src/lib/api.ts`)
- FastAPI application → Document routes: mounts (evidence: `backend/app/main.py`)
- FastAPI application → Question routes: mounts (evidence: `backend/app/main.py`)
- FastAPI application → Conflict routes: mounts (evidence: `backend/app/main.py`)
- FastAPI application → Investigation routes: mounts (evidence: `backend/app/main.py`)
- FastAPI application → Trust Lab routes: mounts (evidence: `backend/app/main.py`)
- Document routes → Ingestion pipeline: starts ingestion (evidence: `backend/app/api/documents.py`)
- Ingestion pipeline → Format extraction: extracts files (evidence: `backend/app/services/ingestion.py`)
- Ingestion pipeline → Passage chunking: chunks pages (evidence: `backend/app/services/ingestion.py`)
- Ingestion pipeline → Claim extraction: extracts claims (evidence: `backend/app/services/ingestion.py`)
- Ingestion pipeline → Embeddings: embeds passages (evidence: `backend/app/services/ingestion.py`)
- Ingestion pipeline → Vector index: indexes passages (evidence: `backend/app/services/ingestion.py`)
- Ingestion pipeline → SQL database: stores records (evidence: `backend/app/services/ingestion.py`)
- Question routes → Answer generation: answers with (evidence: `backend/app/api/questions.py`)
- Answer generation → Hybrid retrieval: retrieves evidence
- Hybrid retrieval → Embeddings: embeds query (evidence: `backend/app/services/retriever.py`)
- Hybrid retrieval → Vector index: searches index (evidence: `backend/app/services/retriever.py`)
- Answer generation → LLM service: generates answer
- Answer generation → Citation verification: verifies quotes
- Answer generation → Conflict detection: checks disputes
- Conflict routes → Document comparison: compares sources (evidence: `backend/app/api/conflicts.py`)
- Conflict routes → Time travel: requests timeline (evidence: `backend/app/api/conflicts.py`)
- Conflict routes → Board assembly: assembles board (evidence: `backend/app/api/conflicts.py`)
- Conflict routes → SQL database: reads workspace (evidence: `backend/app/api/conflicts.py`)
- Document routes → Case file findings: reports findings
- Question routes → Answer red-team: tests answers (evidence: `backend/app/api/questions.py`)
- Question routes → Evidence PDF: exports evidence (evidence: `backend/app/api/questions.py`)
- Trust Lab routes → Answer red-team: runs attacks
- FastAPI application → Embeddings: warms models (evidence: `backend/app/main.py`)