# clusterzx/paperless-ai architecture

> Architecture diagram of the GitHub repository clusterzx/paperless-ai, 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/clusterzx/paperless-ai
- Repository: https://github.com/clusterzx/paperless-ai

## Overview

Paperless-AI is a web application that automates document metadata generation and adds manual review, configurable classification, and RAG-based search and chat for a Paperless-ngx archive. The main automated workflow scans Paperless documents, requests AI analysis, then updates document metadata and records processing state. In the RAG workflow, the web API delegates indexing and search to a Python service; question answering also retrieves document content and uses the configured AI provider. README capabilities are included, but links for unsampled setup, manual, and rules implementations are limited to what the tree and excerpts support.

Main entry points: [`server.js`](https://github.com/clusterzx/paperless-ai/blob/main/server.js) (Application server), [`services/ragService.js`](https://github.com/clusterzx/paperless-ai/blob/main/services/ragService.js) (RAG client), [`services/paperlessService.js`](https://github.com/clusterzx/paperless-ai/blob/main/services/paperlessService.js) (Paperless client), [`services/aiServiceFactory.js`](https://github.com/clusterzx/paperless-ai/blob/main/services/aiServiceFactory.js) (AI service factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_processing["Document processing"]
  node_server["Application server<br/>[server.js]"]
  node_paperless_client["Paperless client"]
  node_document_model[("Processing records<br/>[document.js]")]
  node_manual_service["Manual processing<br/>[manualService.js]"]
end

subgraph group_rag["Search and chat"]
  node_rag_routes["RAG API routes<br/>[rag.js]"]
  node_rag_service["RAG client<br/>[ragService.js]"]
  node_rag_engine["RAG index and search<br/>[main.py]"]
  node_vector_store[("Semantic index<br/>[main.py]")]
end

subgraph group_ai["AI providers"]
  node_ai_factory["AI service factory"]
  node_ai_providers["AI provider services"]
end

subgraph group_web["Web application"]
  node_rag_ui["RAG interface<br/>[chat.js]"]
  node_manual_ui["Manual processing UI<br/>[manual.js]"]
  node_setup_routes["Setup routes<br/>[setup.js]"]
  node_setup_service["Setup service<br/>[setupService.js]"]
  node_settings_ui["Settings interface<br/>[settings.js]"]
  node_web_views["Web views"]
end

node_timer(("Scheduled scan"))
node_paperless["Paperless-ngx"]
node_llm["AI model API"]
node_browser_user(("Web user"))

node_timer -->|"triggers scan"| node_server
node_server -->|"fetches documents"| node_paperless_client
node_paperless_client -->|"reads and updates"| node_paperless
node_server -->|"requests analysis"| node_ai_factory
node_ai_factory -->|"selects provider"| node_ai_providers
node_ai_providers -->|"sends prompts"| node_llm
node_server -->|"records processing"| node_document_model
node_browser_user -->|"asks or searches"| node_rag_ui
node_rag_ui -->|"submits request"| node_rag_routes
node_rag_routes -->|"delegates request"| node_rag_service
node_rag_service -->|"calls RAG API"| node_rag_engine
node_rag_engine -->|"indexes and searches"| node_vector_store
node_rag_service -->|"fetches source content"| node_paperless_client
node_rag_service -->|"requests answer generation"| node_ai_factory
node_browser_user -->|"reviews documents"| node_manual_ui
node_browser_user -->|"configures application"| node_setup_routes
node_setup_routes -->|"delegates setup"| node_setup_service
node_browser_user -->|"changes preferences"| node_settings_ui
node_browser_user -->|"uses interface"| node_web_views

click node_server "https://github.com/clusterzx/paperless-ai/blob/main/server.js"
click node_paperless_client "https://github.com/clusterzx/paperless-ai/blob/main/services/paperlessService.js"
click node_ai_factory "https://github.com/clusterzx/paperless-ai/blob/main/services/aiServiceFactory.js"
click node_ai_providers "https://github.com/clusterzx/paperless-ai/tree/main/services"
click node_document_model "https://github.com/clusterzx/paperless-ai/blob/main/models/document.js"
click node_rag_routes "https://github.com/clusterzx/paperless-ai/blob/main/routes/rag.js"
click node_rag_service "https://github.com/clusterzx/paperless-ai/blob/main/services/ragService.js"
click node_rag_engine "https://github.com/clusterzx/paperless-ai/blob/main/main.py"
click node_vector_store "https://github.com/clusterzx/paperless-ai/blob/main/main.py"
click node_rag_ui "https://github.com/clusterzx/paperless-ai/blob/main/public/js/chat.js"
click node_manual_ui "https://github.com/clusterzx/paperless-ai/blob/main/public/js/manual.js"
click node_manual_service "https://github.com/clusterzx/paperless-ai/blob/main/services/manualService.js"
click node_setup_routes "https://github.com/clusterzx/paperless-ai/blob/main/routes/setup.js"
click node_setup_service "https://github.com/clusterzx/paperless-ai/blob/main/services/setupService.js"
click node_settings_ui "https://github.com/clusterzx/paperless-ai/blob/main/public/js/settings.js"
click node_web_views "https://github.com/clusterzx/paperless-ai/tree/main/views"

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_server,node_paperless_client,node_document_model,node_manual_service,node_browser_user toneBlue
class node_rag_routes,node_rag_service,node_rag_engine,node_vector_store toneAmber
class node_ai_factory,node_ai_providers,node_llm toneMint
class node_rag_ui,node_manual_ui,node_setup_routes,node_setup_service,node_settings_ui,node_web_views toneRose
class node_timer,node_paperless toneIndigo
```

## Components

### Document processing

- [Application server](https://github.com/clusterzx/paperless-ai/blob/main/server.js): `server.js`
- [Paperless client](https://github.com/clusterzx/paperless-ai/blob/main/services/paperlessService.js): `services/paperlessService.js`
- [Processing records](https://github.com/clusterzx/paperless-ai/blob/main/models/document.js): `models/document.js`
- [Manual processing](https://github.com/clusterzx/paperless-ai/blob/main/services/manualService.js): `services/manualService.js`

### Search and chat

- [RAG API routes](https://github.com/clusterzx/paperless-ai/blob/main/routes/rag.js): `routes/rag.js`
- [RAG client](https://github.com/clusterzx/paperless-ai/blob/main/services/ragService.js): `services/ragService.js`
- [RAG index and search](https://github.com/clusterzx/paperless-ai/blob/main/main.py): `main.py`
- [Semantic index](https://github.com/clusterzx/paperless-ai/blob/main/main.py): `main.py`

### AI providers

- [AI service factory](https://github.com/clusterzx/paperless-ai/blob/main/services/aiServiceFactory.js): `services/aiServiceFactory.js`
- [AI provider services](https://github.com/clusterzx/paperless-ai/tree/main/services): `services`

### Web application

- [RAG interface](https://github.com/clusterzx/paperless-ai/blob/main/public/js/chat.js): `public/js/chat.js`
- [Manual processing UI](https://github.com/clusterzx/paperless-ai/blob/main/public/js/manual.js): `public/js/manual.js`
- [Setup routes](https://github.com/clusterzx/paperless-ai/blob/main/routes/setup.js): `routes/setup.js`
- [Setup service](https://github.com/clusterzx/paperless-ai/blob/main/services/setupService.js): `services/setupService.js`
- [Settings interface](https://github.com/clusterzx/paperless-ai/blob/main/public/js/settings.js): `public/js/settings.js`
- [Web views](https://github.com/clusterzx/paperless-ai/tree/main/views): `views`

### Other components

- **Scheduled scan**
- **Paperless-ngx**
- **AI model API**
- **Web user**

## Connections

- Scheduled scan → Application server: triggers scan
- Application server → Paperless client: fetches documents
- Paperless client → Paperless-ngx: reads and updates
- Application server → AI service factory: requests analysis
- AI service factory → AI provider services: selects provider
- AI provider services → AI model API: sends prompts
- Application server → Processing records: records processing
- Web user → RAG interface: asks or searches
- RAG interface → RAG API routes: submits request
- RAG API routes → RAG client: delegates request
- RAG client → RAG index and search: calls RAG API
- RAG index and search → Semantic index: indexes and searches
- RAG client → Paperless client: fetches source content
- RAG client → AI service factory: requests answer generation
- Web user → Manual processing UI: reviews documents
- Web user → Setup routes: configures application
- Setup routes → Setup service: delegates setup
- Web user → Settings interface: changes preferences
- Web user → Web views: uses interface