How dragonhp/paperless-ngx works
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