# conleonidou/gemi-parser architecture

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

- Interactive diagram: https://gitdiagram.com/conleonidou/gemi-parser
- Repository: https://github.com/conleonidou/gemi-parser

## Overview

##### Project type and purpose
- This is a monolithic, single-page web app built in Python using Streamlit. Its sole purpose is to parse invoice documents and display results via a web interface.

##### File structure
- Top-level files:
- `.devcontainer/` – VS Code remote container config (development environment)
- `app.py` – Streamlit entry point (UI layer)
- `requirements.txt` – Python dependencies (Streamlit, parsing libraries, etc.)
- `README.md`, `LICENSE`, `.gitignore`
- `src/` directory organized into three packages:
- `models/invoice.py` – Defines the Invoice data model (fields, validation)
- `services/invoice_processor.py` – Core parsing logic, orchestrates data flow
- `utils/data_preparation.py` – Pre-processing helpers (text cleaning, normalization)

##### Extract additional insights from the README
- The app runs via `streamlit run app.py` and is deployed to Streamlit Cloud.
- It’s a beta tool, so accuracy warnings and issue reporting are called out.
- No external microservices or databases are mentioned—state is ephemeral.

a. Main components:
1. **User / Client Browser** – interacts via HTTP with the Streamlit UI
2. **Streamlit App (app.py)** – UI layer: handles user input, displays output
3. **Invoice Processor Service** – encapsulated in `src/services/invoice_processor.py`
4. **Data Preparation Utilities** – `src/utils/data_preparation.py`
5. **Invoice Model** – `src/models/invoice.py`
6. **Python Runtime & Dependencies** – environment managed by `requirements.txt` and `.devcontainer`
7. **Hosting Layer** – Streamlit Cloud (or local Docker dev‐container)
b. Relationships & data flow:
- The user uploads or drops an invoice file in the UI.
- The Streamlit app invokes the Invoice Processor.
- The processor first calls Data Preparation utilities to clean and normalize raw text.
- Prepared data is passed into the Invoice Model for field extraction & validation.
- Processed model output is returned to the UI for rendering.
- The UI displays structured invoice data (tables, charts, download links).
c. Architectural patterns & principles:
- Layered (UI → Service → Model/Util) separation of concerns
- Single codebase “monolith” – no separate microservices or persistent storage
- Dev container for environment consistency
d. Key technologies & libraries:
- Python 3.x, Streamlit (UI framework)
- Any PDF/text parsing libraries listed in `requirements.txt`
- VS Code Dev Containers (Docker) for local development

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Environment
    Browser["User / Client Browser"]:::external
    Cloud["Streamlit Cloud (Hosting)"]:::external
    DevContainer["Dev Container (Local Docker)"]:::external

    %% UI Layer
    UI["Streamlit App"]:::ui

    %% Core Service & Logic
    subgraph "Core Service & Logic"
        Processor["Invoice Processor Service"]:::service
        Utils["Data Preparation Utilities"]:::data
        Model["Invoice Model"]:::data
    end

    %% Infrastructure
    Env["Python Runtime & Dependencies"]:::infra

    %% Connections
    Browser -->|"HTTP Request"| UI
    UI -->|"invoke parser"| Processor
    Processor -->|"clean & normalize"| Utils
    Utils -->|"prepared data"| Model
    Model -->|"extracted & validated invoice"| Processor
    Processor -->|"response payload"| UI
    UI -->|"render output"| Browser
    Env --- UI
    Cloud --- UI
    DevContainer --- UI

    %% Click Events
    click UI "https://github.com/conleonidou/gemi-parser/blob/main/app.py"
    click Processor "https://github.com/conleonidou/gemi-parser/blob/main/src/services/invoice_processor.py"
    click Utils "https://github.com/conleonidou/gemi-parser/blob/main/src/utils/data_preparation.py"
    click Model "https://github.com/conleonidou/gemi-parser/blob/main/src/models/invoice.py"
    click Env "https://github.com/conleonidou/gemi-parser/blob/main/requirements.txt"
    click DevContainer "https://github.com/conleonidou/gemi-parser/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef ui fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef service fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef data fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef infra fill:#FFDAB9,stroke:#333,stroke-width:1px
```
