# uncharted0110/documint architecture

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

- Interactive diagram: https://gitdiagram.com/uncharted0110/documint
- Repository: https://github.com/uncharted0110/documint

## Overview

##### Project Type and Purpose
- This is a full-stack document-intelligence application (“DocumInt”) combining a FastAPI/Python backend with a React+Vite+Tailwind frontend.
- Purpose: Ingest and index PDF documents, extract outlines/headings, perform hybrid retrieval (BM25 + embeddings), provide AI-generated insights via Gemini/Azure TTS, and present results in an interactive PDF viewer, chat, mindmap and podcastify UI.

##### File Structure Analysis
- Top-level:
- Backend/ – FastAPI service (app.py, pdf_extractor.py, run_pipeline.py, requirements.txt) plus src modules:
– extract/ (heading_extractor, content_chunker)
– retrieval/ (hybrid_retriever)
– output/ (formatter, JSON output)
– utils/ (file_utils)
- DocumInt/ – React+Vite frontend (package.json, tailwind.config.ts, vite.config.ts) with src/contexts, hooks/, components/, pages/, utils/
- Dockerfile, .dockerignore, .gitignore, README.md
- Patterns:
- Monolithic backend with layered modules (extraction → retrieval → output)
- REST API endpoints exposed by FastAPI
- Frontend MVC-style React components + context/hook state management
- CI/DevOps: Dockerfile for containerization

##### README Insights
- Lists all key libraries and external services (Adobe PDF Embed, Google Gemini, Azure TTS)
- Details core algorithms, domain-specific weighting, caching layers, performance metrics
- Defines API endpoints for PDF upload, outline extraction, caching, hybrid retrieval, AI analysis, podcast generation, TTS streaming

##### Main Components
a. User Interface (Browser)
- PDF Viewer (Adobe Embed)
- Chat/Insights panel
- Mindmap, Podcastify UI
b. Frontend Application (React + Vite + Tailwind)
- Components, Contexts, Hooks
- API client (axios/fetch wrappers in src/config/api.ts)
c. Backend Service (FastAPI + Uvicorn)
- HTTP API layer (app.py)
- PDF Extraction Module (pdf_extractor.py → src/extract)
- Retrieval Module (hybrid_retriever in src/retrieval)
- Output Formatter (src/output/formatter)
- Pipeline Runner (run_pipeline.py for batch)
- Utility Layer (file I/O, caching)
d. Data Storage & Cache
- Local file store or in-memory cache for uploaded PDFs, embeddings, outputs
- JSON output store (src/output/output.json)
e. External Services
- Adobe PDF Embed SDK
- Google Gemini API (AI insights)
- Azure Speech Service (TTS)
- Sentence-Transformers Model downloads (on startup)

##### Relationships and Interactions
1. User interacts with React UI → selects or uploads PDF → React calls backend `/cache-pdfs`
2. Backend stores PDF → processes via extract module → builds index/embeddings via retrieval module
3. Frontend calls `/extract-outline` → backend returns outline JSON
4. User issues search/query → frontend POST `/query-pdfs` → backend hybrid_retriever returns ranked chunks
5. For AI insights: frontend POST `/analyze-chunks-with-gemini` → backend calls Gemini API → returns enhanced results
6. For podcastify: frontend POST `/podcastify-analysis` → backend runs script generation → calls Azure TTS via `/tts` → streams audio
7. Frontend renders viewer, mindmap, chat, podcast player

##### Architectural Patterns and Principles
- Layered Architecture: clear separation of API, business logic (extract/retrieval/output), and utilities
- Stateless REST API (scalable behind Uvicorn/Gunicorn)
- Single Page Application (SPA) on frontend with React contexts/hooks for state
- Caching layer for performance (embeddings, transcripts, mindmap)
- Extensibility points: new extractors, retrieval models, front-end components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Application"
        direction TB
        PDFViewer["PDF Viewer"]:::ui
        PDFOutlineSidebar["PDF Outline Sidebar"]:::ui
        ChatUI["Chat Panel"]:::ui
        InsightsUI["Insights Display"]:::ui
        MindmapUI["Mindmap UI"]:::ui
        FlippableCards["Podcast Cards"]:::ui
        ToolBar["Audio Controls"]:::ui
        APIClient["API Client"]:::api
    end

    %% Backend Layer
    subgraph "Backend Service"
        direction TB
        APILayer["FastAPI API Layer"]:::api
        ExtractionService["PDF Extraction Module"]:::api
        HeadingExtractor["Heading Extractor"]:::api
        ContentChunker["Content Chunker"]:::api
        RetrievalService["Hybrid Retriever Module"]:::api
        OutputFormatter["Output Formatter"]:::api
        JSONStore["JSON Output Store"]:::data
        PipelineRunner["Pipeline Runner"]:::api
        Utils["Utility Layer"]:::api
        Dependencies["Backend Requirements"]:::api
        Storage["Cache/Storage"]:::data
    end

    %% External Services
    AdobeEmbed["Adobe PDF Embed SDK"]:::ext
    GeminiAPI["Google Gemini API"]:::ext
    AzureTTS["Azure Speech Service"]:::ext
    SentenceTransformers["Sentence-Transformers Models"]:::ext

    %% Connections: Frontend to Backend
    PDFViewer -->|"renders/view PDF"| APIClient
    PDFOutlineSidebar -->|"fetch outline"| APIClient
    ChatUI -->|"query/chunks"| APIClient
    InsightsUI -->|"analyze with Gemini"| APIClient
    MindmapUI -->|"load mindmap data"| APIClient
    FlippableCards -->|"podcastify request"| APIClient
    ToolBar -->|"TTS stream"| APIClient

    APIClient -->|"HTTP POST JSON"| APILayer

    %% Backend internal flows
    APILayer -->|"extract PDF"| ExtractionService
    ExtractionService -->|"heading extraction"| HeadingExtractor
    ExtractionService -->|"chunk content"| ContentChunker
    ExtractionService -->|"store embeddings/chunks"| Storage

    APILayer -->|"query PDFs"| RetrievalService
    RetrievalService -->|"access store"| Storage
    RetrievalService -->|"return ranked chunks"| APILayer

    APILayer -->|"format output"| OutputFormatter
    OutputFormatter -->|"write JSON"| JSONStore

    APILayer -->|"batch run"| PipelineRunner
    PipelineRunner --> ExtractionService
    PipelineRunner --> RetrievalService

    APILayer -->|"utility calls"| Utils

    %% External integrations
    AdobeEmbed --> PDFViewer
    APILayer -->|"Gemini analysis"| GeminiAPI
    APILayer -->|"TTS request"| AzureTTS
    RetrievalService -->|"load model"| SentenceTransformers

    %% Click Events
    click PDFViewer "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/components/PDFViewer.tsx"
    click PDFOutlineSidebar "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/components/PDFOutlineSidebar.tsx"
    click ChatUI "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/components/Chat.tsx"
    click InsightsUI "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/components/Insights.tsx"
    click MindmapUI "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/components/Mindmap.tsx"
    click FlippableCards "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/components/FlippableCards.tsx"
    click ToolBar "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/components/ToolBar.tsx"
    click APIClient "https://github.com/uncharted0110/documint/blob/main/DocumInt/src/config/api.ts"
    click APILayer "https://github.com/uncharted0110/documint/blob/main/Backend/app.py"
    click ExtractionService "https://github.com/uncharted0110/documint/blob/main/Backend/pdf_extractor.py"
    click HeadingExtractor "https://github.com/uncharted0110/documint/blob/main/Backend/src/extract/heading_extractor.py"
    click ContentChunker "https://github.com/uncharted0110/documint/blob/main/Backend/src/extract/content_chunker.py"
    click RetrievalService "https://github.com/uncharted0110/documint/blob/main/Backend/src/retrieval/hybrid_retriever.py"
    click OutputFormatter "https://github.com/uncharted0110/documint/blob/main/Backend/src/output/formatter.py"
    click JSONStore "https://github.com/uncharted0110/documint/blob/main/Backend/src/output/output.json"
    click PipelineRunner "https://github.com/uncharted0110/documint/blob/main/Backend/src/run_pipeline.py"
    click Utils "https://github.com/uncharted0110/documint/blob/main/Backend/src/utils/file_utils.py"
    click Dependencies "https://github.com/uncharted0110/documint/blob/main/Backend/requirements.txt"

    %% Classes
    classDef ui fill:#daf1ff,stroke:#0366d6,color:#0366d6;
    classDef api fill:#f3e8ff,stroke:#8e44ad,color:#8e44ad;
    classDef data fill:#fff4e5,stroke:#d35400,color:#d35400;
    classDef ext fill:#e6ffed,stroke:#27ae60,color:#27ae60;
```
