# dragonhp/paperless-ngx architecture

> Architecture diagram of the GitHub repository dragonhp/paperless-ngx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dragonhp/paperless-ngx
- Repository: https://github.com/dragonhp/paperless-ngx

## Overview

##### Project type and purpose
- Paperless-ngx is a full-stack, containerized document management system.
- It comprises an Angular-based single-page application (src-ui) talking to a Django REST/WebSocket backend (src/*), with Celery workers for asynchronous document processing and optional language parsers (Tesseract, Tika, text).

##### File-structure highlights
- Top‐level “src-ui/” folder: Angular front end—components, services, assets, e2e tests.
- Top‐level “src/” folder: Django monolith split into apps:
- paperless (core, auth, config, websockets)
- documents (document models, converters, classifiers, file‐handling)
- paperless_mail (IMAP/POP3 fetcher, mail parsers)
- paperless_tesseract, paperless_tika, paperless_text (OCR/parsing plugins)
- “docker/compose”: multiple compose files for Docker services (webserver, scheduler, worker, consumer, flower, DB variants).
- “.devcontainer”: VS Code remote/devcontainer setup.
- Configuration/build: Dockerfile, pyproject.toml, mkdocs.yml for docs.

##### Architecture overview
- User browser ↔ Angular SPA
- HTTP(S) REST calls
- WebSocket for live status/progress
- Angular SPA ↔ Django REST API & WebSocket endpoints
- Authentication (Django allauth/socialaccount)
- CRUD on documents, tags, workflows, permissions
- Django core
- Gunicorn/Uvicorn → s6 → served by webserver container
- Database (PostgreSQL/MariaDB/SQLite)
- Redis as broker & cache
- Celery scheduler & workers for asynchronous tasks
- Celery Flower for monitoring
- Celery Workers
- document consumer: ingestion pipeline
- schedulers: periodic tasks (sanity checks, archiving, indexing)
- mail fetcher: IMAP/POP3 → document pipeline
- plugins (Tesseract, Tika, text) invoked by tasks
- Storage
- Mounted volumes for originals, archive, thumbnails
- Optional external storage backends via Django storage API

##### Architectural patterns and principles
- Separation of concerns: UI vs API vs background workers
- Asynchronous processing via Celery + Redis
- Plugin architecture: parsers and converters loaded dynamically
- Containerized, reproducible environments via Docker Compose & s6-overlay
- 12-factor style: configuration in environment variables, logs to stdout, ephemeral containers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "Browser"
        AngularSPA["Angular SPA"]:::ui
    end

    %% API Layer
    subgraph "API Server"
        DjangoAPI["Django REST API & WebSocket"]:::api
        CeleryApp["Celery App"]:::api
    end

    %% Data Stores
    subgraph "Data Stores"
        DB[("PostgreSQL/MariaDB/SQLite")]:::datastore
        Redis[("Redis (Broker/Cache)")]:::datastore
        Storage[("Persistent Volumes")]:::datastore
    end

    %% Background Workers
    subgraph "Background Workers"
        direction TB
        DocumentConsumer["Document Consumer"]:::worker
        Scheduler["Scheduler"]:::worker
        MailFetcher["Mail Fetcher"]:::worker
        subgraph "Plugins"
            direction TB
            Tesseract["Tesseract Plugin"]:::worker
            Tika["Tika Plugin"]:::worker
            Text["Text Plugin"]:::worker
        end
    end

    %% External Services
    subgraph "External Services"
        IMAP["IMAP/POP3 Mail Server"]:::external
        ExternalTika["External Tika Server"]:::external
    end

    %% Orchestration
    subgraph "Orchestration"
        Compose["Docker Compose"]:::external
        S6["s6-overlay Init"]:::external
        DevContainer["VS Code Devcontainer"]:::external
    end

    %% Connections
    AngularSPA -->|"HTTP/WS"| DjangoAPI
    DjangoAPI -->|"tasks()"| Redis
    DjangoAPI -->|"reads/writes"| DB
    DjangoAPI -->|"stores files"| Storage
    DjangoAPI -->|"uses"| CeleryApp

    Redis -->|"dequeue"| DocumentConsumer
    Redis -->|"dequeue"| Scheduler
    Redis -->|"dequeue"| MailFetcher

    DocumentConsumer -->|"writes/reads"| DB
    DocumentConsumer -->|"stores files"| Storage
    DocumentConsumer -->|"uses plugins"| Tesseract
    DocumentConsumer -->|"uses plugins"| Tika
    DocumentConsumer -->|"uses plugins"| Text

    Scheduler -->|"writes/reads"| DB
    MailFetcher -->|"writes/reads"| DB
    MailFetcher -->|"fetches from"| IMAP

    Tika -->|"optional call"| ExternalTika

    Compose --> AngularSPA
    Compose --> DjangoAPI
    Compose --> DocumentConsumer
    Compose --> Scheduler
    Compose --> MailFetcher
    Compose --> S6

    %% Click Events
    click AngularSPA "https://github.com/dragonhp/paperless-ngx/tree/dev/src-ui/"
    click DjangoAPI "https://github.com/dragonhp/paperless-ngx/tree/dev/src/paperless/"
    click CeleryApp "https://github.com/dragonhp/paperless-ngx/blob/dev/src/paperless/celery.py"
    click DocumentConsumer "https://github.com/dragonhp/paperless-ngx/blob/dev/src/documents/consumer.py"
    click MailFetcher "https://github.com/dragonhp/paperless-ngx/blob/dev/src/paperless_mail/management/commands/mail_fetcher.py"
    click Tesseract "https://github.com/dragonhp/paperless-ngx/tree/dev/src/paperless_tesseract/"
    click Tika "https://github.com/dragonhp/paperless-ngx/tree/dev/src/paperless_tika/"
    click Text "https://github.com/dragonhp/paperless-ngx/tree/dev/src/paperless_text/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#1f77b4;
    classDef api fill:#d4edda,stroke:#2ca02c;
    classDef datastore fill:#fff3cd,stroke:#ff7f0e;
    classDef worker fill:#e2e3e5,stroke:#9467bd;
    classDef external fill:#f8f9fa,stroke:#7f7f7f;
```
