# emilker/eduquizgen architecture

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

- Interactive diagram: https://gitdiagram.com/emilker/eduquizgen
- Repository: https://github.com/emilker/eduquizgen

## Overview

##### Project type and purpose
- This is a Python-based full-stack utility whose goal is to generate educational quizzes automatically from PDF documents.
- It exposes both a Streamlit web frontend (app.py) and a CLI entry point (main.py).
- Under the hood it uses PDF processing, a vector database for semantic retrieval, and a local LLM service (Ollama) for question generation, then exports the results as printable PDF.

##### File structure
- app.py – Streamlit web interface
- main.py – Command-line interface
- config.py – Global parameters (model name, chunk sizes, paths)
- document_processor.py – PDF parsing & text chunking
- vector_db.py – Vector store management (Chroma DB)
- quiz_generator.py – Chains together embeddings + LLM calls to produce questions
- requirements.txt – Python dependencies (LangChain, Ollama, PDF libs, ReportLab)

##### README insights
- Architecture isn’t explicitly diagrammed, but it describes four core subsystems: PDF ingestion, embedding & vector storage, LLM-based question generation, and PDF export.
- External dependencies: Ollama service running locally, vector DB folder, streamlit runtime.

a. Main components:
1. User Interface
- Streamlit UI (app.py)
- CLI (main.py)
2. Configuration Layer (config.py)
3. PDF Ingestion & Preprocessing (document_processor.py)
4. Semantic Storage & Retrieval (vector_db.py + Chroma)
5. Question Generation Engine (quiz_generator.py + LangChain + Ollama)
6. PDF Exporter (ReportLab)
7. External Services
- Ollama LLM Service
b. Relationships & interactions:
- UI → invokes either app.py or main.py → reads config → passes input PDF to document_processor
- document_processor → chunks text → returns text fragments
- quiz_generator orchestrates:
– sends fragments to vector_db to create/retrieve embeddings
– calls Ollama through LangChain-Ollama adapter for question prompts
- quiz_generator collates responses → hands off to PDF Exporter → writes final quiz PDF
c. Architectural patterns & design principles:
- Modular pipeline style: separate concerns (ingest, store, generate, export)
- Adapter pattern: LangChain abstracts LLM calls to Ollama
- Configuration-driven behavior for chunk sizing and model choice
d. Key technologies/frameworks:
- Python 3.10
- Streamlit for frontend
- unstructured, pikepdf, pdfminer for PDF parsing
- chromadb + sentence-transformers for vector storage
- LangChain (core, community, ollama) for orchestration
- Ollama LLM service (llama3.2:8b)
- ReportLab for PDF generation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User(("User")):::external

    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        app["Streamlit UI"]:::frontend
        cli["Command-Line Interface"]:::frontend
    end

    %% Configuration Layer
    config["Configuration Layer"]:::config

    %% Processing Pipeline
    subgraph "Backend Pipeline"
        direction TB
        processor["PDF Ingestion & Preprocessing"]:::backend
        storage["Semantic Storage & Retrieval"]:::backend
        generator["Question Generation Engine"]:::backend
        exporter["PDF Exporter"]:::backend
    end

    %% External Services
    ollama["Ollama LLM Service"]:::external

    %% Output
    output["Quiz PDF Output"]:::persistence

    %% Connections
    User -->|selects mode| app
    User -->|selects mode| cli

    app -->|reads config| config
    cli -->|reads config| config

    config --> processor
    processor -->|text_chunks| storage
    storage -->|embed_request| generator
    generator -->|LLM_prompt| ollama
    ollama -->|LLM_response| generator
    generator -->|questions| exporter
    exporter -->|final_quiz.pdf| output

    %% Click Events
    click app "https://github.com/emilker/eduquizgen/blob/main/app.py"
    click cli "https://github.com/emilker/eduquizgen/blob/main/main.py"
    click config "https://github.com/emilker/eduquizgen/blob/main/config.py"
    click processor "https://github.com/emilker/eduquizgen/blob/main/document_processor.py"
    click storage "https://github.com/emilker/eduquizgen/blob/main/vector_db.py"
    click generator "https://github.com/emilker/eduquizgen/blob/main/quiz_generator.py"
    click exporter "https://github.com/emilker/eduquizgen/blob/main/quiz_generator.py"

    %% Styles
    classDef frontend fill:#b2f2bb,stroke:#2f6627
    classDef backend fill:#bae7ff,stroke:#1d39c4
    classDef external fill:#ffd8a8,stroke:#c2410c
    classDef config fill:#f5f5f5,stroke:#666666
    classDef persistence fill:#f5f5f5,stroke:#666666
```
