# pragy10/finesse architecture

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

- Interactive diagram: https://gitdiagram.com/pragy10/finesse
- Repository: https://github.com/pragy10/finesse

## Overview

Finesse lets an authenticated user upload insurance PDFs, then search policy text or ask questions and receive AI answers with clause citations. The upload route orchestrates parsing, chunking, storage, indexing, and metadata; the query and answer routes serve distinct retrieval and reasoning paths. The graph also includes profile management and monitoring. Relationships come from the supplied excerpts, SOURCE INDEX references, and README; unsampled feature internals are represented only where documented.

Main entry points: [`backend/routes/documents.js`](https://github.com/pragy10/finesse/blob/main/backend/routes/documents.js) (Document routes), [`frontend/src/App.jsx`](https://github.com/pragy10/finesse/blob/main/frontend/src/App.jsx) (App routes), [`backend/server.js`](https://github.com/pragy10/finesse/blob/main/backend/server.js) (Express server), [`backend/routes/ask.js`](https://github.com/pragy10/finesse/blob/main/backend/routes/ask.js) (Answer route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_app["App routes<br/>[App.jsx]"]
  node_authctx["Auth state<br/>[AuthContext.jsx]"]
  node_docsctx["Document state"]
  node_uploadui["PDF upload<br/>[FileUpload.jsx]"]
  node_assistant["AI assistant<br/>[AIAssistant.jsx]"]
  node_clausesearch["Clause search<br/>[ClauseSearch.jsx]"]
end

subgraph group_api["API and identity"]
  node_server["Express server<br/>[server.js]"]
  node_authmw["Token verification<br/>[auth.js]"]
  node_profile["Profile routes<br/>[profile.js]"]
end

subgraph group_ingest["Document ingestion"]
  node_documents["Document routes<br/>[documents.js]"]
  node_parser["PDF extraction<br/>[parseDocument.js]"]
  node_chunker["Smart chunking<br/>[smartChunker.js]"]
  node_storechunks["Chunk indexing<br/>[storeChunks.js]"]
end

subgraph group_answer["Search and reasoning"]
  node_embed["Text embeddings<br/>[embed.js]"]
  node_ask["Answer route<br/>[ask.js]"]
  node_query["Search route<br/>[query.js]"]
  node_reasoner["AI reasoning<br/>[reasoningEngine.js]"]
  node_openrouter["LLM client"]
end

subgraph group_services["Data and monitoring"]
  node_firestore[("Firestore metadata<br/>[firebaseAdmin.js]")]
  node_supabase[("PDF storage<br/>[supabaseClient.js]")]
  node_qdrant[("Vector database<br/>[qdrantClient.js]")]
  node_metrics["Prometheus metrics<br/>[metrics.js]"]
  node_firebase["Firebase Auth<br/>[firebase.js]"]
end

node_user(("Policy holder"))
node_llmservice{{"OpenRouter service"}}

node_user -->|"uses"| node_app
node_app -->|"provides auth"| node_authctx
node_app -->|"provides documents"| node_docsctx
node_app -->|"hosts workflow"| node_uploadui
node_app -->|"hosts workflow"| node_assistant
node_app -->|"hosts workflow"| node_clausesearch
node_authctx -->|"authenticates with"| node_firebase
node_authctx -->|"fetches profile"| node_profile
node_docsctx -->|"loads and manages"| node_documents
node_uploadui -->|"uploads PDFs"| node_documents
node_assistant -->|"asks questions"| node_ask
node_clausesearch -->|"searches clauses"| node_query
node_server -->|"mounts routes"| node_documents
node_server -->|"mounts routes"| node_profile
node_server -->|"mounts routes"| node_query
node_server -->|"mounts routes"| node_ask
node_server -->|"records traffic"| node_metrics
node_documents -->|"requires auth"| node_authmw
node_documents -->|"extracts text"| node_parser
node_documents -->|"chunks text"| node_chunker
node_documents -->|"stores PDFs"| node_supabase
node_documents -->|"indexes chunks"| node_storechunks
node_documents -->|"writes metadata"| node_firestore
node_storechunks -->|"embeds chunks"| node_embed
node_storechunks -->|"writes vectors"| node_qdrant
node_query -->|"embeds query"| node_embed
node_query -->|"searches vectors"| node_qdrant
node_ask -->|"embeds query"| node_embed
node_ask -->|"retrieves matches"| node_qdrant
node_ask -->|"generates answer"| node_reasoner
node_reasoner -->|"requests completion"| node_openrouter
node_openrouter -->|"calls API"| node_llmservice
node_profile -->|"requires auth"| node_authmw
node_profile -->|"reads and writes"| node_firestore
node_authmw -->|"verifies token"| node_firestore

click node_app "https://github.com/pragy10/finesse/blob/main/frontend/src/App.jsx"
click node_authctx "https://github.com/pragy10/finesse/blob/main/frontend/src/context/AuthContext.jsx"
click node_docsctx "https://github.com/pragy10/finesse/blob/main/frontend/src/context/DocumentContext.jsx"
click node_uploadui "https://github.com/pragy10/finesse/blob/main/frontend/src/components/features/FileUpload.jsx"
click node_assistant "https://github.com/pragy10/finesse/blob/main/frontend/src/components/features/AIAssistant.jsx"
click node_clausesearch "https://github.com/pragy10/finesse/blob/main/frontend/src/components/features/ClauseSearch.jsx"
click node_server "https://github.com/pragy10/finesse/blob/main/backend/server.js"
click node_authmw "https://github.com/pragy10/finesse/blob/main/backend/middleware/auth.js"
click node_documents "https://github.com/pragy10/finesse/blob/main/backend/routes/documents.js"
click node_parser "https://github.com/pragy10/finesse/blob/main/backend/parsing/parseDocument.js"
click node_chunker "https://github.com/pragy10/finesse/blob/main/backend/setup/smartChunker.js"
click node_embed "https://github.com/pragy10/finesse/blob/main/backend/vector/embed.js"
click node_storechunks "https://github.com/pragy10/finesse/blob/main/backend/vector/storeChunks.js"
click node_ask "https://github.com/pragy10/finesse/blob/main/backend/routes/ask.js"
click node_query "https://github.com/pragy10/finesse/blob/main/backend/routes/query.js"
click node_reasoner "https://github.com/pragy10/finesse/blob/main/backend/llm/reasoningEngine.js"
click node_openrouter "https://github.com/pragy10/finesse/blob/main/backend/config/openRouterClient.js"
click node_firestore "https://github.com/pragy10/finesse/blob/main/backend/config/firebaseAdmin.js"
click node_supabase "https://github.com/pragy10/finesse/blob/main/backend/config/supabaseClient.js"
click node_qdrant "https://github.com/pragy10/finesse/blob/main/backend/vector/qdrantClient.js"
click node_profile "https://github.com/pragy10/finesse/blob/main/backend/routes/profile.js"
click node_metrics "https://github.com/pragy10/finesse/blob/main/backend/config/metrics.js"
click node_firebase "https://github.com/pragy10/finesse/blob/main/frontend/src/config/firebase.js"

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_authctx,node_docsctx,node_uploadui,node_assistant,node_clausesearch toneBlue
class node_server,node_authmw,node_profile toneAmber
class node_documents,node_parser,node_chunker,node_storechunks,node_llmservice toneMint
class node_embed,node_ask,node_query,node_reasoner,node_openrouter toneRose
class node_firestore,node_supabase,node_qdrant,node_metrics,node_firebase,node_user toneIndigo
```

## Components

### Web experience

- [App routes](https://github.com/pragy10/finesse/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/pragy10/finesse/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Document state](https://github.com/pragy10/finesse/blob/main/frontend/src/context/DocumentContext.jsx): `frontend/src/context/DocumentContext.jsx`
- [PDF upload](https://github.com/pragy10/finesse/blob/main/frontend/src/components/features/FileUpload.jsx): `frontend/src/components/features/FileUpload.jsx`
- [AI assistant](https://github.com/pragy10/finesse/blob/main/frontend/src/components/features/AIAssistant.jsx): `frontend/src/components/features/AIAssistant.jsx`
- [Clause search](https://github.com/pragy10/finesse/blob/main/frontend/src/components/features/ClauseSearch.jsx): `frontend/src/components/features/ClauseSearch.jsx`

### API and identity

- [Express server](https://github.com/pragy10/finesse/blob/main/backend/server.js): `backend/server.js`
- [Token verification](https://github.com/pragy10/finesse/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`
- [Profile routes](https://github.com/pragy10/finesse/blob/main/backend/routes/profile.js): `backend/routes/profile.js`

### Document ingestion

- [Document routes](https://github.com/pragy10/finesse/blob/main/backend/routes/documents.js): `backend/routes/documents.js`
- [PDF extraction](https://github.com/pragy10/finesse/blob/main/backend/parsing/parseDocument.js): `backend/parsing/parseDocument.js`
- [Smart chunking](https://github.com/pragy10/finesse/blob/main/backend/setup/smartChunker.js): `backend/setup/smartChunker.js`
- [Chunk indexing](https://github.com/pragy10/finesse/blob/main/backend/vector/storeChunks.js): `backend/vector/storeChunks.js`

### Search and reasoning

- [Text embeddings](https://github.com/pragy10/finesse/blob/main/backend/vector/embed.js): `backend/vector/embed.js`
- [Answer route](https://github.com/pragy10/finesse/blob/main/backend/routes/ask.js): `backend/routes/ask.js`
- [Search route](https://github.com/pragy10/finesse/blob/main/backend/routes/query.js): `backend/routes/query.js`
- [AI reasoning](https://github.com/pragy10/finesse/blob/main/backend/llm/reasoningEngine.js): `backend/llm/reasoningEngine.js`
- [LLM client](https://github.com/pragy10/finesse/blob/main/backend/config/openRouterClient.js): `backend/config/openRouterClient.js`

### Data and monitoring

- [Firestore metadata](https://github.com/pragy10/finesse/blob/main/backend/config/firebaseAdmin.js): `backend/config/firebaseAdmin.js`
- [PDF storage](https://github.com/pragy10/finesse/blob/main/backend/config/supabaseClient.js): `backend/config/supabaseClient.js`
- [Vector database](https://github.com/pragy10/finesse/blob/main/backend/vector/qdrantClient.js): `backend/vector/qdrantClient.js`
- [Prometheus metrics](https://github.com/pragy10/finesse/blob/main/backend/config/metrics.js): `backend/config/metrics.js`
- [Firebase Auth](https://github.com/pragy10/finesse/blob/main/frontend/src/config/firebase.js): `frontend/src/config/firebase.js`

### Other components

- **Policy holder**
- **OpenRouter service**

## Connections

- Policy holder → App routes: uses (evidence: `README.md`)
- App routes → Auth state: provides auth (evidence: `frontend/src/App.jsx`)
- App routes → Document state: provides documents (evidence: `frontend/src/App.jsx`)
- App routes → PDF upload: hosts workflow
- App routes → AI assistant: hosts workflow
- App routes → Clause search: hosts workflow
- Auth state → Firebase Auth: authenticates with (evidence: `frontend/src/context/AuthContext.jsx`)
- Auth state → Profile routes: fetches profile (evidence: `frontend/src/context/AuthContext.jsx`)
- Document state → Document routes: loads and manages (evidence: `frontend/src/context/DocumentContext.jsx`)
- PDF upload → Document routes: uploads PDFs (evidence: `README.md`)
- AI assistant → Answer route: asks questions (evidence: `README.md`)
- Clause search → Search route: searches clauses (evidence: `README.md`)
- Express server → Document routes: mounts routes (evidence: `backend/server.js`)
- Express server → Profile routes: mounts routes (evidence: `backend/server.js`)
- Express server → Search route: mounts routes (evidence: `backend/server.js`)
- Express server → Answer route: mounts routes (evidence: `backend/server.js`)
- Express server → Prometheus metrics: records traffic (evidence: `backend/server.js`)
- Document routes → Token verification: requires auth (evidence: `backend/routes/documents.js`)
- Document routes → PDF extraction: extracts text (evidence: `backend/routes/documents.js`)
- Document routes → Smart chunking: chunks text (evidence: `backend/routes/documents.js`)
- Document routes → PDF storage: stores PDFs (evidence: `backend/routes/documents.js`)
- Document routes → Chunk indexing: indexes chunks (evidence: `backend/routes/documents.js`)
- Document routes → Firestore metadata: writes metadata (evidence: `backend/routes/documents.js`)
- Chunk indexing → Text embeddings: embeds chunks (evidence: `backend/vector/storeChunks.js`)
- Chunk indexing → Vector database: writes vectors (evidence: `backend/vector/storeChunks.js`)
- Search route → Text embeddings: embeds query (evidence: `backend/routes/query.js`)
- Search route → Vector database: searches vectors (evidence: `backend/routes/query.js`)
- Answer route → Text embeddings: embeds query (evidence: `backend/routes/ask.js`)
- Answer route → Vector database: retrieves matches (evidence: `backend/routes/ask.js`)
- Answer route → AI reasoning: generates answer (evidence: `backend/routes/ask.js`)
- AI reasoning → LLM client: requests completion (evidence: `backend/llm/reasoningEngine.js`)
- LLM client → OpenRouter service: calls API (evidence: `backend/config/openRouterClient.js`)
- Profile routes → Token verification: requires auth (evidence: `backend/routes/profile.js`)
- Profile routes → Firestore metadata: reads and writes (evidence: `backend/routes/profile.js`)
- Token verification → Firestore metadata: verifies token (evidence: `backend/middleware/auth.js`)
