# mulinco/extrator-pdf-streamlit architecture

> Architecture diagram of the GitHub repository mulinco/extrator-pdf-streamlit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mulinco/extrator-pdf-streamlit
- Repository: https://github.com/mulinco/extrator-pdf-streamlit

## Overview

##### Project type and purpose
- This is a monolithic, Python‐based Streamlit application whose goal is to let end users upload PDF “Declarações de Importação,” extract structured fields (D.I., Invoice, PO, HAWB, etc.) via regex and PyMuPDF, display results in the browser, and export a consolidated Excel report using Pandas and XlsxWriter.

##### File structure
- Top‐level files:
- app.py – the Streamlit entrypoint
- anonimizar_pdfs.py – a standalone PDF‐anonymization utility (auxiliary script)
- requirements.txt – dependencies (Streamlit, PyMuPDF, Pandas, XlsxWriter…)
- pages/ directory: multipage Streamlit modules (e.g. 2_Fechamento_Aeronave.py)
- pdfs_para_github/: sample PDFs for testing/demonstration
- .devcontainer/: dev environment configuration

##### README for insights
- The README describes a two‐tier flow:
- Frontend: browser ↔ Streamlit UI (upload button, table view, download button)
- Backend: app.py → PyMuPDF for page iteration → regex extraction → Pandas DataFrame → XlsxWriter to .xlsx

1. User’s Web Browser (Client)
2. Streamlit Server (app.py + pages/)
3. PDF Processing Module (PyMuPDF wrapper)
4. Data Extraction Module (Regex functions)
5. Data Layer (Pandas DataFrame)
6. Export Module (XlsxWriter)
7. Optional Utility Script (anonimizar_pdfs.py)
- Browser → (HTTP/WebSocket) → Streamlit Server (file upload trigger)
- Server → PDF Processing → loops per page → raw text
- Raw text → Data Extraction → structured records
- Structured records → Pandas DataFrame → in‐memory table
- DataFrame → Export Module → .xlsx file
- Export Module → Browser download response
- Auxiliary: anonimizar_pdfs.py reads/writes PDFs on disk
c. Architectural patterns & principles:
– MVC‐style separation:
- View = Streamlit UI components
- Controller = app.py’s control flow & page scripts
- Model = DataFrame + extraction functions
– Single process, event‐driven (Streamlit’s re‐run on interaction)
– Modular code: PDF I/O, regex extraction, data transformation, export
d. Key frameworks & libraries:
– Streamlit for UI & app server
– PyMuPDF (fitz) for PDF reading
– Python’s re module for regex matching
– Pandas for data management
– XlsxWriter as Excel engine

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        Browser["User's Web Browser"]:::frontend
        StreamlitUI["Streamlit UI"]:::frontend
    end

    subgraph "Backend"
        StreamlitServer["Streamlit Server\n(app.py)"]:::backend
        subgraph "Extraction Pipeline"
            PDFProcessor["PDF Processor\n(PyMuPDF)"]:::processing
            DataExtractor["Data Extraction\n(Regex)"]:::processing
            DataModel["Data Layer\n(Pandas DataFrame)"]:::data
        end
        Exporter["Export Module\n(XlsxWriter)"]:::data
    end

    anom["PDF Anonymization Utility\n(anonimizar_pdfs.py)"]:::utility
    pdfs["Sample PDFs\n(pdfs_para_github/)"]:::resource
    devc["Dev Container\n(.devcontainer/devcontainer.json)"]:::config
    req["Dependencies\n(requirements.txt)"]:::config
    readme["Documentation\n(README.md)"]:::config

    Browser -->|"Upload PDF"| StreamlitUI
    StreamlitUI -->|"Trigger upload"| StreamlitServer
    StreamlitServer --> PDFProcessor
    PDFProcessor -->|"Raw text per page"| DataExtractor
    DataExtractor -->|"Structured records"| DataModel
    DataModel --> Exporter
    Exporter -->|"Download .xlsx"| Browser

    anom -.->|"Reads/Writes"| pdfs
    devc -.-> StreamlitServer
    req -.-> StreamlitServer
    readme -.-> StreamlitServer

    click StreamlitServer "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/app.py"
    click StreamlitUI "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/pages/2_Fechamento_Aeronave.py"
    click PDFProcessor "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/app.py"
    click DataExtractor "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/app.py"
    click DataModel "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/app.py"
    click Exporter "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/app.py"
    click anom "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/anonimizar_pdfs.py"
    click pdfs "https://github.com/mulinco/extrator-pdf-streamlit/tree/main/pdfs_para_github/"
    click devc "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/.devcontainer/devcontainer.json"
    click req "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/requirements.txt"
    click readme "https://github.com/mulinco/extrator-pdf-streamlit/blob/main/README.md"

    classDef frontend fill:#D6E9FE,stroke:#4A90E2,color:#000
    classDef backend fill:#E8F4FD,stroke:#3A7BD5,color:#000
    classDef processing fill:#DFF0D8,stroke:#3C763D,color:#000
    classDef data fill:#FCF8E3,stroke:#8A6D3B,color:#000
    classDef utility fill:#F2DEDE,stroke:#A94442,color:#000
    classDef config fill:#E2D6FF,stroke:#7A42F5,color:#000
    classDef resource fill:#F5F5F5,stroke:#AAA,color:#000
```
