How icereed/paperless-gpt works
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 HTTP server and routes · App.tsx Web app routes · app_http_handlers.go API handlers · ocr.go OCR processing
Components 20
Web interface
- Web app routes
web-app/src/App.tsx - Document workflow
web-app/src/DocumentProcessor.tsx - Suggestion review
web-app/src/components/SuggestionsReview.tsx - OCR interface
web-app/src/OCR.tsx - Ad-hoc analysis
web-app/src/AdhocAnalysis.tsx - Settings and prompts
web-app/src/components/Settings.tsx
Application API
- HTTP server and routes
main.go - API handlers
app_http_handlers.go
AI and OCR
- Suggestion generation
app_llm.go - LLM client setup
app_llm.go - OCR processing
ocr.go - OCR providers
ocr/provider.go - Searchable PDF
internal/pdfrender/pdfrender.go
Jobs and persistence
- Background jobs
jobs.go - Local database
local_db.go - OCR run history
ocr_runs.go
External services
- paperless-ngx
- LLM services
- Specialist OCR services
Other components
- User
Connections 27
- 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