History

Claude Opus 5 3310ae3926 All checks were successful CI / Lint, typecheck, test (pull_request) Successful in 7m19s Details CI / Build container images (pull_request) Successful in 1m23s Details CI / Auth e2e pack (pull_request) Successful in 8m55s Details CI / Import/export fidelity gate (pull_request) Successful in 57s Details CD / Build and push images (push) Successful in 14s Details CD / Deploy to Test (push) Successful in 16s Details CD / Smoke tests against Test (push) Successful in 1m28s Details CD / Promote to Int (push) Successful in 13s Details CI / Lint, typecheck, test (push) Successful in 6m52s Details CI / Build container images (push) Has been skipped Details CI / Auth e2e pack (push) Successful in 9m6s Details CI / Import/export fidelity gate (push) Successful in 58s Details #305 : a full pond archive before deletion and before purge Deleting a pond already had a strict prompt — typing the pond name, stricter than a confirm dialog. That was never the gap. The gap is that the person who deletes it loses access the moment they do: the pond leaves their view, only a Site Admin can bring it back, and the export is no longer reachable for them. So the archive is offered INSIDE the deletion flow, before the button. What it contains, and why it is not the existing export: - Every page the requester may read, as Markdown, as before. - Every attachment of the pond, not only the embedded ones. An attachment nobody put on a page would otherwise vanish unnoticed — which is the whole reason this issue exists. - `manifest.json`: pond settings (EFFECTIVE, defaults filled in — a preservation format must not require its reader to know Dorfteich's defaults), labels, the page hierarchy and sort keys, comments, and attachment metadata including the #199 hash so a reader can verify bytes. It extends the #210 manifest rather than adding a second descriptor, and carries an explicit `formatVersion`. - `README.txt`, because the manifest is for machines: whoever unpacks a folder of Markdown a year from now must not believe they hold a one-click restore. Decisions worth naming: - "Complete" describes the RESULT, not the route. A pond admin who may read every page gets `complete: true`; only an archive that actually leaves pages out is incomplete. The Site-Admin route skips the read filter (an archive taken before an irreversible purge must not depend on which ponds the operator happens to be a member of) — those are two different questions and the first version of this conflated them. - The omission is named before the download, with its number, in the UI and in the manifest. An archive silently missing content is worse than no archive, because it ends the search. - Not downloading stays allowed. A pond of test pages should not require one, and the server cannot tell whether a file arrived anyway — so the finality is stated in text instead of enforced. - A plain link, not fetch-into-a-blob. The api streams the ZIP; buffering a whole pond in the tab to draw a progress bar would trade memory for cosmetics. The browser reports progress and completion; what it cannot say — that the archive is being BUILT — is announced in a live region. - Read trail unchanged in kind (ADR 0023): one `export` event per classified page before any classified byte enters the stream. Attachments never travel without their page, so the same events cover them. - New audit action `pond.archived` (catalogue v1.7) with page and attachment counts, omitted pages, and completeness. Format documented in `docs/architecture/pond-archive-format.md`, including what is deliberately NOT in it (history, permissions, trash). Verified by hand, not only asserted: a real pond's archive downloaded and unpacked — README, manifest, three page files, the media file; the manifest's effective settings, per-page classification, the VS-NfD frontmatter and marking preserved in the classified page's Markdown, and the attachment's sha256 present. Plus six api tests (including that an unembedded attachment travels and that a Site Admin gets a complete archive without membership) and the a11y pack 11/11 in both schemes, which now also scans the pond settings screen. Not done, because there is nothing to attach it to: the Site Admin's purge dialog (#193) exists only as an api endpoint — there is no pond-trash UI in the web app. The api half is here and tested, so it becomes a link when that screen is built.		2026-08-01 20:24:35 +02:00
..
adr	#303 : operator-uploaded fonts — storage, API, PDF embedding, backup	2026-08-01 14:49:13 +02:00
audit-events.md	#305 : a full pond archive before deletion and before purge	2026-08-01 20:24:35 +02:00
data-model.md	#217 : map IdP groups and roles onto the permission model	2026-07-31 13:09:11 +02:00
deployment.md	Re-align the stage tables after the path change	2026-07-14 12:53:11 +02:00
operations.md	#288 : reset schema before pg_restore — partitioned tables broke --clean	2026-07-31 17:00:05 +02:00
permissions.md	#217 : map IdP groups and roles onto the permission model	2026-07-31 13:09:11 +02:00
plugin-architecture.md	#232 : plugin allowlist with SHA-256 hash pinning	2026-07-31 21:26:36 +02:00
pond-archive-format.md	#305 : a full pond archive before deletion and before purge	2026-08-01 20:24:35 +02:00
README.md	docs: ADR 0017 — Barrierefreiheit als Standard-Anforderung	2026-07-21 17:17:26 +02:00
realtime-collaboration.md	Scaffold pnpm monorepo with lint, format, and test tooling	2026-07-04 19:06:27 +02:00
roadmap.md	Add M13 to the roadmap	2026-07-14 16:37:24 +02:00
security.md	#306 : instance branding — logo and favicon, cropped in the browser	2026-08-01 19:30:52 +02:00

README.md

Dorfteich — Architecture Overview

This directory is the authoritative architecture documentation. Every implementation story references the documents here; when a story and this documentation disagree, clarify before coding.

System context

Dorfteich is shipped as a set of Docker containers behind a reverse proxy. One deployment = one instance (e.g. dorfteich.online, or a self-hosted installation).

flowchart LR
    subgraph clients [Clients]
        B[Browser SPA<br/>React + TipTap + Yjs]
    end
    subgraph instance [Dorfteich instance - Docker Compose]
        RP[Reverse proxy]
        WEB[web<br/>static SPA assets]
        API[api<br/>NestJS REST]
        COLLAB[collab<br/>Hocuspocus WebSocket]
        PG[(PostgreSQL)]
        PAN[pandoc-server<br/>doc conversion]
        GOT[Gotenberg<br/>HTML to PDF]
        VOL[/uploads + plugins volume/]
    end
    B -- HTTPS --> RP
    RP --> WEB
    RP -- /api --> API
    RP -- /collab WebSocket --> COLLAB
    API --> PG
    COLLAB --> PG
    API --> PAN
    API --> GOT
    API --> VOL
    COLLAB -. permission checks .-> API

web serves the single-page application (static assets).
api owns all business logic: auth, ponds, pages, labels, permissions, quotas, import/export, plugin management, admin functions.
collab synchronizes CRDT documents (page content) and awareness (cursors) over WebSocket and persists document state to PostgreSQL. It authenticates clients with short-lived tokens issued by api.
pandoc-server and Gotenberg are internal-only conversion sidecars (Word/OpenOffice import/export, PDF export).
All page content lives in PostgreSQL; binary uploads (images, attachments) and installed plugins live on a Docker volume.

Documents

Architecture Decision Records (`adr/`)

ADR	Decision
0001	TypeScript everywhere, pnpm monorepo
0002	PostgreSQL as the only database
0003	Yjs CRDT + Hocuspocus for real-time and offline collaboration
0004	TipTap (ProseMirror) as the WYSIWYG editor
0005	React + Vite single-page application
0006	NestJS + Prisma for the API server
0007	Cookie sessions, Argon2id, OIDC-ready identity model
0008	Sandboxed iframe plugins with a message-based API
0009	Pandoc + Gotenberg sidecars for import/export
0010	PostgreSQL full-text search behind a search interface
0011	Filesystem volume for uploads, DB-tracked quotas
0012	i18next with German and English from the start
0013	Page version history via Yjs snapshots, soft-delete trash
0014	CI/CD with Gitea Actions, staged promotion
0015	Nightly pg_dump + uploads sync, 30-day retention, off-host mirror
0016	Self-hosted Google Fonts, per-pond font configuration
0017	Accessibility (WCAG 2.1 AA) as a default requirement

Concept documents

Document	Contents
data-model.md	Entities and relations: users, ponds, pages, labels, grants, quotas, plugins
permissions.md	Role model and the "most specific setting wins" resolution algorithm
realtime-collaboration.md	CRDT document lifecycle, cursor sync, offline behavior, versioning hooks
plugin-architecture.md	Plugin manifest, packaging, sandbox runtime, extension points, admin flows
deployment.md	Compose stacks for Dev/Test/Int/Prod, environments, promotion pipeline
operations.md	Monitoring, logging, backup/restore, update strategy for self-hosters
security.md	Threat-driven security concept: authn/authz, sandboxing, uploads, secrets
roadmap.md	Epics and milestones; the order stories are implemented in

Terminology

German (product vision)	English (code, docs, issues)
Teich	pond
Seite	page
Teich-Admin	Pond Admin
Bearbeitende	Editor
Lesende	Reader
Öffentlichkeit	Public

Conventions for implementers

Language: English for code, comments, commit messages, and issues.
Write clear, human-readable code; document the "why", not the "what".
UI strings never appear hard-coded — always through i18n resources (see ADR 0012), with German and English translations added in the same change.
Every story lists the ADRs it depends on; read them before starting.
Every API route declares its access rule explicitly (a permission decorator, @Public(), or the Site-Admin guard — issue #52); permission checks run only through the shared resolution (permissions.md), never ad hoc. 404/403 policy: a denied read answers 404 so the existence of ponds and pages is not revealed; a denied write on something the user may read answers 403. Trash views require write capability and answer 404 on denial (ADR 0013).