# harshvaibhav09/opspilot architecture

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

- Interactive diagram: https://gitdiagram.com/harshvaibhav09/opspilot
- Repository: https://github.com/harshvaibhav09/opspilot

## Overview

OpsPilot is a logistics document-intelligence assistant. Users upload PDFs, receive background processing and per-file progress, then ask typed or spoken questions grounded in those documents; answers include citations, and voice playback is an optional presentation path over the same chat. The backend classifies and chunks documents, embeds and stores them, retrieves relevant passages, and generates answers while retaining session history. The README documents contradiction analysis and developer retrieval details. Some implementation files were not excerpted, so those features are represented at subsystem level and only documented relationships are shown.

Main entry points: [`backend/app/services/chat_service.py`](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/chat_service.py) (Chat orchestration), [`frontend/src/components/ChatWindow.jsx`](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/components/ChatWindow.jsx) (Chat interface), [`backend/app/services/ingestion_service.py`](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/ingestion_service.py) (PDF ingestion), [`frontend/src/services/api.js`](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web client"]
  node_app["App shell<br/>[App.jsx]"]
  node_chatui["Chat interface<br/>[ChatWindow.jsx]"]
  node_uploadui["Upload and library<br/>[Uploader.jsx]"]
  node_speech["Speech input"]
  node_audio["Audio playback<br/>[audioPlayer.js]"]
  node_client["API client<br/>[api.js]"]
end

subgraph group_api["Backend API"]
  node_api_routes["API routes<br/>[main.py]"]
  node_chat_api["Chat endpoint<br/>[chat.py]"]
  node_docs_api["Document endpoints<br/>[documents.py]"]
  node_voice_api["Voice endpoint<br/>[voice.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_ingest["PDF ingestion"]
  node_classify["Document classification"]
  node_chunk["Type-aware chunking<br/>[chunkers.py]"]
  node_analysis["Contradiction analysis"]
  node_jobs["Upload jobs<br/>[job_service.py]"]
end

subgraph group_qa["Chat and retrieval"]
  node_chat["Chat orchestration<br/>[chat_service.py]"]
  node_retrieval["Hybrid retrieval"]
  node_embed["Embedding service"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
end

subgraph group_platform["State and integrations"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_vector[("Vector and BM25 store<br/>[vector_store.py]")]
  node_sessions[("Session store<br/>[session_store.py]")]
  node_memory["Conversation memory<br/>[memory_service.py]"]
  node_voice["Speech synthesis<br/>[voice_service.py]"]
end

node_user(("Ops user"))
node_groq{{"Groq service"}}

node_user -->|"uses"| node_app
node_app -->|"creates session"| node_client
node_app -->|"renders"| node_chatui
node_app -->|"shows library"| node_uploadui
node_chatui -->|"sends chat"| node_client
node_chatui -->|"accepts voice"| node_speech
node_chatui -->|"plays answer"| node_audio
node_uploadui -->|"uploads files"| node_client
node_client -->|"calls API"| node_api_routes
node_api_routes -->|"routes chat"| node_chat_api
node_api_routes -->|"routes documents"| node_docs_api
node_api_routes -->|"routes voice"| node_voice_api
node_chat_api -->|"handles message"| node_chat
node_chat_api -->|"loads history"| node_memory
node_docs_api -->|"starts background job"| node_jobs
node_jobs -->|"runs ingestion"| node_ingest
node_ingest -->|"classifies sample"| node_classify
node_ingest -->|"chunks pages"| node_chunk
node_ingest -->|"embeds chunks"| node_embed
node_ingest -->|"stores chunks"| node_vector
node_docs_api -->|"starts analysis"| node_analysis
node_chat -->|"retrieves passages"| node_retrieval
node_chat -->|"loads and saves turns"| node_memory
node_chat -->|"uses prompts"| node_prompts
node_chat -->|"generates answer"| node_llm
node_chat -->|"adds document findings"| node_analysis
node_retrieval -->|"embeds query"| node_embed
node_retrieval -->|"queries hybrid index"| node_vector
node_memory -->|"reads and writes turns"| node_sessions
node_llm -->|"requests completion"| node_groq
node_voice_api -->|"synthesizes speech"| node_voice
node_voice -.->|"uses configured provider"| node_groq
node_chatui -->|"requests speech"| node_client

click node_app "https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/App.jsx"
click node_chatui "https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/components/ChatWindow.jsx"
click node_uploadui "https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/components/Uploader.jsx"
click node_speech "https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/hooks/useSpeechRecognition.js"
click node_audio "https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/services/audioPlayer.js"
click node_client "https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/services/api.js"
click node_api_routes "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/main.py"
click node_chat_api "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/api/chat.py"
click node_docs_api "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/api/documents.py"
click node_voice_api "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/api/voice.py"
click node_ingest "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/ingestion_service.py"
click node_classify "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/classification_service.py"
click node_chunk "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/chunkers.py"
click node_analysis "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/document_analysis_service.py"
click node_jobs "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/job_service.py"
click node_chat "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/chat_service.py"
click node_retrieval "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/retrieval_service.py"
click node_embed "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/embedding_service.py"
click node_prompts "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/core/prompts.py"
click node_llm "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/core/llm_client.py"
click node_vector "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/db/vector_store.py"
click node_sessions "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/db/session_store.py"
click node_memory "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/memory_service.py"
click node_voice "https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/voice_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_chatui,node_uploadui,node_speech,node_audio,node_client,node_user toneBlue
class node_api_routes,node_chat_api,node_docs_api,node_voice_api toneAmber
class node_ingest,node_classify,node_chunk,node_analysis,node_jobs toneMint
class node_chat,node_retrieval,node_embed,node_prompts toneRose
class node_llm,node_vector,node_sessions,node_memory,node_voice,node_groq toneIndigo
```

## Components

### Web client

- [App shell](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat interface](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/components/ChatWindow.jsx): `frontend/src/components/ChatWindow.jsx`
- [Upload and library](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/components/Uploader.jsx): `frontend/src/components/Uploader.jsx`
- [Speech input](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/hooks/useSpeechRecognition.js): `frontend/src/hooks/useSpeechRecognition.js`
- [Audio playback](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/services/audioPlayer.js): `frontend/src/services/audioPlayer.js`
- [API client](https://github.com/harshvaibhav09/opspilot/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Backend API

- [API routes](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat endpoint](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Document endpoints](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Voice endpoint](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/api/voice.py): `backend/app/api/voice.py`

### Document ingestion

- [PDF ingestion](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/ingestion_service.py): `backend/app/services/ingestion_service.py`
- [Document classification](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/classification_service.py): `backend/app/services/classification_service.py`
- [Type-aware chunking](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/chunkers.py): `backend/app/services/chunkers.py`
- [Contradiction analysis](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/document_analysis_service.py): `backend/app/services/document_analysis_service.py`
- [Upload jobs](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/job_service.py): `backend/app/services/job_service.py`

### Chat and retrieval

- [Chat orchestration](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`
- [Hybrid retrieval](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/retrieval_service.py): `backend/app/services/retrieval_service.py`
- [Embedding service](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`
- [Prompt templates](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/core/prompts.py): `backend/app/core/prompts.py`

### State and integrations

- [LLM client](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/core/llm_client.py): `backend/app/core/llm_client.py`
- [Vector and BM25 store](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/db/vector_store.py): `backend/app/db/vector_store.py`
- [Session store](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/db/session_store.py): `backend/app/db/session_store.py`
- [Conversation memory](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/memory_service.py): `backend/app/services/memory_service.py`
- [Speech synthesis](https://github.com/harshvaibhav09/opspilot/blob/main/backend/app/services/voice_service.py): `backend/app/services/voice_service.py`

### Other components

- **Ops user**
- **Groq service**

## Connections

- Ops user → App shell: uses
- App shell → API client: creates session (evidence: `frontend/src/App.jsx`)
- App shell → Chat interface: renders (evidence: `frontend/src/App.jsx`)
- App shell → Upload and library: shows library (evidence: `frontend/src/App.jsx`)
- Chat interface → API client: sends chat (evidence: `frontend/src/components/ChatWindow.jsx`)
- Chat interface → Speech input: accepts voice
- Chat interface → Audio playback: plays answer (evidence: `frontend/src/components/ChatWindow.jsx`)
- Upload and library → API client: uploads files (evidence: `frontend/src/components/Uploader.jsx`)
- API client → API routes: calls API
- API routes → Chat endpoint: routes chat (evidence: `backend/app/main.py`)
- API routes → Document endpoints: routes documents (evidence: `backend/app/main.py`)
- API routes → Voice endpoint: routes voice (evidence: `backend/app/main.py`)
- Chat endpoint → Chat orchestration: handles message (evidence: `backend/app/api/chat.py`)
- Chat endpoint → Conversation memory: loads history (evidence: `backend/app/api/chat.py`)
- Document endpoints → Upload jobs: starts background job (evidence: `backend/app/api/documents.py`)
- Upload jobs → PDF ingestion: runs ingestion
- PDF ingestion → Document classification: classifies sample (evidence: `backend/app/services/ingestion_service.py`)
- PDF ingestion → Type-aware chunking: chunks pages (evidence: `backend/app/services/ingestion_service.py`)
- PDF ingestion → Embedding service: embeds chunks (evidence: `backend/app/services/ingestion_service.py`)
- PDF ingestion → Vector and BM25 store: stores chunks (evidence: `backend/app/services/ingestion_service.py`)
- Document endpoints → Contradiction analysis: starts analysis (evidence: `backend/app/api/documents.py`)
- Chat orchestration → Hybrid retrieval: retrieves passages (evidence: `backend/app/services/chat_service.py`)
- Chat orchestration → Conversation memory: loads and saves turns (evidence: `backend/app/services/chat_service.py`)
- Chat orchestration → Prompt templates: uses prompts (evidence: `backend/app/services/chat_service.py`)
- Chat orchestration → LLM client: generates answer (evidence: `backend/app/services/chat_service.py`)
- Chat orchestration → Contradiction analysis: adds document findings (evidence: `backend/app/services/chat_service.py`)
- Hybrid retrieval → Embedding service: embeds query (evidence: `backend/app/services/retrieval_service.py`)
- Hybrid retrieval → Vector and BM25 store: queries hybrid index (evidence: `backend/app/services/retrieval_service.py`)
- Conversation memory → Session store: reads and writes turns (evidence: `backend/app/services/memory_service.py`)
- LLM client → Groq service: requests completion (evidence: `backend/app/core/llm_client.py`)
- Voice endpoint → Speech synthesis: synthesizes speech (evidence: `backend/app/api/voice.py`)
- Speech synthesis → Groq service: uses configured provider
- Chat interface → API client: requests speech (evidence: `frontend/src/components/ChatWindow.jsx`)
