# icereed/paperless-gpt architecture

> Architecture diagram of the GitHub repository icereed/paperless-gpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icereed/paperless-gpt
- Repository: https://github.com/icereed/paperless-gpt

## Overview

paperless-gpt augments paperless-ngx with AI-assisted document organization and OCR. The main workflow is selecting documents in the web UI, generating title/tag/correspondent/date/custom-field suggestions, reviewing them, and applying accepted changes back to paperless-ngx. A separate OCR workflow submits document or page work to configured OCR providers and supports searchable-PDF processing. The map retains documented ad-hoc analysis, prompt/settings, history, and job capabilities. Sampled excerpts establish key API, suggestion, provider, and review links; unsampled subsystem wiring is shown only where supported by the README or route registrations.

Main entry points: [`main.go`](https://github.com/icereed/paperless-gpt/blob/main/main.go) (HTTP server and routes), [`web-app/src/App.tsx`](https://github.com/icereed/paperless-gpt/blob/main/web-app/src/App.tsx) (Web app routes), [`app_http_handlers.go`](https://github.com/icereed/paperless-gpt/blob/main/app_http_handlers.go) (API handlers), [`ocr.go`](https://github.com/icereed/paperless-gpt/blob/main/ocr.go) (OCR processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_webapp["Web app routes<br/>[App.tsx]"]
  node_processor["Document workflow"]
  node_review["Suggestion review"]
  node_ocrui["OCR interface<br/>[OCR.tsx]"]
  node_analysisui["Ad-hoc analysis<br/>[AdhocAnalysis.tsx]"]
  node_settingsui["Settings and prompts<br/>[Settings.tsx]"]
end

subgraph group_api["Application API"]
  node_server["HTTP server and routes<br/>[main.go]"]
  node_handlers["API handlers"]
end

subgraph group_ai["AI and OCR"]
  node_suggestions["Suggestion generation<br/>[app_llm.go]"]
  node_llmclient["LLM client setup<br/>[app_llm.go]"]
  node_ocrflow["OCR processing<br/>[ocr.go]"]
  node_ocrproviders["OCR providers<br/>[provider.go]"]
  node_pdf["Searchable PDF<br/>[pdfrender.go]"]
end

subgraph group_state["Jobs and persistence"]
  node_jobs["Background jobs<br/>[jobs.go]"]
  node_database[("Local database<br/>[local_db.go]")]
  node_ocrhistory["OCR run history<br/>[ocr_runs.go]"]
end

subgraph group_integration["External services"]
  node_paperless[("paperless-ngx")]
  node_llmservice{{"LLM services"}}
  node_ocrservice{{"Specialist OCR services"}}
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_processor
node_webapp -->|"routes to"| node_ocrui
node_webapp -->|"routes to"| node_analysisui
node_webapp -->|"routes to"| node_settingsui
node_processor -->|"requests suggestions"| node_server
node_review -->|"applies changes"| node_server
node_ocrui -->|"submits OCR work"| node_server
node_analysisui -->|"requests analysis"| node_server
node_settingsui -->|"manages settings"| node_server
node_server -->|"dispatches"| node_handlers
node_handlers -->|"generates suggestions"| node_suggestions
node_suggestions -->|"reads document metadata"| node_paperless
node_suggestions -->|"requests generation"| node_llmclient
node_llmclient -->|"calls model"| node_llmservice
node_handlers -->|"updates documents"| node_paperless
node_handlers -->|"queues work"| node_jobs
node_jobs -->|"runs OCR jobs"| node_ocrflow
node_handlers -->|"processes page OCR"| node_ocrflow
node_ocrflow -->|"extracts text"| node_ocrproviders
node_ocrproviders -.->|"uses vision models"| node_llmservice
node_ocrproviders -.->|"uses OCR APIs"| node_ocrservice
node_ocrflow -->|"renders searchable output"| node_pdf
node_ocrflow -->|"records runs"| node_ocrhistory
node_ocrhistory -->|"stores results"| node_database
node_jobs -->|"persists job state"| node_database
node_server -->|"serves interface"| node_webapp

click node_webapp "https://github.com/icereed/paperless-gpt/blob/main/web-app/src/App.tsx"
click node_processor "https://github.com/icereed/paperless-gpt/blob/main/web-app/src/DocumentProcessor.tsx"
click node_review "https://github.com/icereed/paperless-gpt/blob/main/web-app/src/components/SuggestionsReview.tsx"
click node_ocrui "https://github.com/icereed/paperless-gpt/blob/main/web-app/src/OCR.tsx"
click node_analysisui "https://github.com/icereed/paperless-gpt/blob/main/web-app/src/AdhocAnalysis.tsx"
click node_settingsui "https://github.com/icereed/paperless-gpt/blob/main/web-app/src/components/Settings.tsx"
click node_server "https://github.com/icereed/paperless-gpt/blob/main/main.go"
click node_handlers "https://github.com/icereed/paperless-gpt/blob/main/app_http_handlers.go"
click node_suggestions "https://github.com/icereed/paperless-gpt/blob/main/app_llm.go"
click node_llmclient "https://github.com/icereed/paperless-gpt/blob/main/app_llm.go"
click node_ocrflow "https://github.com/icereed/paperless-gpt/blob/main/ocr.go"
click node_ocrproviders "https://github.com/icereed/paperless-gpt/blob/main/ocr/provider.go"
click node_pdf "https://github.com/icereed/paperless-gpt/blob/main/internal/pdfrender/pdfrender.go"
click node_jobs "https://github.com/icereed/paperless-gpt/blob/main/jobs.go"
click node_database "https://github.com/icereed/paperless-gpt/blob/main/local_db.go"
click node_ocrhistory "https://github.com/icereed/paperless-gpt/blob/main/ocr_runs.go"

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_webapp,node_processor,node_review,node_ocrui,node_analysisui,node_settingsui,node_user toneBlue
class node_server,node_handlers toneAmber
class node_suggestions,node_llmclient,node_ocrflow,node_ocrproviders,node_pdf toneMint
class node_jobs,node_database,node_ocrhistory toneRose
class node_paperless,node_llmservice,node_ocrservice toneIndigo
```

## Components

### Web interface

- [Web app routes](https://github.com/icereed/paperless-gpt/blob/main/web-app/src/App.tsx): `web-app/src/App.tsx`
- [Document workflow](https://github.com/icereed/paperless-gpt/blob/main/web-app/src/DocumentProcessor.tsx): `web-app/src/DocumentProcessor.tsx`
- [Suggestion review](https://github.com/icereed/paperless-gpt/blob/main/web-app/src/components/SuggestionsReview.tsx): `web-app/src/components/SuggestionsReview.tsx`
- [OCR interface](https://github.com/icereed/paperless-gpt/blob/main/web-app/src/OCR.tsx): `web-app/src/OCR.tsx`
- [Ad-hoc analysis](https://github.com/icereed/paperless-gpt/blob/main/web-app/src/AdhocAnalysis.tsx): `web-app/src/AdhocAnalysis.tsx`
- [Settings and prompts](https://github.com/icereed/paperless-gpt/blob/main/web-app/src/components/Settings.tsx): `web-app/src/components/Settings.tsx`

### Application API

- [HTTP server and routes](https://github.com/icereed/paperless-gpt/blob/main/main.go): `main.go`
- [API handlers](https://github.com/icereed/paperless-gpt/blob/main/app_http_handlers.go): `app_http_handlers.go`

### AI and OCR

- [Suggestion generation](https://github.com/icereed/paperless-gpt/blob/main/app_llm.go): `app_llm.go`
- [LLM client setup](https://github.com/icereed/paperless-gpt/blob/main/app_llm.go): `app_llm.go`
- [OCR processing](https://github.com/icereed/paperless-gpt/blob/main/ocr.go): `ocr.go`
- [OCR providers](https://github.com/icereed/paperless-gpt/blob/main/ocr/provider.go): `ocr/provider.go`
- [Searchable PDF](https://github.com/icereed/paperless-gpt/blob/main/internal/pdfrender/pdfrender.go): `internal/pdfrender/pdfrender.go`

### Jobs and persistence

- [Background jobs](https://github.com/icereed/paperless-gpt/blob/main/jobs.go): `jobs.go`
- [Local database](https://github.com/icereed/paperless-gpt/blob/main/local_db.go): `local_db.go`
- [OCR run history](https://github.com/icereed/paperless-gpt/blob/main/ocr_runs.go): `ocr_runs.go`

### External services

- **paperless-ngx**
- **LLM services**
- **Specialist OCR services**

### Other components

- **User**

## Connections

- User → Web app routes: uses
- Web app routes → Document workflow: routes to
- Web app routes → OCR interface: routes to
- Web app routes → Ad-hoc analysis: routes to
- Web app routes → Settings and prompts: routes to
- Document workflow → HTTP server and routes: requests suggestions
- Suggestion review → HTTP server and routes: applies changes
- OCR interface → HTTP server and routes: submits OCR work
- Ad-hoc analysis → HTTP server and routes: requests analysis
- Settings and prompts → HTTP server and routes: manages settings
- HTTP server and routes → API handlers: dispatches
- API handlers → Suggestion generation: generates suggestions
- Suggestion generation → paperless-ngx: reads document metadata
- Suggestion generation → LLM client setup: requests generation
- LLM client setup → LLM services: calls model
- API handlers → paperless-ngx: updates documents
- API handlers → Background jobs: queues work
- Background jobs → OCR processing: runs OCR jobs
- API handlers → OCR processing: processes page OCR
- OCR processing → OCR providers: extracts text
- OCR providers → LLM services: uses vision models
- OCR providers → Specialist OCR services: uses OCR APIs
- OCR processing → Searchable PDF: renders searchable output
- OCR processing → OCR run history: records runs
- OCR run history → Local database: stores results
- Background jobs → Local database: persists job state
- HTTP server and routes → Web app routes: serves interface