# mehedihasan-75/ai-document-companion architecture

> Architecture diagram of the GitHub repository mehedihasan-75/ai-document-companion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mehedihasan-75/ai-document-companion
- Repository: https://github.com/mehedihasan-75/ai-document-companion

## Overview

1. **Overall shape**
   This repo is a **FastAPI backend** for an “AI Document Companion” system: users authenticate, upload documents, trigger ingestion, and then ask questions in persisted conversations. The architecture is cleanly layered into **routes → dependencies → services → models/schemas → DB/vector stores**.

2. **HTTP boundary**
   `src/main.py` builds the FastAPI app and wires routers from `src/routes/`. The route layer is split by domain: `auth_routes.py`, `file_routes.py`, `process_routes.py`, and `conversation_routes.py`. The API includes both standard JSON endpoints and a **streaming SSE endpoint** for chat responses.

3. **Authentication and request scoping**
   Authentication is JWT-based. `src/dependencies/auth.py` resolves the current user from the bearer token, and protected routes depend on that user object. This is the main multi-tenant boundary: nearly every file/document/conversation/query path is scoped by `user_id`.

4. **Document upload and file handling**
   `file_routes.py` and `file_service.py` handle upload validation, MIME/type allowlisting, size checks, and file persistence under an upload directory. Uploaded files are represented in the database as `Document` records, with later processing separated from the initial upload.

5. **Background ingestion pipeline**
   Processing is intentionally decoupled from upload. `process_routes.py` triggers `process_service.py`, which dispatches ingestion as a background task and writes status artifacts that clients can poll. The ingestion path runs through `ingestion_service.py`, `unstructured_service.py`, `chunk_service.py`, and `document_service.py`.

6. **Multimodal parsing and chunking**
   The ingestion pipeline uses **Unstructured** in hi-res mode to parse PDFs, DOCX, PPTX, spreadsheets, CSV, HTML, JSON, markdown, and text into typed elements. Those elements are then chunked by title/heading structure rather than raw character splitting, preserving tables, lists, and section boundaries.

7. **Dual-store retrieval architecture**
   The core RAG design uses two stores:
   - **ChromaDB** for vector retrieval of **summaries** of chunks
   - **SQLite docstore** for the **original chunk content**
   
   `vector_service.py` manages both stores, while `retrieval_service.py` and `rag_chain.py` resolve retrieved summary hits back to originals before generation. This is a key architectural boundary: retrieval is summary-based, generation is original-text-based.

8. **LLM and summarization services**
   `llm_service.py` centralizes model instances, and the repo assumes **local Ollama** as the LLM runtime. Different models are used for different jobs: text summarization/QA and vision summarization for images. That makes ingestion and answer generation dependent on local model availability rather than external SaaS APIs.

9. **Conversation memory and answer generation**
   Conversations are first-class database entities in `conversation.py` and `message.py`. `conversation_service.py` loads a bounded history window from the DB, persists each user/assistant turn, and stores source metadata per assistant message. The RAG chain is composed in `rag_chain.py`, and `streaming_service.py` turns chain events into SSE status/delta/completion events.

10. **Data model and persistence**
    SQLAlchemy models under `src/models/` define the durable state: `User`, `Document`, `Chunk`, `Conversation`, and `Message`. `src/db/` contains the engine/session setup and shared base/mixin patterns. This repo is built to work with **SQLite for local development** and **PostgreSQL-compatible configuration** for production.

11. **Validation, schemas, and error boundaries**
    `src/schemas/` defines request/response contracts for auth, file, and conversation flows. `src/core/exceptions.py` provides the service-level error boundary so internal failures are translated into controlled HTTP responses, rather than leaking implementation details.

12. **Supporting layers and configuration**
    `src/config/` centralizes environment settings, constants, file-type allowlists, and prompt templates. `src/core/logger.py` handles logging. The repo also includes docs for auth, DB, FastAPI, frontend SSE integration, and the full RAG pipeline, which are useful references when drawing the architecture diagram.

13. **External/runtime dependencies that matter architecturally**
    The main external pieces are **Ollama** for local LLM inference, **Unstructured** for layout-aware document parsing, **ChromaDB** for vector search, and **SQLAlchemy** for relational persistence. These are not just libraries; they define the system’s runtime topology: file upload and DB-backed metadata are local, while LLM inference and vector retrieval sit in separate service boundaries.

14. **Primary end-to-end data flow**
    The main flow is: **upload file → store metadata → background ingestion → parse/chunk/summarize → write summary vectors to Chroma + originals to SQLite docstore → user asks question in a conversation → retrieve by vector search → resolve originals → build prompt with history and citations → stream answer via SSE → persist message and sources**.

Main entry points: [`src/db/base.py`](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/db/base.py) (Base), [`src/routes/index.py`](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/index.py) (Router Index), [`src/services/ingestion_service.py`](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/ingestion_service.py) (Ingestion), [`src/services/conversation_service.py`](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/conversation_service.py) (Conversation Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_routes["HTTP API"]
  node_src_main["App<br/>FastAPI entry<br/>[main.py]"]
  node_src_routes_index["Router Index<br/>router registry<br/>[index.py]"]
  node_src_routes_auth["Auth Routes<br/>HTTP routes<br/>[auth_routes.py]"]
  node_src_routes_files["File Routes<br/>HTTP routes<br/>[file_routes.py]"]
  node_src_routes_process["Process Routes<br/>HTTP routes<br/>[process_routes.py]"]
  node_src_routes_conversation["Chat Routes<br/>HTTP routes"]
end

subgraph group_group_services["Application Services"]
  node_src_services_file["File Service<br/>upload service<br/>[file_service.py]"]
  node_src_services_process["Process Service<br/>job orchestration<br/>[process_service.py]"]
  node_src_services_ingestion["Ingestion<br/>pipeline service"]
  node_src_services_unstructured["Parser"]
  node_src_services_chunk["Chunker<br/>content chunking<br/>[chunk_service.py]"]
  node_src_services_document["Document Service<br/>document persistence"]
  node_src_services_vector["Vector Store<br/>dual store<br/>[vector_service.py]"]
  node_src_services_retrieval["Retriever<br/>retrieval service"]
  node_src_services_rag["RAG Chain<br/>answer chain<br/>[rag_chain.py]"]
  node_src_services_streaming["Streaming<br/>SSE adapter"]
  node_src_services_conversation["Conversation Service"]
  node_src_services_llm["LLM Service<br/>model runtime<br/>[llm_service.py]"]
end

subgraph group_group_data["Data Layer"]
  node_src_models_user[("User<br/>ORM model<br/>[user.py]")]
  node_src_models_document[("Document<br/>ORM model<br/>[document.py]")]
  node_src_models_chunk[("Chunk<br/>ORM model<br/>[chunk.py]")]
  node_src_models_conversation[("Conversation<br/>ORM model<br/>[conversation.py]")]
  node_src_models_message[("Message<br/>ORM model<br/>[message.py]")]
  node_src_db_session[("Session<br/>DB setup<br/>[session.py]")]
  node_src_db_base[("Base<br/>[base.py]")]
end

subgraph group_group_support["Support"]
  node_src_dependencies_auth["Auth Dep<br/>JWT dependency<br/>[auth.py]"]
  node_src_dependencies_db["DB Dep<br/>session dependency<br/>[db.py]"]
  node_src_config["Config<br/>settings<br/>[environment.py]"]
  node_src_core["Core<br/>shared utilities<br/>[exceptions.py]"]
end

node_src_main -->|"includes"| node_src_routes_index
node_src_routes_index -->|"mounts"| node_src_routes_auth
node_src_routes_index -->|"mounts"| node_src_routes_files
node_src_routes_index -->|"mounts"| node_src_routes_process
node_src_routes_index -->|"mounts"| node_src_routes_conversation
node_src_routes_auth -->|"uses"| node_src_dependencies_db
node_src_routes_files -->|"scopes"| node_src_dependencies_auth
node_src_routes_files -->|"calls"| node_src_services_file
node_src_routes_process -->|"scopes"| node_src_dependencies_auth
node_src_routes_process -->|"calls"| node_src_services_process
node_src_routes_conversation -->|"scopes"| node_src_dependencies_auth
node_src_routes_conversation -->|"calls"| node_src_services_conversation
node_src_routes_conversation -->|"streams via"| node_src_services_streaming
node_src_services_file -->|"writes"| node_src_models_document
node_src_services_process -->|"dispatches"| node_src_services_ingestion
node_src_services_ingestion -->|"parses with"| node_src_services_unstructured
node_src_services_ingestion -->|"chunks with"| node_src_services_chunk
node_src_services_ingestion -->|"persists via"| node_src_services_document
node_src_services_ingestion -->|"indexes via"| node_src_services_vector
node_src_services_chunk -->|"produces"| node_src_models_chunk
node_src_services_document -->|"updates"| node_src_models_document
node_src_services_document -->|"stores"| node_src_models_chunk
node_src_services_vector -->|"summarizes with"| node_src_services_llm
node_src_services_retrieval -->|"queries"| node_src_services_vector
node_src_services_rag -->|"retrieves"| node_src_services_retrieval
node_src_services_rag -->|"loads history"| node_src_services_conversation
node_src_services_rag -->|"generates with"| node_src_services_llm
node_src_services_streaming -->|"consumes"| node_src_services_rag
node_src_services_conversation -->|"writes"| node_src_models_conversation
node_src_services_conversation -->|"writes"| node_src_models_message
node_src_dependencies_auth -->|"resolves"| node_src_models_user
node_src_db_session -->|"builds on"| node_src_db_base
node_src_models_user -->|"extends"| node_src_db_base
node_src_models_document -->|"extends"| node_src_db_base
node_src_models_chunk -->|"extends"| node_src_db_base
node_src_models_conversation -->|"extends"| node_src_db_base
node_src_models_message -->|"extends"| node_src_db_base
node_src_services_file -->|"uses"| node_src_dependencies_db
node_src_services_process -->|"uses"| node_src_dependencies_db
node_src_services_conversation -->|"uses"| node_src_dependencies_db
node_src_core -->|"relies on"| node_src_config

click node_src_main "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/main.py"
click node_src_routes_index "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/index.py"
click node_src_routes_auth "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/auth_routes.py"
click node_src_routes_files "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/file_routes.py"
click node_src_routes_process "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/process_routes.py"
click node_src_routes_conversation "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/conversation_routes.py"
click node_src_dependencies_auth "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/dependencies/auth.py"
click node_src_dependencies_db "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/dependencies/db.py"
click node_src_services_file "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/file_service.py"
click node_src_services_process "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/process_service.py"
click node_src_services_ingestion "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/ingestion_service.py"
click node_src_services_unstructured "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/unstructured_service.py"
click node_src_services_chunk "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/chunk_service.py"
click node_src_services_document "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/document_service.py"
click node_src_services_vector "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/vector_service.py"
click node_src_services_retrieval "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/retrieval_service.py"
click node_src_services_rag "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/rag_chain.py"
click node_src_services_streaming "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/streaming_service.py"
click node_src_services_conversation "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/conversation_service.py"
click node_src_services_llm "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/llm_service.py"
click node_src_models_user "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/user.py"
click node_src_models_document "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/document.py"
click node_src_models_chunk "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/chunk.py"
click node_src_models_conversation "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/conversation.py"
click node_src_models_message "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/message.py"
click node_src_db_session "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/db/session.py"
click node_src_db_base "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/db/base.py"
click node_src_config "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/config/environment.py"
click node_src_core "https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/core/exceptions.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_src_main,node_src_routes_index,node_src_routes_auth,node_src_routes_files,node_src_routes_process,node_src_routes_conversation toneBlue
class node_src_services_file,node_src_services_process,node_src_services_ingestion,node_src_services_unstructured,node_src_services_chunk,node_src_services_document,node_src_services_vector,node_src_services_retrieval,node_src_services_rag,node_src_services_streaming,node_src_services_conversation,node_src_services_llm toneAmber
class node_src_models_user,node_src_models_document,node_src_models_chunk,node_src_models_conversation,node_src_models_message,node_src_db_session,node_src_db_base toneMint
class node_src_dependencies_auth,node_src_dependencies_db,node_src_config,node_src_core toneRose
```

## Components

### HTTP API

FastAPI app and request handlers

- [App](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/main.py): FastAPI entry · Builds the FastAPI application and wires routers · `src/main.py`
- [Router Index](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/index.py): router registry · Aggregates route modules into the app · `src/routes/index.py`
- [Auth Routes](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/auth_routes.py): HTTP routes · Login and token-related endpoints · `src/routes/auth_routes.py`
- [File Routes](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/file_routes.py): HTTP routes · Document upload and file lifecycle endpoints · `src/routes/file_routes.py`
- [Process Routes](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/process_routes.py): HTTP routes · Endpoints for triggering ingestion and processing · `src/routes/process_routes.py`
- [Chat Routes](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/routes/conversation_routes.py): HTTP routes · Conversation and streaming question-answer endpoints · `src/routes/conversation_routes.py`

### Application Services

Business logic, ingestion, retrieval, and response orchestration

- [File Service](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/file_service.py): upload service · Validates, stores, and registers uploaded files · `src/services/file_service.py`
- [Process Service](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/process_service.py): job orchestration · Starts background ingestion and tracks processing status · `src/services/process_service.py`
- [Ingestion](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/ingestion_service.py): pipeline service · Coordinates parsing, chunking, and persistence of document content · `src/services/ingestion_service.py`
- [Parser](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/unstructured_service.py): document parser · Uses Unstructured to extract typed elements from files · `src/services/unstructured_service.py`
- [Chunker](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/chunk_service.py): content chunking · Builds structure-aware chunks from parsed elements · `src/services/chunk_service.py`
- [Document Service](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/document_service.py): document persistence · Stores document and chunk metadata in the relational store · `src/services/document_service.py`
- [Vector Store](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/vector_service.py): dual store · Manages Chroma vector search and SQLite docstore access · `src/services/vector_service.py`
- [Retriever](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/retrieval_service.py): retrieval service · Resolves summary hits back to original chunks for answering · `src/services/retrieval_service.py`
- [RAG Chain](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/rag_chain.py): answer chain · Builds prompts, history, retrieval context, and citations · `src/services/rag_chain.py`
- [Streaming](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/streaming_service.py): SSE adapter · Converts chain events into streaming response events · `src/services/streaming_service.py`
- [Conversation Service](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/conversation_service.py): conversation service · Persists turns and loads bounded conversation history · `src/services/conversation_service.py`
- [LLM Service](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/services/llm_service.py): model runtime · Centralizes local Ollama model access for summarization and QA · `src/services/llm_service.py`

### Data Layer

ORM models and database/session infrastructure

- [User](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/user.py): ORM model · Authenticated account identity · `src/models/user.py`
- [Document](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/document.py): ORM model · Uploaded document metadata and processing state · `src/models/document.py`
- [Chunk](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/chunk.py): ORM model · Persisted chunk metadata and content references · `src/models/chunk.py`
- [Conversation](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/conversation.py): ORM model · Persistent chat thread for a user · `src/models/conversation.py`
- [Message](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/models/message.py): ORM model · Stored user and assistant turns with source metadata · `src/models/message.py`
- [Session](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/db/session.py): DB setup · Engine and session configuration for relational persistence · `src/db/session.py`
- [Base](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/db/base.py): ORM base · Shared declarative base and model foundation · `src/db/base.py`

### Support

Config, dependencies, and shared core utilities

- [Auth Dep](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/dependencies/auth.py): JWT dependency · Resolves the current user from bearer token · `src/dependencies/auth.py`
- [DB Dep](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/dependencies/db.py): session dependency · Provides database sessions to application layers · `src/dependencies/db.py`
- [Config](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/config/environment.py): settings · Environment settings, constants, file types, and prompts · `src/config/environment.py`
- [Core](https://github.com/mehedihasan-75/ai-document-companion/blob/main/src/core/exceptions.py): shared utilities · Central exception handling and logging · `src/core/exceptions.py`

## Connections

- App → Router Index: includes · Registers the API routers
- Router Index → Auth Routes: mounts · Exposes authentication endpoints
- Router Index → File Routes: mounts · Exposes upload endpoints
- Router Index → Process Routes: mounts · Exposes ingestion trigger endpoints
- Router Index → Chat Routes: mounts · Exposes chat endpoints
- Auth Routes → DB Dep: uses · Requires database access
- File Routes → Auth Dep: scopes · Requires authenticated user context
- File Routes → File Service: calls · Delegates file validation and persistence
- Process Routes → Auth Dep: scopes · Requires authenticated user context
- Process Routes → Process Service: calls · Starts ingestion jobs
- Chat Routes → Auth Dep: scopes · Requires authenticated user context
- Chat Routes → Conversation Service: calls · Loads and saves conversation turns
- Chat Routes → Streaming: streams via · Serves SSE chat responses
- File Service → Document: writes · Creates document records
- Process Service → Ingestion: dispatches · Hands off work to the ingestion pipeline
- Ingestion → Parser: parses with · Extracts typed elements from files
- Ingestion → Chunker: chunks with · Builds structure-aware chunks
- Ingestion → Document Service: persists via · Stores document and chunk metadata
- Ingestion → Vector Store: indexes via · Writes summaries to vector store and originals to docstore
- Chunker → Chunk: produces · Creates chunk entities
- Document Service → Document: updates · Maintains document state
- Document Service → Chunk: stores · Persists chunk records
- Vector Store → LLM Service: summarizes with · Uses local models for summaries and QA
- Retriever → Vector Store: queries · Performs vector search and docstore lookup
- RAG Chain → Retriever: retrieves · Fetches relevant context
- RAG Chain → Conversation Service: loads history · Uses prior turns as chat context
- RAG Chain → LLM Service: generates with · Invokes local LLM for final answers
- Streaming → RAG Chain: consumes · Turns chain output into SSE events
- Conversation Service → Conversation: writes · Persists threads
- Conversation Service → Message: writes · Persists turns and source metadata
- Auth Dep → User: resolves · Converts token claims into a user identity
- Session → Base: builds on · Session setup uses the shared ORM base
- User → Base: extends · ORM entity
- Document → Base: extends · ORM entity
- Chunk → Base: extends · ORM entity
- Conversation → Base: extends · ORM entity
- Message → Base: extends · ORM entity
- File Service → DB Dep: uses · Requires a database session
- Process Service → DB Dep: uses · Persists processing status
- Conversation Service → DB Dep: uses · Loads and stores chat history
- Core → Config: relies on · Shared errors and logging follow app settings
