# gianluca-gitea/pdf-extractext architecture

> Architecture diagram of the GitHub repository gianluca-gitea/pdf-extractext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gianluca-gitea/pdf-extractext
- Repository: https://github.com/gianluca-gitea/pdf-extractext

## Overview

PDF Extract Text is a desktop-assisted PDF processing system: users select PDFs in the GUI, which sends requests through the nginx gateway. Extract converts PDFs to plain text or Markdown (with optional OCR); Documents deduplicates uploads, persists extracted text and metadata in MongoDB, and provides history, status editing, soft deletion, and downloads. The upload orchestration and extraction engine are distinct internal layers. README documents the gateway and service split; source excerpts show the main service calls. The GUI implementation and nginx configuration were not excerpted, so those connections rely on README documentation.

Main entry points: [`services/documents/app/services/upload_service.py`](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/upload_service.py) (Upload orchestration), [`nginx/templates/default.conf.template`](https://github.com/gianluca-gitea/pdf-extractext/blob/main/nginx/templates/default.conf.template) (HTTP gateway), [`services/documents/app/main.py`](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/main.py) (Documents API), [`services/extract/app/main.py`](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/extract/app/main.py) (Extract API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway and UI"]
  node_gui["Desktop GUI<br/>[interface.py]"]
  node_nginx["HTTP gateway"]
end

subgraph group_documents["Document management"]
  node_documents_api["Documents API<br/>[main.py]"]
  node_upload["Upload orchestration<br/>[upload_service.py]"]
  node_checksum["SHA-256 checksum"]
  node_builder["Document builder"]
  node_document_service["History and status"]
  node_extract_client["Extraction HTTP client<br/>[extract_client.py]"]
end

subgraph group_extraction["PDF extraction"]
  node_extract_api["Extract API<br/>[main.py]"]
  node_pdf_engine["PDF text and Markdown<br/>[pdf_service.py]"]
  node_ocr["OCR engine"]
end

subgraph group_persistence["Document persistence"]
  node_repository["Document repository"]
  node_mongodb[("MongoDB")]
end

node_user(("User"))

node_user -->|"selects PDFs"| node_gui
node_gui -->|"calls APIs"| node_nginx
node_nginx -->|"routes extract"| node_extract_api
node_nginx -->|"routes documents"| node_documents_api
node_documents_api -->|"processes uploads"| node_upload
node_documents_api -->|"handles document operations"| node_document_service
node_upload -->|"calculates checksum"| node_checksum
node_upload -->|"checks and saves"| node_repository
node_upload -->|"requests extraction"| node_extract_client
node_upload -->|"builds metadata"| node_builder
node_extract_client -->|"posts PDF text"| node_extract_api
node_extract_api -->|"dispatches extraction"| node_pdf_engine
node_pdf_engine -.->|"optionally recognizes images"| node_ocr
node_document_service -->|"reads and updates"| node_repository
node_repository -->|"queries and writes"| node_mongodb

click node_gui "https://github.com/gianluca-gitea/pdf-extractext/blob/main/gui/interface.py"
click node_nginx "https://github.com/gianluca-gitea/pdf-extractext/blob/main/nginx/templates/default.conf.template"
click node_documents_api "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/main.py"
click node_upload "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/upload_service.py"
click node_checksum "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/checksum_service.py"
click node_builder "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/document_builder.py"
click node_document_service "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/document_service.py"
click node_extract_client "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/extract_client.py"
click node_extract_api "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/extract/app/main.py"
click node_pdf_engine "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/extract/app/pdf_service.py"
click node_repository "https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/repositories/document_repository.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gui,node_nginx,node_user toneBlue
class node_documents_api,node_upload,node_checksum,node_builder,node_document_service,node_extract_client toneAmber
class node_extract_api,node_pdf_engine,node_ocr toneMint
class node_repository,node_mongodb toneRose
```

## Components

### Gateway and UI

- [Desktop GUI](https://github.com/gianluca-gitea/pdf-extractext/blob/main/gui/interface.py): `gui/interface.py`
- [HTTP gateway](https://github.com/gianluca-gitea/pdf-extractext/blob/main/nginx/templates/default.conf.template): `nginx/templates/default.conf.template`

### Document management

- [Documents API](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/main.py): `services/documents/app/main.py`
- [Upload orchestration](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/upload_service.py): `services/documents/app/services/upload_service.py`
- [SHA-256 checksum](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/checksum_service.py): `services/documents/app/services/checksum_service.py`
- [Document builder](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/document_builder.py): `services/documents/app/services/document_builder.py`
- [History and status](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/document_service.py): `services/documents/app/services/document_service.py`
- [Extraction HTTP client](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/services/extract_client.py): `services/documents/app/services/extract_client.py`

### PDF extraction

- [Extract API](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/extract/app/main.py): `services/extract/app/main.py`
- [PDF text and Markdown](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/extract/app/pdf_service.py): `services/extract/app/pdf_service.py`
- **OCR engine**

### Document persistence

- [Document repository](https://github.com/gianluca-gitea/pdf-extractext/blob/main/services/documents/app/repositories/document_repository.py): `services/documents/app/repositories/document_repository.py`
- **MongoDB**

### Other components

- **User**

## Connections

- User → Desktop GUI: selects PDFs (evidence: `README.md`)
- Desktop GUI → HTTP gateway: calls APIs (evidence: `README.md`)
- HTTP gateway → Extract API: routes extract (evidence: `README.md`)
- HTTP gateway → Documents API: routes documents (evidence: `README.md`)
- Documents API → Upload orchestration: processes uploads (evidence: `services/documents/app/main.py`)
- Documents API → History and status: handles document operations (evidence: `services/documents/app/main.py`)
- Upload orchestration → SHA-256 checksum: calculates checksum (evidence: `services/documents/app/services/upload_service.py`)
- Upload orchestration → Document repository: checks and saves (evidence: `services/documents/app/services/upload_service.py`)
- Upload orchestration → Extraction HTTP client: requests extraction (evidence: `services/documents/app/services/upload_service.py`)
- Upload orchestration → Document builder: builds metadata (evidence: `services/documents/app/services/upload_service.py`)
- Extraction HTTP client → Extract API: posts PDF text (evidence: `services/documents/app/services/extract_client.py`)
- Extract API → PDF text and Markdown: dispatches extraction (evidence: `services/extract/app/main.py`)
- PDF text and Markdown → OCR engine: optionally recognizes images (evidence: `README.md`)
- History and status → Document repository: reads and updates (evidence: `services/documents/app/services/document_service.py`)
- Document repository → MongoDB: queries and writes (evidence: `services/documents/app/repositories/document_repository.py`)
