# eshaanpra/document2flashcards architecture

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

- Interactive diagram: https://gitdiagram.com/eshaanpra/document2flashcards
- Repository: https://github.com/eshaanpra/document2flashcards

## Overview

##### Project Type and Purpose
- This is a monolithic, full-stack Streamlit application (“Document2Flashcards”) that allows users to upload documents (PDFs, images, text), runs OCR and AI to generate flashcards, persists them in a SQLite database, and presents an interactive flashcard UI.

##### File-Structure Analysis
- Top-level files only:
- FullProgram.py – the single entry point combining UI (Streamlit), business logic, data access, and external-service calls
- config.yaml – holds app‐wide settings (e.g. auth, model paths)
- requirements.txt – Python dependencies (Streamlit, pytesseract, llama-cpp-python, PyPDF2, etc.)
- .gitignore
- No separate “frontend” or “backend” folders; the code is a monolithic service, but internally it can be logically split into layers.

##### README Insights
- Describes OCR (Tesseract), PDF extraction (PyPDF2), AI model (Llama), SQLite DB, user auth, UI with CSS animation, session state.
- Indicates a chunk-based pipeline for processing large documents.

##### Core Components
a. Streamlit Frontend Layer (UI)
- File-upload widget
- Login/Signup flows (streamlit-authenticator)
- Interactive flashcard display (HTML/CSS flip animation)
- Sidebar for deck selection
b. Document Processing Layer
- PDF extractor (PyPDF2)
- Image OCR (pytesseract + PIL)
- Plain-text loader
c. Text Chunking & Preprocessing
- Splits large text into manageable chunks (< n_ctx)
- Normalization, tokenization
d. AI Flashcard Generator
- llama-cpp-python interface to Llama model
- Prompt construction, inference, JSON flashcard output
e. Data Access Layer
- SQLite database
- Tables: Users, Decks, Flashcards
- CRUD operations (save/retrieve decks and cards)
f. External Services & Resources
- Tesseract OCR binary (TESSERACT_PATH)
- Llama model file (MODEL_PATH)
g. Configuration & Environment
- config.yaml / environment variables for secrets and paths

##### Relationships & Interactions
- External services are called by Document Processing (Tesseract) and AI Generator (Llama).

##### Architectural Patterns & Principles
- Monolithic layered architecture: UI, business logic (document-OCR-AI pipeline), data access, external adapters
- Single responsibility per logical module
- Caching of LL model and Streamlit session state for performance
- Use of environment variables for configuration (12-factor)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Artifacts
    subgraph "Configuration & Artifacts"
        direction TB
        CFG["config.yaml"]:::config
        REQ["requirements.txt"]:::artifact
        RMD["README.md"]:::artifact
        GIT[".gitignore"]:::artifact
    end

    %% External Services & Resources
    subgraph "External Services" 
        direction TB
        TESS["Tesseract OCR Binary"]:::external
        LLAMAMODEL["Llama Model File"]:::external
    end

    %% Monolith Container
    subgraph "Monolith (FullProgram.py)"
        direction TB
        %% UI Layer
        subgraph "Streamlit Frontend Layer" 
            direction TB
            UI["UI: File Upload, Login/Signup, Flashcard Display\n(HTML/CSS Animation)"]:::frontend
        end

        %% Business Logic Layer
        subgraph "Document Processing & Chunking Pipeline"
            direction TB
            DP["PDF Extractor (PyPDF2)\nImage OCR (pytesseract+PIL)\nText Loader"]:::biz
            CHUNK["Text Chunking & Preprocessing\n(normalization, tokenization)"]:::biz
        end

        %% AI Generator
        AG["AI Flashcard Generator\n(llama-cpp-python)"]:::biz

        %% Data Access Layer
        subgraph "Data Access Layer"
            direction TB
            DAL["SQLite CRUD\n(Users, Decks, Flashcards)"]:::biz
            DB["SQLite Database"]:::db
        end
    end

    %% Data Flow
    UI -->|"upload_document() "| DP
    DP -->|"chunk_text() (batched)"| CHUNK
    CHUNK -->|"infer_flashcards() "| AG
    AG -->|"save_deck() / save_flashcards() "| DAL
    UI -->|"view_decks()/view_cards() "| DAL
    DAL -->|"SQL Queries"| DB

    %% External Calls
    DP -->|"calls OCR()"| TESS
    AG -->|"loads model from"| LLAMAMODEL
    CFG --> UI
    CFG --> DP
    CFG --> AG
    CFG --> DAL

    %% Click Events
    click UI "https://github.com/eshaanpra/document2flashcards/blob/main/FullProgram.py"
    click DP "https://github.com/eshaanpra/document2flashcards/blob/main/FullProgram.py"
    click CHUNK "https://github.com/eshaanpra/document2flashcards/blob/main/FullProgram.py"
    click AG "https://github.com/eshaanpra/document2flashcards/blob/main/FullProgram.py"
    click DAL "https://github.com/eshaanpra/document2flashcards/blob/main/FullProgram.py"
    click CFG "https://github.com/eshaanpra/document2flashcards/blob/main/config.yaml"
    click REQ "https://github.com/eshaanpra/document2flashcards/blob/main/requirements.txt"
    click RMD "https://github.com/eshaanpra/document2flashcards/blob/main/README.md"
    click GIT "https://github.com/eshaanpra/document2flashcards/blob/main/text.gitignore"

    %% Legend
    subgraph "Legend"
        direction TB
        L1["UI Components"]:::frontend
        L2["Business Logic"]:::biz
        L3["External Services & Resources"]:::external
        L4["Persistent Storage"]:::db
        L5["Config & Artifacts"]:::config
        L6["Other Artifacts"]:::artifact
    end

    classDef frontend fill:#cce5ff,stroke:#0066cc,color:#003366;
    classDef biz fill:#d4edda,stroke:#28a745,color:#155724;
    classDef external fill:#fff3cd,stroke:#ffc107,color:#856404;
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#343a40,shape:cylinder;
    classDef config fill:#f5c6cb,stroke:#d9534f,color:#721c24;
    classDef artifact fill:#f8f9fa,stroke:#6c757d,color:#495057;
```
