# vivekdeshmukhrepos/document-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/vivekdeshmukhrepos/document-intelligence
- Repository: https://github.com/vivekdeshmukhrepos/document-intelligence

## Overview

This is a **single-service Flask web application** that implements a **RAG (Retrieval-Augmented Generation) document Q&A system**:

- Users **upload documents (PDF/TXT)** via a browser UI (or `/upload`).
- The server **extracts text**, **chunks** it, **embeds** chunks using **OpenAI embeddings**, and stores vectors in **ChromaDB** (persistent).
- The original file is stored in **AWS S3**.
- Users **ask questions** via UI (or `/query`); the server embeds the query, performs **top-k similarity search** in ChromaDB, builds a prompt, and calls **GPT-4** to answer.

##### Runtime entrypoint / composition root
- `app/main.py`: Flask app, routes, orchestration of upload + query flows

##### Configuration
- `app/config.py`: env-driven settings (model name, chunk sizes, k, vector db path, keys)

##### “Models” (in this repo, means “data layer”)
- `app/models/vector_store.py`: **VectorStore** wrapper around **ChromaDB** + **OpenAI Embeddings**

##### “Services” (integration / business logic)
- `app/services/llm_service.py`: **LLMService** that:
- calls VectorStore similarity search
- builds context/prompt
- calls GPT-4
- tracks conversation memory/history (in-process)
- `app/services/storage_service.py`: **S3Storage** wrapper (boto3) for upload/download

##### Data
- `data/RAG-White-Paper.pdf`: sample/local document (not required at runtime, but indicates expected inputs)

This strongly implies a **modular monolith**: one Flask server process, structured as routes → services → integrations.

##### What the README adds (must be reflected explicitly)

- Ingestion chunking: **1000 chars** with **200 overlap**
- Embedding model: **text-embedding-3-small**, **1536 dims**
- Retrieval: **cosine similarity**, **k=4**
- LLM: **GPT-4-0613**, temperature **0.7**
- Persistence:
- **ChromaDB persistent storage path** (`VECTOR_DB_PATH`)
- **S3 bucket** for original docs
- Endpoints:
- `GET /` serves UI
- `POST /upload` ingestion pipeline
- `POST /query` RAG pipeline

##### Flask → Browser: “answer JSON”

Critically: show **retrieval before generation**, and show that **chat history is internal state** (memory) that affects prompts.

Small callouts/annotations:
- **RAG Pattern**: Retrieval (ChromaDB) → Augment (context in prompt) → Generation (GPT-4)
- **Modular Monolith**: one Flask service, internal modules
- **Externalized config**: `.env` → `config.py`
- **Persistence split**:
- Vector persistence: ChromaDB on disk
- Original document storage: S3

- Flask 2.3.3
- LangChain components (text splitter, OpenAI wrappers)
- ChromaDB (vector DB)
- OpenAI Embeddings model (text-embedding-3-small, 1536 dims)
- OpenAI GPT-4-0613 (temp 0.7)
- boto3 / AWS S3
- pypdf + unstructured

Browser ↔ Flask App ↔ (OpenAI API, S3, ChromaDB on disk).
This is the executive view.

Includes extraction → chunk → embed → store → S3 upload.

Includes query embed → similarity search → prompt build (history+context) → GPT-4.

- “Flask Server / Routes” → `app/main.py`
- “Config” → `app/config.py`
- “VectorStore (ChromaDB + embeddings)” → `app/models/vector_store.py`
- “LLMService (GPT-4 + history)” → `app/services/llm_service.py`
- “S3Storage” → `app/services/storage_service.py`
- “UI” → `app/templates/index.html`, `app/static/style.css`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% C4-ish Container + Flows
  %% =========================

  U["User"]:::client
  B["Browser"]:::client

  subgraph "Presentation (Web)"
    UI["Web UI (Upload + Chat)"]:::ui
    UIHTML["index.html (template)"]:::ui
    UICSS["style.css (static)"]:::ui
  end

  subgraph "Single Flask Service (Modular Monolith)"
    APPINIT["App Package Init"]:::app
    CFG["Config (env-driven)"]:::app

    FLASK["Flask 2.3.3 Server"]:::app
    R0["Route: GET /"]:::route
    R1["Route: POST /upload"]:::route
    R2["Route: POST /query"]:::route

    subgraph "Ingestion Pipeline (orchestrated in routes)"
      DP["Document Processing"]:::app
      EX["Text Extraction (pypdf + unstructured)"]:::app
      CH["Chunking (RecursiveCharacterTextSplitter)"]:::app
    end

    VS["VectorStore (ChromaDB + OpenAI Embeddings)"]:::app

    subgraph "Q&A Orchestration"
      LLM["LLMService (Prompt + Memory + GPT-4)"]:::app
      MEM["Conversation History (in-process)"]:::state
      PB["Prompt Builder"]:::app
    end

    S3SVC["S3Storage (boto3 wrapper)"]:::app
  end

  subgraph "Local Persistence"
    CHROMA[("ChromaDB (persistent collection)")]:::store
    DISK[("Disk/Volume (VECTOR_DB_PATH)")]:::store
  end

  subgraph "Cloud Storage (AWS)"
    S3[("S3 Bucket (raw documents)")]:::store
  end

  subgraph "External SaaS (OpenAI)"
    OAIE["Embeddings API (text-embedding-3-small, 1536 dims)"]:::external
    OAIG["Chat Completions (GPT-4-0613, temp=0.7)"]:::external
  end

  subgraph "Data Artifacts (RAG Forms)"
    RAW["Raw PDF/TXT"]:::artifact
    TXT["Extracted Text"]:::artifact
    CHUNKS["Chunks (1000 chars, overlap 200)"]:::artifact
    VECS["Embeddings (vectors)"]:::artifact
    TOPK["Top-k Context (k=4, cosine)"]:::artifact
    PROMPT["Prompt (system+history+context+question)"]:::artifact
  end

  subgraph "Repo Meta"
    REQ["Python Dependencies"]:::meta
    DOCS["README / Run + Architecture Notes"]:::meta
    SAMPLE["Sample Document"]:::meta
  end

  %% --- Client/UI wiring ---
  U -->|"uses"| B
  B -->|"GET /"| R0
  R0 -->|"renders"| UI
  UI -->|"includes"| UIHTML
  UI -->|"styles"| UICSS

  %% --- Routes composition ---
  FLASK -->|"handles"| R0
  FLASK -->|"handles"| R1
  FLASK -->|"handles"| R2
  CFG -->|"configures"| FLASK
  APPINIT -->|"initializes"| FLASK

  %% =========================
  %% Upload / Ingestion Flow
  %% =========================
  UI -->|"multipart_upload"| R1
  R1 -->|"accept_file"| RAW
  R1 -->|"orchestrate"| DP
  DP -->|"extract_text"| EX
  EX -->|"produces"| TXT
  DP -->|"chunk_text"| CH
  CH -->|"split_1000_overlap_200"| CHUNKS

  R1 -->|"index_chunks"| VS
  VS -->|"embed_chunks"| OAIE
  OAIE -->|"returns_vectors"| VECS
  VS -.->|"upsert_vectors+metadata"| CHROMA
  CHROMA -.->|"persist_to"| DISK

  R1 -->|"store_original"| S3SVC
  S3SVC -.->|"upload_file"| S3
  R1 -->|"success_response"| UI

  %% =========================
  %% Query / Q&A Flow (RAG)
  %% =========================
  UI -->|"question_JSON"| R2
  R2 -->|"embed_query"| VS
  VS -->|"embed_query"| OAIE
  VS -->|"similarity_search_k=4_cosine"| CHROMA
  CHROMA -->|"top_k_chunks+scores"| TOPK
  VS -->|"return_context"| LLM

  LLM -->|"read_update"| MEM
  LLM -->|"build_prompt"| PB
  TOPK -->|"augment_context"| PB
  PB -->|"prompt"| PROMPT
  LLM -->|"completion_inference"| OAIG
  OAIG -->|"answer"| LLM
  R2 -->|"answer_JSON"| UI

  %% =========================
  %% Architecture Callouts
  %% =========================
  NOTE1["Pattern: RAG = Retrieval (Chroma) → Augment (Prompt) → Generation (GPT-4)"]:::note
  NOTE2["Persistence Split: Vectors on Disk (ChromaDB) vs Originals in S3"]:::note
  NOTE3["Config: .env → config.py (models, chunking, k, paths, keys)"]:::note
  NOTE4["Perf Notes: Embedding per chunk; Similarity ~100-500ms; GPT-4 ~2-5s"]:::note

  CHROMA -->|"enables"| NOTE1
  S3 -->|"stores"| NOTE2
  CFG -->|"drives"| NOTE3
  OAIG -->|"latency"| NOTE4

  %% --- Repo meta relationships (non-runtime) ---
  REQ -->|"pins"| FLASK
  DOCS -->|"describes"| NOTE1
  SAMPLE -->|"example_input"| RAW

  %% Click Events (mapped components)
  click FLASK "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/main.py"
  click R0 "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/main.py"
  click R1 "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/main.py"
  click R2 "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/main.py"
  click APPINIT "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/__init__.py"
  click CFG "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/config.py"
  click VS "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/models/vector_store.py"
  click LLM "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/services/llm_service.py"
  click S3SVC "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/services/storage_service.py"
  click UIHTML "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/templates/index.html"
  click UICSS "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/static/style.css"
  click REQ "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/requirements.txt"
  click DOCS "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/README.md"
  click SAMPLE "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/data/RAG-White-Paper.pdf"
  click DP "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/main.py"
  click EX "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/main.py"
  click CH "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/main.py"
  click MEM "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/services/llm_service.py"
  click PB "https://github.com/vivekdeshmukhrepos/document-intelligence/blob/main/app/services/llm_service.py"

  %% Styles
  classDef client fill:#ECEFF4,stroke:#4C566A,stroke-width:1px,color:#2E3440;
  classDef ui fill:#E5E9F0,stroke:#5E81AC,stroke-width:1px,color:#2E3440;
  classDef app fill:#D7E9FF,stroke:#2B6CB0,stroke-width:1px,color:#102A43;
  classDef route fill:#BEE3F8,stroke:#2C5282,stroke-width:1px,color:#102A43;
  classDef external fill:#FFE3C2,stroke:#C05621,stroke-width:1px,color:#7B341E;
  classDef store fill:#C6F6D5,stroke:#2F855A,stroke-width:1px,color:#1C4532;
  classDef artifact fill:#F7FAFC,stroke:#718096,stroke-width:1px,color:#2D3748,stroke-dasharray:3 3;
  classDef state fill:#E9D8FD,stroke:#6B46C1,stroke-width:1px,color:#2D3748;
  classDef note fill:#FFF5F5,stroke:#C53030,stroke-width:1px,color:#742A2A;
  classDef meta fill:#EDF2F7,stroke:#A0AEC0,stroke-width:1px,color:#2D3748;
```
