# chrisvivasai/fraga architecture

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

- Interactive diagram: https://gitdiagram.com/chrisvivasai/fraga
- Repository: https://github.com/chrisvivasai/fraga

## Overview

##### Project type and purpose
- This is a full-stack, Streamlit-based web application (“OCR Fraga”) for reviewing Architectural & Engineering plan PDFs.
- It combines OCR (Tesseract), PDF parsing (PyMuPDF), image extraction, embedding generation, a Retrieval-Augmented Generation Q&A system, and persistence via Supabase (PostgreSQL + Storage).
- Users upload or load plan sets, the system extracts text/images, creates embeddings, stores data, and presents an interactive UI for text, image browsing, and AI-driven Q&A (optionally using local Ollama models or Google Gemini).

##### File structure
- Top-level:
- app.py – Streamlit entry point (UI control, tab layout).
- modules/ – Core logic subdivided by functionality:
– text_extractor.py (OCR, cleaning, embedding)
– image_handler.py (PDF image extraction, metadata, cloud storage)
– qa_analyzer.py (semantic search + LLM calls, context assembly)
– shared_resources.py (DB/Storage & model-loading utilities)
- requirements.txt & packages.txt – dependencies.
- README.md – documentation.
- Configuration: expects a .env file (Supabase URLs/keys, Tesseract path, optional Google API key, Ollama model name).
- No dedicated frontend vs. backend directories, but logically app.py is the “UI layer” and modules are the “service layer.”

##### Key insights from README
- Uses Streamlit’s multi-tab UI: Text/Project Info, Images, Q&A.
- Persistence via Supabase: projects, extracted text, embeddings, image metadata, raw PDFs.
- Two AI model options: local (Ollama/Gemma/LLaVA) or Google Gemini via API.
- OCR via Tesseract; PDF parsing via PyMuPDF; embeddings via sentence-transformers; semantic search; RAG pipeline.

##### Main components & their interactions
a. Frontend (Streamlit UI – app.py)
- File uploader & project selector
- Sidebar for AI model selection
- Three tabs: Text, Images, Q&A
– Displays results and takes user queries
b. Service layer (modules/)
- TextExtraction Service
- Reads PDF → Tesseract OCR → cleans/standardizes text → creates embeddings
- ImageExtraction Service
- Reads PDF → extracts images → stores in Supabase Storage → metadata in Supabase DB
- QA Service
- Accepts user query → retrieves relevant text embeddings + optional code DB → calls LLM (Ollama/Gemini) → returns answer
- SharedResources
- Manages Supabase DB & Storage connections
- Loads LLM clients (Ollama or Google API)
c. Database & Storage (Supabase)
- PostgreSQL: projects, document records, text chunks, embeddings, image metadata, QA logs
- Storage: raw PDFs, extracted images
d. External Services
- Tesseract OCR (local binary)
- Ollama (local LLM hosting) or Google Gemini API
- Supabase (cloud DB + Storage)

##### Architectural patterns & design principles
- MVC-like separation: UI (app.py) vs. business logic (modules/) vs. persistence (Supabase).
- Single-process monolith, but logically layered.
- RAG pattern: semantic search + LLM.
- Factory or provider pattern in shared_resources for model and DB clients.
- Streamlit event-driven UI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "User Interface" 
        direction TB
        Browser["Client Browser"]:::external
        Streamlit["Streamlit (Python, app.py)"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        SharedResources["Shared Resources\n(Supabase client, model loader)"]:::pipeline
        TextExtraction["TextExtraction Service\n(modules/text_extractor.py)"]:::pipeline
        TextUtils["Text Utilities\n(modules/text_utils.py)"]:::pipeline
        ImageExtraction["ImageExtraction Service\n(modules/image_handler.py)"]:::pipeline
        ImageUtils["Image Utilities\n(modules/image_utils.py)"]:::pipeline
        ImageDB["Image Metadata Persistence\n(modules/image_db.py)"]:::pipeline
        QAService["QA Service\n(modules/qa_analyzer.py)"]:::pipeline
        DocSummary["Document Summarization\n(modules/document_summary_utils.py)"]:::pipeline
    end

    %% Persistence Layer
    subgraph "Persistence (Supabase)" 
        direction TB
        SupabaseDB["PostgreSQL + pgvector"]:::persistence
        SupabaseStorage["Storage Bucket"]:::persistence
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        Tesseract["Tesseract OCR"]:::external
        PyMuPDF["PyMuPDF (fitz)"]:::external
        Embeddings["sentence-transformers\n(HuggingFace, torch)"]:::external
        ImgProcessing["Pillow & OpenCV"]:::external
        Ollama["Ollama Local LLM"]:::external
        GoogleGemini["Google Gemini API"]:::external
    end

    %% Documentation & Config
    subgraph "Docs & Config" 
        direction TB
        README["README.md"]:::external
        Reqs["requirements.txt"]:::external
        Packages["packages.txt"]:::external
    end

    %% Connections
    Browser -->|"HTTP/WebSocket"| Streamlit
    Streamlit -->|uses| SharedResources
    Streamlit -->|uploads PDF| TextExtraction
    TextExtraction -->|calls OCR| Tesseract
    TextExtraction -->|cleans text| TextUtils
    TextExtraction -->|embeddings| Embeddings
    TextExtraction -->|stores text & embeddings| SupabaseDB

    Streamlit -->|uploads PDF| ImageExtraction
    ImageExtraction -->|parses PDF| PyMuPDF
    ImageExtraction -->|process| ImageUtils
    ImageExtraction -->|stores images| SupabaseStorage
    ImageExtraction -->|metadata| ImageDB --> SupabaseDB

    Browser -->|QA query| Streamlit
    Streamlit -->|queries| QAService
    QAService -->|vector search| SupabaseDB
    QAService -->|context assembly| DocSummary
    QAService -->|calls LLM| Ollama
    QAService -->|calls API| GoogleGemini
    QAService -->|returns answer| Streamlit --> Browser

    %% Click Events
    click Streamlit "https://github.com/chrisvivasai/fraga/blob/main/app.py"
    click TextExtraction "https://github.com/chrisvivasai/fraga/blob/main/modules/text_extractor.py"
    click TextUtils "https://github.com/chrisvivasai/fraga/blob/main/modules/text_utils.py"
    click ImageExtraction "https://github.com/chrisvivasai/fraga/blob/main/modules/image_handler.py"
    click ImageUtils "https://github.com/chrisvivasai/fraga/blob/main/modules/image_utils.py"
    click ImageDB "https://github.com/chrisvivasai/fraga/blob/main/modules/image_db.py"
    click QAService "https://github.com/chrisvivasai/fraga/blob/main/modules/qa_analyzer.py"
    click DocSummary "https://github.com/chrisvivasai/fraga/blob/main/modules/document_summary_utils.py"
    click SharedResources "https://github.com/chrisvivasai/fraga/blob/main/modules/shared_resources.py"
    click README "https://github.com/chrisvivasai/fraga/blob/main/README.md"
    click Reqs "https://github.com/chrisvivasai/fraga/blob/main/requirements.txt"
    click Packages "https://github.com/chrisvivasai/fraga/blob/main/packages.txt"

    %% Styles
    classDef ui fill:#D6E5FF,stroke:#333,stroke-width:1px
    classDef pipeline fill:#D3F9D8,stroke:#333,stroke-width:1px
    classDef persistence fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
