# Self-Hosted PDF Editor — Implementation Plan
**Project codename:** `paperjet` (rename freely)
**Document version:** 1.1
**Status:** Foundational specification — this document is the single source of truth. Every AI agent working on this project reads this file first, in full, before writing code.
> **v1.1 changes:** resolved the four open questions — upload ceiling set to 200 MB; versioning reframed around accidental-loss recovery with a document-level **trash/restore** added as the primary safety net; cookie/proxy behavior pinned (direct HTTP for dev only, everything through the HTTPS proxy in production); signature capture specified as **draw + type-to-signature with live multi-font preview**.
---
## 1. Purpose & Scope
A self-hosted, single-user, browser-based PDF editor with a Sejda-style annotation workflow. The user adds text boxes, freehand drawing, signatures, images, highlights, and shapes onto a PDF, moves and resizes them freely, and exports a flattened PDF. The application persists work continuously (autosave), keeps a per-file version history, and supports undo/redo.
It runs on the user's own server via Docker Compose, is reachable over LAN and over WAN through an nginx reverse proxy, and is protected by a single password. It depends on **no external programs, no external containers, and no third-party APIs**. Libraries and packages bundled into the application's own containers are permitted.
### Non-goals (v1)
- Multi-user collaboration / real-time co-editing
- True content editing (reflowing or rewriting the PDF's existing text stream)
- OCR (can be added later as an annotation-source plugin)
- Cloud sync
The architecture must not foreclose these. Future features are designed for, not built now.
---
## 2. Key Architectural Decisions (and changes from earlier discussion)
These decisions supersede anything discussed earlier in planning. Where they change a prior assumption, the change and its rationale are called out.
### 2.1 Rendering happens on the client, not the server *(CHANGED)*
Earlier planning floated server-side page rendering (PyMuPDF renders each page to an image, the browser displays the image). **We are not doing that.** The browser renders pages directly with PDF.js.
**Why:** Client-side rendering gives crisp, GPU-accelerated, infinitely zoomable pages with no per-page network round-trip and far less bandwidth — which matters for the WAN/reverse-proxy use case. Server-side image rendering would be blurry on zoom, slow over WAN, and heavier on the server.
**Consequence:** The server's PDF engine (PyMuPDF) is used for exactly two things — generating small thumbnails for the home page, and flattening annotations into the final exported PDF. It never renders full pages for the live editor.
### 2.2 The server stores annotations opaquely; only export understands them
The backend persists the annotation array as a JSON blob and does not parse individual annotation types for normal CRUD. Only the **export renderer** has per-type logic, dispatched through a type registry. This is the core extensibility decision: a new annotation type (e.g. "stamp", "checkbox", "redaction") requires a new frontend tool and a new export-renderer function, with **no database migration and no API change**.
### 2.3 `pdf-lib` is dropped entirely *(CHANGED)*
Because all PDF writing happens server-side in PyMuPDF, the browser never manipulates raw PDF bytes. Earlier planning included `pdf-lib` as a fallback writer; it is removed. One rendering engine for display (PDF.js), one writing engine for export (PyMuPDF). Fewer engines, fewer coordinate-mismatch bugs.
### 2.4 Versions store annotation snapshots, not flattened PDFs — and exist to recover from accidental loss *(CHANGED / IMPROVED)*
Earlier planning suggested flattening a real PDF per version. Instead, a version is a lightweight JSON snapshot of the annotation state. The original uploaded PDF is immutable on disk; every version is that original plus a layer of annotations. Flattening to an actual PDF happens **only on export/download**.
**Purpose drives the policy.** Versioning here is a *safety net against accidental loss*, not a granular editing timeline. There are two distinct things a user can lose by accident, and each gets its own net:
- **A whole document**, deleted by mistake → recovered via a document-level **trash/restore** (soft delete, §6.2 / §9.6).
- **Annotation work inside a document**, cleared or overwritten by mistake → recovered via **version checkpoints** (§9.2).
Because the goal is recovery rather than fine-grained history, auto-checkpoints are taken at meaningful safety boundaries (document close, and immediately before any destructive operation like "clear all" or a restore) rather than on a noisy time-based cadence. Manual checkpoints are always available.
**Why snapshots:** they're kilobytes, not megabytes, so both nets are effectively free. Any version restores by loading its JSON, and exports on demand.
### 2.5 Canonical coordinate space is fixed and documented
All stored coordinates are in **PDF points (1/72 inch), top-left origin, relative to the page's unrotated CropBox.** This single rule is the most important correctness constraint in the project (see §8).
### 2.6 Session auth with hashed password, not HTTP Basic *(CHANGED)*
Because the app is WAN-exposed, auth is a real login screen backed by an Argon2id password hash and a signed, httpOnly, SameSite cookie — not HTTP Basic Auth. Login is rate-limited.
---
## 3. Technology Stack (final)
| Layer | Choice | Notes |
|---|---|---|
| Frontend language | TypeScript (strict mode) | Type safety across the PDF/screen coordinate boundary |
| Frontend framework | React 18 | Largest ecosystem; best-represented in all agents' training |
| Build tool | Vite | Fast, simple, standard |
| PDF rendering (client) | PDF.js (`pdfjs-dist`) | Display only |
| Canvas editing overlay | Fabric.js | Text boxes, drawing, drag/resize/select handles |
| Frontend state | Zustand | Lightweight, predictable; good fit for editor + undo stack |
| Styling | Tailwind CSS v4 | CSS-first `@theme` config; fast iteration toward a clean Sejda-like light UI |
| Backend language | Python 3.12 | Chosen for PyMuPDF |
| Backend framework | FastAPI | Async, typed, auto-generates OpenAPI |
| PDF processing (server) | PyMuPDF (`pymupdf` / fitz) | Thumbnails + export flatten. MuPDF compiled into the wheel — self-contained |
| Validation | Pydantic v2 | Mirrors the TS annotation types |
| ORM | SQLAlchemy 2.x | With Alembic for migrations |
| Database | SQLite (WAL mode) | Single-user scale; embedded, no extra container |
| Password hashing | Argon2id (`argon2-cffi`) | |
| Web server (frontend) | nginx | Serves the static React build; also the app-internal entry |
| ASGI server (backend) | uvicorn | Behind nginx |
| Orchestration | Docker Compose | |
| External programs / containers / APIs | **None** | Hard requirement |
**The user's own nginx reverse proxy** sits in front of this stack and is out of scope for the compose file (it already exists). The compose stack exposes one HTTP port for the proxy to target.
---
## 4. System Architecture
```
┌───────────────────────────┐
Internet (WAN) ───────▶│ User's nginx reverse proxy│ (existing, out of scope)
LAN ──────────────────▶│ TLS termination, routing │
└─────────────┬─────────────┘
│ http :8080
┌─────────────▼─────────────────────────────┐
│ Docker Compose │
│ │
│ ┌──────────────┐ ┌────────────────┐ │
│ │ frontend │ │ backend │ │
│ │ nginx │─────▶│ FastAPI │ │
│ │ serves SPA │ /api │ uvicorn │ │
│ │ proxies /api│ │ PyMuPDF │ │
│ └──────────────┘ │ SQLAlchemy │ │
│ └───────┬────────┘ │
│ │ │
│ ┌──────────▼────────┐ │
│ │ volumes │ │
│ │ pdf_storage/ │ │
│ │ thumbnails/ │ │
│ │ db/app.sqlite │ │
│ └───────────────────┘ │
└────────────────────────────────────────────┘
```
- The `frontend` nginx serves the SPA and reverse-proxies `/api/*` to the `backend`. This means the browser sees a single origin — no CORS complexity, cookies "just work."
- The user's outer reverse proxy points at the `frontend` container's published port.
---
## 5. Repository Structure
A single monorepo. Two deployable images.
```
paperjet/
├── README.md
├── ARCHITECTURE.md # symlink or copy of THIS plan; agents read first
├── docker-compose.yml
├── .env.example
├── .github/workflows/ci.yml # lint + typecheck + test on push
│
├── frontend/
│ ├── Dockerfile # multi-stage: build SPA, serve via nginx
│ ├── nginx.conf # SPA fallback + /api proxy
│ ├── package.json
│ ├── tsconfig.json # strict: true
│ ├── vite.config.ts
│ ├── # Tailwind v4: no config file — design tokens are defined via @theme in src/index.css
│ └── src/
│ ├── main.tsx
│ ├── app/ # routing, layout, theme
│ ├── pages/
│ │ ├── LoginPage.tsx
│ │ ├── HomePage.tsx # recent + upload + library tabs
│ │ └── EditorPage.tsx
│ ├── features/
│ │ ├── auth/
│ │ ├── library/ # list, upload, delete, search
│ │ ├── editor/
│ │ │ ├── canvas/ # Fabric.js integration
│ │ │ ├── tools/ # one module per annotation tool
│ │ │ ├── toolbar/
│ │ │ ├── pages/ # PDF.js page rendering
│ │ │ └── history/ # undo/redo stack
│ │ └── versions/
│ ├── lib/
│ │ ├── coords.ts # ⚠ THE coordinate transform module (§8)
│ │ ├── api/ # generated/typed API client
│ │ └── annotations/ # shared annotation type defs + registry
│ └── types/ # generated from backend OpenAPI
│
├── backend/
│ ├── Dockerfile
│ ├── pyproject.toml
│ ├── alembic/ # migrations
│ └── app/
│ ├── main.py # FastAPI app, router mounting
│ ├── config.py # env-driven settings (Pydantic Settings)
│ ├── db.py # engine, session, WAL pragma
│ ├── models/ # SQLAlchemy models
│ ├── schemas/ # Pydantic request/response models
│ ├── api/v1/
│ │ ├── auth.py
│ │ ├── documents.py
│ │ ├── annotations.py
│ │ ├── versions.py
│ │ └── export.py
│ ├── services/
│ │ ├── storage.py # file IO on the volume
│ │ ├── thumbnails.py # PyMuPDF thumbnail generation
│ │ └── export/ # PyMuPDF flatten + type registry (§9.3)
│ │ ├── renderer.py
│ │ └── handlers/ # one handler per annotation type
│ ├── auth/ # hashing, session cookie, dependencies
│ └── tests/
│
└── shared/
└── annotation-schema.json # canonical schema; source for TS + Pydantic
```
**`shared/annotation-schema.json`** is the contract for the annotation data model. Both the TypeScript types and the Pydantic models derive from it. When the model changes, it changes here first.
---
## 6. Data Model
SQLite, WAL mode enabled. UUIDv4 string primary keys throughout.
### 6.1 Tables
**`settings`** (singleton row, `id = 1`)
| column | type | notes |
|---|---|---|
| id | INTEGER PK | always 1 |
| password_hash | TEXT | Argon2id; NULL until first-run setup |
| created_at | TEXT (ISO8601) | |
| updated_at | TEXT | |
**`documents`**
| column | type | notes |
|---|---|---|
| id | TEXT PK | uuid |
| title | TEXT | display name, user-editable; defaults to filename |
| original_filename | TEXT | |
| file_path | TEXT | path on `pdf_storage` volume |
| thumbnail_path | TEXT | path on `thumbnails` volume; NULL until generated |
| size_bytes | INTEGER | |
| page_count | INTEGER | |
| created_at | TEXT | upload time |
| updated_at | TEXT | last edit (drives "recently edited") |
| deleted_at | TEXT | soft delete; NULL = active |
**`annotation_states`** (current working layer, one row per document)
| column | type | notes |
|---|---|---|
| document_id | TEXT PK FK | → documents.id |
| data | TEXT (JSON) | the annotation array (§7) |
| updated_at | TEXT | written by autosave |
**`versions`** (history snapshots)
| column | type | notes |
|---|---|---|
| id | TEXT PK | uuid |
| document_id | TEXT FK | |
| label | TEXT | NULL for auto-checkpoints |
| data | TEXT (JSON) | full annotation snapshot |
| kind | TEXT | `manual` \| `auto` |
| created_at | TEXT | |
Indexes: `documents(updated_at)`, `documents(deleted_at)`, `versions(document_id, created_at)`.
### 6.2 Soft deletes / trash (v1 feature)
Deleting a document is a **soft delete**: it sets `documents.deleted_at` and moves the row out of the active library into a **Trash** view, from which it can be **restored**. This is the primary recovery path for an accidentally deleted file. The underlying PDF, thumbnail, and annotation state are retained while the document is in trash.
- **Restore** clears `deleted_at`, returning the document to the library with its annotations intact.
- **Permanent delete** happens either when the user empties trash explicitly, or automatically after a retention window (default **30 days** in trash), at which point files and rows are purged. Retention is a config value.
- Bulk delete and bulk restore operate on multiple selected items.
---
## 7. Annotation Data Model
The single most reused structure in the system. Defined once in `shared/annotation-schema.json`, mirrored as a TS discriminated union and Pydantic models.
### 7.1 Envelope (common to all types)
```jsonc
{
"id": "uuid",
"page": 0, // 0-indexed
"type": "text", // discriminator; drives the registry
"rect": { // CANONICAL space: PDF points, top-left origin (§8)
"x": 72.0,
"y": 144.0,
"width": 200.0,
"height": 48.0
},
"rotation": 0, // degrees, clockwise, about rect center
"z": 3, // z-order within the page
"props": { /* type-specific, opaque to the server */ },
"createdAt": "2026-06-10T...",
"updatedAt": "2026-06-10T..."
}
```
### 7.2 Per-type `props` (v1 set)
| type | `props` shape (summary) |
|---|---|
| `text` | `{ text, fontFamily, fontSize, color, align, bold, italic, lineHeight }` |
| `draw` | `{ paths: [[x,y]...], strokeColor, strokeWidth, opacity }` (points in rect-local space) |
| `signature` | discriminated by `mode`:
• draw → `{ mode: "draw", ref, strokeColor }` (a captured raster/vector signature, stored as an asset)
• type → `{ mode: "type", text, fontFamily, color }` (rendered as text in a bundled signature font) |
| `image` | `{ ref, naturalWidth, naturalHeight }` (uploaded raster) |
| `highlight` | `{ color, opacity }` |
| `shape` | `{ kind: "rect"\|"ellipse"\|"line"\|"arrow", strokeColor, fillColor, strokeWidth }` |
Large binary payloads (signature PNGs, placed images) are **not** inlined into the JSON. They are uploaded to an assets endpoint and referenced by id (`ref`). This keeps the annotation JSON small and the autosave PUT cheap. See §9.4.
### 7.3 Extensibility contract
- Adding a type = (a) add its `props` schema to `annotation-schema.json`, (b) add a frontend tool module under `editor/tools/`, (c) register a frontend renderer + an export handler in the registries. **No DB or API change.**
- The server must round-trip unknown `type` values without error (forward compatibility): if an export handler is missing for a type, it is skipped with a logged warning, never a crash.
---
## 8. The Coordinate System (read this twice)
**Canonical storage space:** PDF points (1/72"), **top-left origin** (y increases downward), relative to each page's CropBox at **0° rotation**.
Rationale for top-left origin: Fabric.js canvas space is top-left, and PyMuPDF's high-level API is top-left native — so two of the three engines need no flip. Only PDF.js (whose `viewport` PDF-point conversions are bottom-left) is flipped, in exactly one place.
`lib/coords.ts` is the **only** module permitted to convert between coordinate spaces. No component computes its own transforms inline. It exposes:
```ts
// canonical (PDF points, top-left) ↔ screen (CSS pixels at current zoom)
pdfToScreen(p: PdfPoint, viewport: PageViewport): ScreenPoint
screenToPdf(p: ScreenPoint, viewport: PageViewport): PdfPoint
pdfRectToScreen(r: PdfRect, viewport): ScreenRect
screenRectToPdf(r: ScreenRect, viewport): PdfRect
```
It must correctly handle, with unit tests for each:
1. **Zoom** — scaling without cumulative drift.
2. **Page rotation** — pages with intrinsic /Rotate of 90/180/270°.
3. **Device pixel ratio** — retina vs standard displays.
4. **CropBox ≠ MediaBox** — pages whose visible box is offset from the media origin.
5. **Y-axis flip** for the PDF.js boundary specifically.
**Verification gate:** before any annotation tool is built, write a round-trip test — `screenToPdf(pdfToScreen(p)) ≈ p` within 0.01pt across all rotations and zoom levels — and a cross-engine test that places a known rect via the frontend transform and confirms PyMuPDF stamps it in the same visual location. The export renderer and the live editor must agree pixel-for-pixel. This gate is non-negotiable; misalignment here corrupts every saved annotation.
---
## 9. Backend Behavior
### 9.1 Autosave model
- Frontend debounces 500ms after the last edit, then `PUT /documents/{id}/annotations` with the **full** current annotation array (idempotent full-state replace — simpler and more crash-safe than diff patches at this scale).
- The PUT updates `annotation_states.data` and bumps `documents.updated_at`.
- Concurrent-tab safety: last write wins (single user, acceptable). Include an `updatedAt` in the payload so a stale tab can be detected and warned, but do not block.
### 9.2 Versioning model
- **Manual checkpoint:** `POST /documents/{id}/versions` snapshots current working state into `versions` with `kind=manual` and an optional label. Manual versions are kept indefinitely.
- **Auto checkpoint:** the backend snapshots automatically at *safety boundaries* — on document close, and immediately **before any destructive operation** (a "clear all", or a version restore). This keeps the net focused on recoverable accidents rather than logging every keystroke. Auto versions are retained for a rolling window (default **30 days**, config-driven) and pruned beyond it; manual versions are never auto-pruned.
- **Restore:** `POST /documents/{id}/versions/{vid}/restore` first auto-snapshots the *current* state (so a restore is itself undoable), then copies the target version's `data` into the working state.
In-document accidental edits during a single session are also covered by the in-memory undo/redo stack (§12.3); versions are the cross-session and pre-destructive-action net.
### 9.3 Export (flatten) via type registry
`services/export/renderer.py` opens the original PDF with PyMuPDF, iterates the annotation array, and dispatches each by `type` to a handler in `services/export/handlers/`. Each handler receives `(page, annotation, coord_ctx)` and draws into the page using PyMuPDF primitives (`insert_textbox`, `draw_line`, `insert_image`, `draw_rect`, etc.). Output is written to a temp file and streamed back.
- The registry is a dict `{type: handler}`; adding a type adds a handler, nothing else.
- Missing handler → log + skip, never crash (§7.3).
- Export accepts an optional `versionId` to export a historical version instead of the working state.
- Fonts: bundle inside the backend image (no external program) two font sets so server export matches the live editor exactly: (a) standard-metric fonts — the Liberation family for Helvetica/Times/Courier compatibility — for `text` annotations; and (b) a small curated set of **signature/script fonts** for typed signatures (§7.2, §12.5), the same faces offered in the editor's live preview. Embed used fonts into the output for portability.
### 9.4 Assets (binary annotation payloads)
- `POST /documents/{id}/assets` (multipart) stores a signature PNG or placed image on the `pdf_storage` volume, returns `{ ref }`.
- Annotations reference assets by `ref`; the JSON stays small.
- Orphan assets (unreferenced after edits) are swept periodically.
### 9.5 Thumbnails
- On upload, generate a single first-page thumbnail (PyMuPDF, ~300px wide) to `thumbnails/`. Cheap. Regenerate lazily if missing. Used by home-page cards.
### 9.6 Trash / restore
- Delete sets `documents.deleted_at`; the document leaves the active library and appears in **Trash**.
- Restore clears `deleted_at`.
- A periodic sweep permanently purges documents whose `deleted_at` is older than the retention window (default 30 days), deleting their PDF, thumbnail, assets, annotation state, and versions. Purge is also triggerable manually via "empty trash".
- All list queries for the active library filter `deleted_at IS NULL`; the trash view filters `deleted_at IS NOT NULL`.
---
## 10. Full API Specification
Base path `/api/v1`. All responses JSON unless noted. All endpoints except `auth/*` and `health` require a valid session cookie; unauthenticated requests get `401`. Errors use a consistent envelope: `{ "error": { "code": str, "message": str } }`.
### 10.1 Auth
| Method | Path | Body | Returns | Notes |
|---|---|---|---|---|
| GET | `/auth/status` | — | `{ authenticated: bool, setupRequired: bool }` | `setupRequired` true if no password set |
| POST | `/auth/setup` | `{ password }` | `204` | First-run only; 409 if already set |
| POST | `/auth/login` | `{ password }` | `204` + sets cookie | Rate-limited (see §11) |
| POST | `/auth/logout` | — | `204` | Clears cookie |
| PUT | `/auth/password` | `{ currentPassword, newPassword }` | `204` | 403 on mismatch |
### 10.2 Documents
| Method | Path | Body / Query | Returns |
|---|---|---|---|
| GET | `/documents` | `?sort=recent\|title&q=&deleted=false&limit=&offset=` | `{ items: DocumentMeta[], total }` |
| POST | `/documents` | multipart `file` | `DocumentMeta` (201) |
| GET | `/documents/{id}` | — | `DocumentMeta` |
| PATCH | `/documents/{id}` | `{ title? }` | `DocumentMeta` |
| DELETE | `/documents/{id}` | — | `204` (soft delete → trash) |
| POST | `/documents/bulk-delete` | `{ ids: string[] }` | `{ deleted: number }` (soft) |
| POST | `/documents/{id}/restore` | — | `DocumentMeta` (un-trash) |
| POST | `/documents/bulk-restore` | `{ ids: string[] }` | `{ restored: number }` |
| DELETE | `/documents/{id}?permanent=true` | — | `204` (hard delete from trash) |
| POST | `/documents/trash/empty` | — | `{ purged: number }` |
| GET | `/documents/{id}/file` | — | `application/pdf` (original bytes; PDF.js fetches this) |
| GET | `/documents/{id}/thumbnail` | — | `image/png` |
`?deleted=false` (default) lists the active library; `?deleted=true` lists trash. Hard delete requires the explicit `permanent=true` flag so it can never happen by accident from the normal delete path.
`DocumentMeta`:
```jsonc
{ "id", "title", "originalFilename", "sizeBytes", "pageCount",
"createdAt", "updatedAt", "thumbnailUrl" }
```
### 10.3 Annotations (working state)
| Method | Path | Body | Returns |
|---|---|---|---|
| GET | `/documents/{id}/annotations` | — | `{ data: Annotation[], updatedAt }` |
| PUT | `/documents/{id}/annotations` | `{ data: Annotation[], baseUpdatedAt? }` | `{ updatedAt }` |
`baseUpdatedAt` (optional) lets the server warn on stale-tab overwrite (returns `409` with current state if provided and mismatched; client may force with a retry omitting it).
### 10.4 Assets
| Method | Path | Body | Returns |
|---|---|---|---|
| POST | `/documents/{id}/assets` | multipart `file` | `{ ref, url }` |
| GET | `/documents/{id}/assets/{ref}` | — | binary (image/png etc.) |
### 10.5 Versions
| Method | Path | Body | Returns |
|---|---|---|---|
| GET | `/documents/{id}/versions` | — | `{ items: VersionMeta[] }` |
| POST | `/documents/{id}/versions` | `{ label? }` | `VersionMeta` (201) |
| GET | `/documents/{id}/versions/{vid}` | — | `{ data: Annotation[], meta }` |
| POST | `/documents/{id}/versions/{vid}/restore` | — | `{ updatedAt }` |
| DELETE | `/documents/{id}/versions/{vid}` | — | `204` |
`VersionMeta`: `{ id, label, kind, createdAt, annotationCount }`.
### 10.6 Export
| Method | Path | Body | Returns |
|---|---|---|---|
| POST | `/documents/{id}/export` | `{ versionId?, flatten: true }` | `application/pdf` (synchronous; single-user scale) |
If export ever becomes slow for huge files, migrate to a job pattern (`202` + `GET /jobs/{id}`). The endpoint shape is designed so this is additive, not breaking.
### 10.7 Health
| Method | Path | Returns |
|---|---|---|
| GET | `/health` | `{ status: "ok", version }` |
### 10.8 OpenAPI is generated, not hand-maintained
FastAPI emits `/api/v1/openapi.json`. The frontend's typed API client and `types/` are generated from it (e.g. `openapi-typescript`). **Agents must regenerate types after any schema change** rather than hand-editing them. This keeps frontend and backend in lockstep.
---
## 11. Authentication & Security
- **Single password, no username.** Stored as Argon2id hash in `settings.password_hash`.
- **First-run setup:** if `setupRequired`, the UI shows a "set your password" screen before anything else. `/auth/setup` works only while no hash exists.
- **Session:** on login, issue a signed token (itsdangerous or JWT) in a cookie that is `httpOnly`, `Secure`, `SameSite=Lax`, with a sane expiry (e.g., 7 days, sliding). No token in localStorage (XSS-safe).
- **Login rate limiting:** exponential backoff / lockout after N failed attempts per IP (e.g., 5 attempts → 15-min lockout). In-memory counter is fine for single-user; document it.
- **CSRF:** because auth is cookie-based, protect state-changing routes. With `SameSite=Lax` plus a custom `X-Requested-With` header required on mutating requests (the SPA always sends it; cross-site form posts can't), CSRF is adequately mitigated for single-user. Document the reasoning.
- **Upload validation:** verify magic bytes (`%PDF-`), enforce a max size (config), and open with PyMuPDF in a guarded try/except to reject malformed/malicious files before storing. Never trust the client-supplied content-type or filename; sanitize filenames.
- **Path safety:** all file paths derive from server-generated UUIDs, never from user input. No user string ever becomes a filesystem path.
- **Secrets:** `SECRET_KEY`, cookie settings, max upload size, etc. come from environment variables (`.env`), never hardcoded.
- **Security headers** (set in nginx): `Content-Security-Policy` (restrict to self; allow the wasm/worker for PDF.js), `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`.
- **TLS** is terminated at the user's outer reverse proxy. **In production, all traffic — LAN included — goes through that HTTPS proxy**, so `COOKIE_SECURE=true` and the browser always sees HTTPS; the `Secure` cookie flag is honored. **Direct HTTP access to the published port is only for local development/testing**, where `COOKIE_SECURE=false` is set so the session cookie works over plain HTTP. This single env var is the only difference between the two modes; document both in `.env.example`.
---
## 12. Frontend Architecture
### 12.1 Pages
- **LoginPage** — password entry (and first-run setup variant).
- **HomePage** — three zones in a clean light layout:
- **Recently edited** — cards (thumbnail, title, edited-time), sorted by `updatedAt`.
- **Upload** — prominent button **and** full-page drag-and-drop dropzone with progress.
- **Library tab** — grid/list of all PDFs with multi-select, search, and delete (single + bulk). Selection mode reveals a delete action bar.
- **Trash view** — soft-deleted documents with **restore** (single + bulk) and **permanent delete** / **empty trash**. Shows days remaining before auto-purge.
- **EditorPage** — the canvas workspace.
### 12.2 Editor composition
- **PageStack** — renders each PDF page via PDF.js into a `