# michniks2001/outline-generator architecture

> Architecture diagram of the GitHub repository michniks2001/outline-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michniks2001/outline-generator
- Repository: https://github.com/michniks2001/outline-generator

## Overview

1. **System shape**
   - This repo is a two-tier application: a **React/Vite frontend** and a **FastAPI backend**.
   - The frontend handles document upload, text extraction in the browser, and user interaction.
   - The backend owns persistence, OCR fallback, semantic search, and AI-driven outline generation.

2. **Frontend boundary**
   - `src/App.jsx` is the main orchestration layer for the UI.
   - `src/Chatbot.jsx` and `src/SourceModal.jsx` suggest the UI is centered on asking questions and inspecting retrieved source chunks.
   - `src/main.jsx` boots the app; styles are split across component-specific CSS files.

3. **Client-side document ingestion**
   - The README says PDFs are first processed **in the browser** using `pdfjs-dist`.
   - If extracted text is too small, the file is sent to the backend for OCR.
   - This creates an important architectural split: lightweight PDFs stay mostly client-side, while scanned/complex PDFs rely on server-side processing.

4. **Backend entry and API surface**
   - `backend/app.py` is the server entrypoint.
   - `backend/src/endpoints.py` likely defines the HTTP API consumed by the frontend.
   - The documented routes show the main backend capabilities:
     - `/store-text`
     - `/ocr-pdf`
     - `/search-chunks`
     - `/generate-outline`

5. **Core backend subsystems**
   - `backend/src/database.py` indicates a persistence layer, backed by **ChromaDB** per the README.
   - `backend/src/models.py` likely defines request/response schemas for the API.
   - `backend/src/utils.py` and `backend/src/outline.py` likely hold reusable text-processing and outline-generation logic.
   - `backend/src/chatbot.py` appears to encapsulate the question-answering / retrieval-augmented generation flow.

6. **Document processing pipeline**
   - Uploaded or OCR-extracted text is chunked before storage.
   - The README specifies **sentence-aware chunking** with ~200-character chunks and ~40-character overlap.
   - Large PDFs are processed in batches of 30 pages, which is an operational boundary for throughput and memory usage.

7. **Vector search and retrieval**
   - Chunks are stored in **ChromaDB** for semantic retrieval.
   - The search endpoint returns relevant chunks based on the user’s questions.
   - This retrieved context is then reused by the outline generation flow, making search the bridge between stored documents and AI output.

8. **AI generation path**
   - The backend integrates **Google Gemini** via environment variables in `backend/.env`.
   - `backend/src/outline.py` likely converts retrieved chunks plus user questions into a structured research-paper outline.
   - The model is not just generating freeform chat; it is producing a constrained, outline-shaped response from retrieved evidence.

9. **OCR fallback path**
   - When client-side PDF text extraction is insufficient, the backend uses **pdf2image + pytesseract**.
   - This requires an external **Tesseract OCR** installation, which is a deployment/runtime dependency.
   - Architecturally, OCR is a resilience path for scanned or image-based PDFs, not the default ingestion path.

10. **State and storage boundaries**
   - Persistent document memory lives in the backend’s ChromaDB store, not in the browser.
   - The README implies folder-based organization, so document metadata is likely stored alongside chunks to partition content by folder or collection.
   - The frontend does not appear to own long-term document state; it is a thin interaction layer over backend storage and retrieval.

11. **Operational concerns**
   - The backend runs on `localhost:8000`; the frontend on Vite’s dev server, typically `localhost:5173`.
   - CORS must allow the frontend origin to call the API.
   - The backend is configured through environment variables for Gemini key and model selection, making the AI provider an external dependency.

12. **How to diagram this repo**
   - A useful architecture diagram would show:
     - Browser UI
     - Client-side PDF extraction
     - OCR fallback to backend
     - FastAPI API layer
     - Chunking + embedding/storage in ChromaDB
     - Retrieval/search
     - Gemini-based outline generation
     - UI display of outline and source chunks
   - The key flow is: **PDF/question input → text extraction → chunk storage/search → Gemini outline generation → UI presentation**.

Main entry points: [`backend/src/endpoints.py`](https://github.com/michniks2001/outline-generator/blob/main/backend/src/endpoints.py) (HTTP routes), [`src/App.jsx`](https://github.com/michniks2001/outline-generator/blob/main/src/App.jsx) (Browser UI), [`backend/src/outline.py`](https://github.com/michniks2001/outline-generator/blob/main/backend/src/outline.py) (Outline builder), [`backend/src/utils.py`](https://github.com/michniks2001/outline-generator/blob/main/backend/src/utils.py) (Chunk text)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_ui["Browser UI<br/>react app<br/>[App.jsx]"]
  node_ui_boot(("App boot<br/>entry<br/>[main.jsx]"))
  node_chat_panel["Chat panel<br/>ui component<br/>[Chatbot.jsx]"]
  node_source_modal["Source modal<br/>ui component<br/>[SourceModal.jsx]"]
  node_client_pdf["PDF extract<br/>browser processing"]
end

subgraph group_backend["Backend"]
  node_fastapi_entry(("API server<br/>fastapi entry<br/>[app.py]"))
  node_api_routes["HTTP routes<br/>api layer<br/>[endpoints.py]"]
  node_schemas["Schemas<br/>pydantic models<br/>[models.py]"]
  node_store_text["Store text<br/>ingestion endpoint"]
  node_ocr_pdf["OCR fallback<br/>ocr pipeline"]
  node_chunking["Chunk text<br/>text pipeline<br/>[utils.py]"]
  node_vector_store[("ChromaDB<br/>vector database<br/>[database.py]")]
  node_search_chunks["Search chunks<br/>retrieval endpoint"]
  node_chatbot_core["QA engine<br/>rag orchestration<br/>[chatbot.py]"]
  node_outline_gen["Outline builder<br/>generation pipeline<br/>[outline.py]"]
  node_generate_outline["Generate outline<br/>generation endpoint"]
  node_gemini{{"Gemini API<br/>llm provider"}}
  node_runtime_env["Env config<br/>runtime config<br/>[.env.example]"]
  node_tesseract{{"Tesseract OCR<br/>system dependency"}}
end

node_ui_boot -->|"mounts"| node_browser_ui
node_browser_ui -->|"extracts"| node_client_pdf
node_browser_ui -->|"renders"| node_chat_panel
node_browser_ui -->|"opens"| node_source_modal
node_browser_ui -->|"calls"| node_api_routes
node_fastapi_entry -->|"serves"| node_api_routes
node_api_routes -->|"uses"| node_schemas
node_api_routes -->|"exposes"| node_store_text
node_api_routes -->|"exposes"| node_ocr_pdf
node_api_routes -->|"exposes"| node_search_chunks
node_api_routes -->|"exposes"| node_generate_outline
node_store_text -->|"routes to"| node_chunking
node_ocr_pdf -->|"depends on"| node_tesseract
node_ocr_pdf -->|"feeds"| node_chunking
node_chunking -->|"writes"| node_vector_store
node_search_chunks -->|"queries"| node_vector_store
node_search_chunks -->|"supplies context"| node_chatbot_core
node_chatbot_core -->|"invokes"| node_gemini
node_generate_outline -->|"delegates"| node_outline_gen
node_outline_gen -->|"retrieves evidence"| node_search_chunks
node_outline_gen -->|"invokes"| node_gemini
node_runtime_env -.->|"configures"| node_gemini
node_runtime_env -.->|"configures"| node_fastapi_entry

click node_browser_ui "https://github.com/michniks2001/outline-generator/blob/main/src/App.jsx"
click node_ui_boot "https://github.com/michniks2001/outline-generator/blob/main/src/main.jsx"
click node_chat_panel "https://github.com/michniks2001/outline-generator/blob/main/src/Chatbot.jsx"
click node_source_modal "https://github.com/michniks2001/outline-generator/blob/main/src/SourceModal.jsx"
click node_fastapi_entry "https://github.com/michniks2001/outline-generator/blob/main/backend/app.py"
click node_api_routes "https://github.com/michniks2001/outline-generator/blob/main/backend/src/endpoints.py"
click node_schemas "https://github.com/michniks2001/outline-generator/blob/main/backend/src/models.py"
click node_chunking "https://github.com/michniks2001/outline-generator/blob/main/backend/src/utils.py"
click node_vector_store "https://github.com/michniks2001/outline-generator/blob/main/backend/src/database.py"
click node_chatbot_core "https://github.com/michniks2001/outline-generator/blob/main/backend/src/chatbot.py"
click node_outline_gen "https://github.com/michniks2001/outline-generator/blob/main/backend/src/outline.py"
click node_runtime_env "https://github.com/michniks2001/outline-generator/blob/main/backend/.env.example"

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_browser_ui,node_ui_boot,node_chat_panel,node_source_modal,node_client_pdf toneBlue
class node_fastapi_entry,node_api_routes,node_schemas,node_store_text,node_ocr_pdf,node_chunking,node_vector_store,node_search_chunks,node_chatbot_core,node_outline_gen,node_generate_outline,node_gemini,node_runtime_env,node_tesseract toneAmber
```

## Components

### Frontend

React/Vite browser app for upload, question handling, and result display.

- [Browser UI](https://github.com/michniks2001/outline-generator/blob/main/src/App.jsx): react app · Main interactive client for uploading documents, asking questions, and viewing outputs. · `src/App.jsx`
- [App boot](https://github.com/michniks2001/outline-generator/blob/main/src/main.jsx): entry · Vite/React entry point that mounts the application. · `src/main.jsx`
- [Chat panel](https://github.com/michniks2001/outline-generator/blob/main/src/Chatbot.jsx): ui component · Conversation-style interface for asking questions over stored document content. · `src/Chatbot.jsx`
- [Source modal](https://github.com/michniks2001/outline-generator/blob/main/src/SourceModal.jsx): ui component · Popup for inspecting retrieved source chunks and evidence. · `src/SourceModal.jsx`
- **PDF extract**: browser processing · Client-side PDF text extraction before falling back to server OCR.

### Backend

FastAPI service for storage, OCR fallback, search, and outline generation.

- [API server](https://github.com/michniks2001/outline-generator/blob/main/backend/app.py): fastapi entry · Backend application entrypoint that starts the FastAPI service. · `backend/app.py`
- [HTTP routes](https://github.com/michniks2001/outline-generator/blob/main/backend/src/endpoints.py): api layer · Endpoint layer exposing text storage, OCR, search, and outline generation. · `backend/src/endpoints.py`
- [Schemas](https://github.com/michniks2001/outline-generator/blob/main/backend/src/models.py): pydantic models · Request and response models shared across API handlers. · `backend/src/models.py`
- **Store text**: ingestion endpoint · Receives extracted text for chunking and persistence.
- **OCR fallback**: ocr pipeline · Converts PDF pages to images and runs OCR on scanned or low-text files.
- [Chunk text](https://github.com/michniks2001/outline-generator/blob/main/backend/src/utils.py): text pipeline · Sentence-aware splitting with overlap to prepare retrieval units. · `backend/src/utils.py`
- [ChromaDB](https://github.com/michniks2001/outline-generator/blob/main/backend/src/database.py): vector database · Persistent semantic store for document chunks and metadata. · `backend/src/database.py`
- **Search chunks**: retrieval endpoint · Semantic lookup over stored chunks for a user question.
- [QA engine](https://github.com/michniks2001/outline-generator/blob/main/backend/src/chatbot.py): rag orchestration · Retrieval-augmented answering flow that assembles context for responses. · `backend/src/chatbot.py`
- [Outline builder](https://github.com/michniks2001/outline-generator/blob/main/backend/src/outline.py): generation pipeline · Produces a structured outline from retrieved evidence and model prompts. · `backend/src/outline.py`
- **Generate outline**: generation endpoint · API route that returns an AI-generated outline for the selected topic or document.
- **Gemini API**: llm provider · External model used for outline generation and AI-assisted responses.
- [Env config](https://github.com/michniks2001/outline-generator/blob/main/backend/.env.example): runtime config · Backend environment variables for API keys, model selection, and service settings. · `backend/.env.example`
- **Tesseract OCR**: system dependency · External OCR engine required for server-side document recognition.

## Connections

- App boot → Browser UI: mounts · Bootstraps the main application.
- Browser UI → PDF extract: extracts · Processes PDFs locally when text extraction is sufficient.
- Browser UI → Chat panel: renders · Primary interaction surface for questions and answers.
- Browser UI → Source modal: opens · Shows source evidence for retrieved chunks.
- Browser UI → HTTP routes: calls · Sends upload, search, and outline requests to the backend.
- API server → HTTP routes: serves · Starts the HTTP API layer.
- HTTP routes → Schemas: uses · Validates incoming and outgoing payloads.
- HTTP routes → Store text: exposes · Endpoint for persisting extracted text.
- HTTP routes → OCR fallback: exposes · Endpoint for OCR fallback on scanned PDFs.
- HTTP routes → Search chunks: exposes · Endpoint for semantic retrieval over stored chunks.
- HTTP routes → Generate outline: exposes · Endpoint for structured outline generation.
- Store text → Chunk text: routes to · Breaks uploaded text into retrieval-sized units.
- OCR fallback → Tesseract OCR: depends on · Uses OCR engine for image-based text extraction.
- OCR fallback → Chunk text: feeds · OCR output is normalized and chunked before storage.
- Chunk text → ChromaDB: writes · Persists chunks for later semantic search.
- Search chunks → ChromaDB: queries · Retrieves relevant chunks by similarity.
- Search chunks → QA engine: supplies context · Provides evidence chunks for question answering.
- QA engine → Gemini API: invokes · Uses the model to synthesize answers from retrieved context.
- Generate outline → Outline builder: delegates · Hands off outline construction to the generation pipeline.
- Outline builder → Search chunks: retrieves evidence · Pulls supporting chunks before generation.
- Outline builder → Gemini API: invokes · Uses the model to produce structured outline output.
- Env config → Gemini API: configures · Provides API keys and model selection.
- Env config → API server: configures · Supplies backend runtime settings.