culater/paperless-tree-view repository overview

⁠paperless-tree-view

Displays the documents of a paperless-ngx⁠ instance in exactly the directory hierarchy that paperless-ngx itself creates on disk (via PAPERLESS_FILENAME_FORMAT and/or per-document StoragePath templates), instead of the usual flat document list. Also includes full-text search with hierarchically displayed matches, and inline preview/download right in the app.

The app does not recompute the tree structure itself (no reimplementation of paperless' Jinja2 filename templating). Instead it reads the relative path paperless-ngx has already resolved for each document via GET /api/documents/{id}/metadata/ (field media_filename) and builds the tree from that.

⁠Architecture

• Backend: Node.js/TypeScript, Express. Holds an in-memory cache of the document tree, does a full resync on startup and then periodically (SYNC_INTERVAL_MINUTES), and proxies download/preview/thumbnail requests to paperless-ngx (the paperless API token never leaves the server).
• Frontend: React (Vite) + Tailwind CSS, served by the backend as static files.

⁠Configuration

See .env.example. Required: PAPERLESS_URL, PAPERLESS_TOKEN.

⁠Local development

# Backend
cd backend && npm install && npm run dev   # runs on port 3000 (override via PORT env)

# Frontend (separate terminal)
cd frontend && npm install && npm run dev  # Vite dev server, proxies /api to the backend port

⁠Docker

cp .env.example .env   # fill in PAPERLESS_URL / PAPERLESS_TOKEN
docker compose up --build

The app is then available at http://localhost:3000.

⁠Known limitations

• Single instance only. The document tree lives purely in process memory (no Redis/DB) — multiple concurrently running container replicas would sync independently and serve inconsistent trees.
• Full resync on every restart and every interval tick. There is (deliberately, for simplicity) no incremental sync via paperless' modified__after filter. This can be noticeable for very large document counts — SYNC_INTERVAL_MINUTES/SYNC_CONCURRENCY are configurable for that reason.
• media_filename staleness: if the global PAPERLESS_FILENAME_FORMAT is changed in paperless-ngx without subsequently running paperless' document_renamer management command, the path paperless reports can be briefly stale. This is a property of paperless-ngx itself, not of this app.

⁠CI/CD

The GitLab CI pipeline (.gitlab-ci.yml) builds, tests, and publishes the image following the pattern of the other homesrvr projects (see homesrvr/defaults for the shared template). It publishes to both the GitLab Container Registry and Docker Hub. The release version number is read from backend/package.json (version).