pngx-sync/AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

pngx-controller is a Paperless-ngx Central Sync Controller: a single-container FastAPI service that reads from a master paperless-ngx instance and syncs documents/metadata to one or more replicas using only the public paperless REST API. Master always wins; replicas are read-only by convention.

The full specification is in pngx-controller-prd.md.

Tech Stack

Layer	Choice
Backend	Python / FastAPI
Scheduler	APScheduler (runs inside FastAPI event loop)
Frontend	Jinja2 templates + HTMX + Pico CSS (no JS build step)
Database	SQLite via SQLModel
Auth	Authentik forward auth via X-authentik-* headers (no app-level auth code)
Transport	Tailscale IPs (bypasses Traefik/public internet)

Architecture

Single process, single container. APScheduler runs the sync job inside the FastAPI event loop. An asyncio.Lock prevents concurrent sync runs.

FastAPI app
├── Web UI (Jinja2 + HTMX) — /, /replicas, /logs, /settings
├── REST API — /api/*
└── APScheduler — sync job every N minutes (default: 15)

SQLite (bind-mounted at /data/db.sqlite3)
├── replicas       — configured instances (URL + encrypted API token)
├── sync_map       — master_doc_id ↔ replica_doc_id mapping per replica
├── sync_runs      — audit log of sync cycles
├── logs           — per-document sync events
└── settings       — master_url, master_token, sync_interval_seconds, log_retention_days

API tokens are encrypted at rest using Fernet with SECRET_KEY from the environment.

Sync Engine Logic

1. Acquire asyncio.Lock (skip if already running)
2. For each enabled replica:
   • ensure_schema_parity: sync tags, correspondents, document types, custom fields by name (IDs differ per instance; name→id mapping is built and used locally)
   • Fetch master docs modified since last sync (?modified__gte=...)
   • For each doc: download file + metadata from master, then create (POST /api/documents/post_document/) or update (PUT /api/documents/{replica_id}/) on replica
   • Skip file re-upload if SHA256 checksum matches sync_map.file_checksum
3. Advance last_sync_ts, close sync_run record, release lock

Schema parity must be established before document sync so custom fields exist on the replica.

Key Design Constraints

• No consume directory — sync via REST API only; consume causes re-OCR, ID collisions, and breaks on live instances
• No changes to paperless containers — controller is fully external
• SPOF accepted — if controller is down, paperless instances run normally; sync resumes on recovery
• Live log tail uses SSE at /api/logs/stream; dashboard sync progress uses HTMX polling /api/sync/running

Environment Variables

Variable	Purpose
SECRET_KEY	Fernet key for encrypting API tokens at rest
DATABASE_URL	SQLite path, e.g. sqlite:////data/db.sqlite3

Implementation Phases (from PRD)

• Phase 1 (MVP): SQLModel schema, settings/replica CRUD, sync engine, APScheduler, basic dashboard, log table
• Phase 2: SSE log stream, sync progress indicator, manual trigger with live feedback
• Phase 3: Full resync per replica, deletion propagation (tombstone table), file checksum skip, alert webhooks