How kevinjose-ma/ai-document-classification-summarization works
This repository is a two-tier AI document platform with a React frontend and a FastAPI backend, plus local file-based artifacts for uploads and vector indexes.
At a high level, the architecture is:
User browser → React/Vite frontend → FastAPI API layer → ingestion/retrieval/LLM services → MongoDB + local file storage + FAISS indexes
Main subsystems:
1. Frontend application
• Located under frontend/.
• Built with React, Vite, and Tailwind CSS.
• src/main.jsx and src/App.jsx provide the application entry and route composition.
• src/context/AuthContext.jsx indicates client-side auth state management, likely storing login/session state and protecting routes.
• src/api/axios.js is the HTTP client boundary to the backend API.
• The UI is organized into route-based pages:
- authentication and onboarding: Login.jsx, Register.jsx, Onboarding.jsx
- document workflow: Dashboard.jsx, DocumentPage.jsx, DocumentViewer.jsx, UploadPage.jsx, IngestionPage.jsx
- admin/operational views: Analytics.jsx, UsersPage.jsx, Settings.jsx, Emailsettings.jsx
• Reusable UI components in src/components/ implement the app shell and document-centric interactions: sidebar, topbar, table/cards, filters, upload form, confirmation dialogs, status badges, skeleton loaders, and toast notifications.
Architecturally, the frontend is a presentation and interaction layer only. It does not appear to own business logic; instead it drives backend APIs and renders document, ingestion, and account state.
2. Backend API layer
• Located under backend/app/api/.
• FastAPI is the backend runtime, with backend/app/main.py as the application entry point.
• The API is split into domain routers:
- auth.py for login/register/authentication flow
- documents.py for document CRUD, querying, and viewing
- ingestion_sources.py for managing where documents come from
• This layer is the boundary between the frontend and the system’s internal processing pipeline. It likely validates requests, enforces auth, and dispatches work to services.
3. Core configuration and runtime concerns
• backend/app/core/config.py centralizes environment/configuration values.
• backend/app/core/logger.py indicates structured logging setup.
• The presence of backend/logs/ shows runtime logs are persisted separately from app code.
• Deployment files such as Dockerfile, railway.toml, and nixpacks.toml show the app is designed for containerized/cloud deployment.
4. Document processing and AI service layer
This is the main backend value proposition and is split into several cooperating services under backend/app/services/:
• ingestion.py orchestrates the end-to-end ingest pipeline.
• extractor.py handles getting raw text/content from uploaded files.
• parser.py likely normalizes text and splits it into smaller semantic units/clauses.
• storage.py abstracts persistence of files and derived artifacts.
• retriever.py performs semantic lookup against FAISS indexes.
• llm.py wraps calls to the LLM provider.
• prompts.py centralizes prompt templates and structured prompt construction.
• summarizer.py generates summaries or condensed outputs from extracted content.
The README identifies Google Gemini as the LLM provider and FAISS as the vector retrieval layer. That means the AI flow is not “LLM only”; it is retrieval-augmented:
• the document is first processed and indexed
• user questions are then answered by combining semantic retrieval from FAISS with a generated LLM response
5. Data/model layer
• Located under backend/app/models/.
• ingestion_source.py suggests a model for configured document sources or source metadata.
• models.py likely contains the main document/user/schema definitions.
• The README also mentions document versioning and duplicate detection, so the persistence model likely stores metadata such as file hash, version, classification, and ownership/user scope.
6. Utility and maintenance layer
• backend/app/utils/utils.py contains shared helpers, likely including SHA256 hashing and text/file utility functions.
• Top-level maintenance scripts indicate operational support:
- clean_qa_cache.py clears cached Q&A artifacts
- rebuild_all_faiss_indices.py regenerates vector indexes from stored documents
• These scripts imply that some derived data is reproducible and can be rebuilt independently of the primary database.
Primary data flows:
A. Authentication flow
• The user signs in or registers through the frontend.
• The frontend sends credentials to api/auth.py.
• The backend authenticates and returns a session/token.
• The frontend stores auth state in AuthContext and attaches it via the Axios client.
B. Document upload and ingestion flow
• A user uploads a file from the frontend upload workflow.
• The backend receives it through the documents/ingestion APIs.
• The file is stored under backend/uploads/.
• The ingestion pipeline computes a file hash for duplicate detection.
• The document text is extracted, parsed into clauses/chunks, and classified.
• Chunks are indexed into FAISS for semantic retrieval.
• Metadata is stored in MongoDB.
• Temporary intermediate files are kept under backend/uploads/__temp__/.
• The categorized folders under backend/uploads/ (Engineering, Finance, General, Hr, Legal) show the system is already organized around document domains or tenants.
C. Question answering / retrieval flow
• The user asks a question in the UI.
• The request goes through the document API to the retriever and LLM services.
• The retriever searches FAISS for relevant clauses.
• The LLM service uses prompts from prompts.py to generate an answer grounded in retrieved content.
• The result is returned to the frontend, which displays it in document or viewer pages.
D. Document browsing and administration flow
• The frontend dashboard and document pages read metadata from the backend.
• Filters, tables, and document cards are purely presentation layers over backend data.
• Admin-like screens such as users, analytics, settings, and ingestion sources suggest the backend exposes operational metadata, not just raw document access.
Important architectural boundaries:
• Browser/UI boundary: React pages and components only talk to the backend through the Axios client.
• API boundary: FastAPI routers separate authentication, document operations, and ingestion-source management.
• Processing boundary: ingestion/extraction/parsing/retrieval/LLM concerns are isolated into services instead of being embedded in route handlers.
• Storage boundary: raw files live on disk, metadata lives in MongoDB, and semantic indexes live in FAISS artifacts on disk.
• External AI boundary: Gemini is an external dependency for classification and Q&A generation.
• Maintenance boundary: cache cleanup and index rebuilds are separate scripts, showing the system can recover derived artifacts without rebuilding the entire application.
In short, this repo is an AI document intelligence platform where the frontend handles document-centric UX, the backend coordinates authentication and APIs, and the service layer turns uploaded files into searchable, classifiable, LLM-grounded knowledge using MongoDB for metadata and FAISS for vector retrieval.
Main entry points: main.py API app · ingestion.py Ingestion pipeline · documents.py Documents API · App.jsx App routes
Components 29
Frontend
React/Vite UI and client-side state
- App entry · Bootstraps the React app and route composition
frontend/src/main.jsx - App routes · Top-level app composition and navigation
frontend/src/App.jsx - Auth state · Holds browser-side session and route protection state
frontend/src/context/AuthContext.jsx - API client · Shared frontend HTTP client for backend calls
frontend/src/api/axios.js - Pages · Login, dashboard, upload, document, analytics, and settings screens
- UI components · Sidebar, tables, cards, forms, dialogs, toasts, and status indicators
frontend/src/components/Layout.jsx
API Layer
FastAPI entrypoint and routers
- API app · Backend application bootstrap and router wiring
backend/app/main.py - Auth API · Login and registration endpoints
backend/app/api/auth.py - Documents API · Document CRUD, browsing, and question-answering endpoints
backend/app/api/documents.py - Sources API · Ingestion-source management endpoints
backend/app/api/ingestion_sources.py
Services
Document ingestion, retrieval, and LLM orchestration
- Ingestion pipeline · Coordinates upload processing, parsing, storage, and indexing
backend/app/services/ingestion.py - Extractor · Pulls raw text and content from uploaded files
backend/app/services/extractor.py - Parser · Normalizes and chunks extracted content for downstream use
backend/app/services/parser.py - Retriever · Searches FAISS indexes for semantically relevant passages
backend/app/services/retriever.py - LLM service · Wraps external model calls for answers and summaries
backend/app/services/llm.py - Prompts · Centralized prompt construction for generation tasks
backend/app/services/prompts.py - Storage · Abstracts local file and derived artifact persistence
backend/app/services/storage.py - Summarizer · Produces condensed document outputs
backend/app/services/summarizer.py
Core
Configuration, logging, and shared utilities
Models
Domain schemas and persistence models
- Domain models · Main document and user data models
backend/app/models/models.py - Source model · Ingestion source metadata model
backend/app/models/ingestion_source.py
Runtime Storage
Local artifacts and external backing stores
- Uploads · Raw documents and temporary artifacts on disk
backend/uploads - MongoDB · Persistent metadata and application records
- FAISS indexes · On-disk semantic indexes for retrieval
Ops
Maintenance scripts and deployment
- Maintenance · Cache cleanup and FAISS rebuild utilities
backend/rebuild_all_faiss_indices.py - Deployment · Container and platform deployment definitions
Dockerfile
External
Outside services and dependencies
- Gemini · External model provider for generation and classification
Other components
- Browser · User-facing entry point for the document workflow
Connections 33
- Browser → App entry: opens · User loads the web application
- App entry → App routes: boots · App entry composes the route tree
- App routes → Auth state: uses · Routes and UI depend on auth state
- App routes → API client: calls · Frontend uses the shared API client
- App routes → Pages: renders · Pages provide the main user workflows
- Pages → UI components: composes · Pages are built from shared widgets
- API client → API app: requests · All backend communication goes through the API boundary
- API app → Auth API: routes to · FastAPI mounts authentication endpoints
- API app → Documents API: routes to · FastAPI mounts document endpoints
- API app → Sources API: routes to · FastAPI mounts ingestion-source endpoints
- Auth API → Domain models: validates · Authentication uses domain schemas and user records
- Documents API → Ingestion pipeline: orchestrates · Document operations drive ingestion and retrieval workflows
- Documents API → Retriever: queries · Q&A requests search indexed content
- Documents API → Summarizer: summarizes · Document views can request condensed outputs
- Sources API → Source model: manages · Ingestion sources are persisted as source records
- Ingestion pipeline → Extractor: extracts · Pipeline begins by extracting raw content
- Ingestion pipeline → Parser: parses · Pipeline normalizes and chunks extracted text
- Ingestion pipeline → Storage: stores · Pipeline persists files and derived artifacts
- Ingestion pipeline → Retriever: indexes · Chunks are prepared for semantic retrieval
- Ingestion pipeline → Domain models: writes metadata · Document metadata and versioning state are persisted
- Extractor → Uploads: reads · Extraction reads uploaded files from disk
- Storage → Uploads: writes · Raw uploads and temporary artifacts are stored locally
- Retriever → FAISS indexes: searches · Semantic lookup runs against FAISS artifacts
- Retriever → MongoDB: loads metadata · Retrieval is paired with persisted document metadata
- LLM service → Gemini: invokes · Generation and classification use the external model provider
- LLM service → Prompts: formats · LLM calls are built from shared prompt templates
- Summarizer → LLM service: uses · Summaries are generated through the LLM wrapper
- API app → Config: configures · Application startup is driven by shared settings
- API app → Logger: logs · Backend startup and requests use centralized logging
- Documents API → MongoDB: reads/writes · Document metadata is persisted in the database
- Maintenance → FAISS indexes: rebuilds · Operational scripts regenerate vector indexes
- Maintenance → Uploads: scans · Rebuild and cleanup operate over stored artifacts
- Deployment → API app: deploys · Container and platform config package the backend application