How uncharted0110/documint works
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