History

Claude Opus 5 6377faf332 All checks were successful CI / Lint, typecheck, test (pull_request) Successful in 7m28s Details CI / Build container images (pull_request) Successful in 2m7s Details CI / Auth e2e pack (pull_request) Successful in 9m37s Details CI / Import/export fidelity gate (pull_request) Successful in 1m7s Details CD / Build and push images (push) Successful in 23s Details CD / Deploy to Test (push) Successful in 12s Details CD / Smoke tests against Test (push) Successful in 1m47s Details CD / Promote to Int (push) Successful in 16s Details CI / Lint, typecheck, test (push) Successful in 7m25s Details CI / Build container images (push) Has been skipped Details CI / Auth e2e pack (push) Successful in 9m41s Details CI / Import/export fidelity gate (push) Successful in 1m12s Details #306 : instance branding — logo and favicon, cropped in the browser An instance had no way to look like itself: the top bar said "Dorfteich" whatever the operator called their instance, `instance.name` was never rendered in the running app at all, and there was no favicon anywhere — `index.html` had no `<link rel="icon">` and `public/` held only fonts and theme-init.js. Where the line is drawn, and why: - The api never decodes an image. Cropping, scaling and the conversion to PNG happen on a canvas in the browser; the api checks the PNG signature, reads the IHDR dimensions at their fixed offsets and enforces the caps. An image library would put a decoder in front of attacker-supplied bytes AND would have to be carried through the `--network none` offline build. Reading two big-endian integers is not decoding. - SVG is refused, with its own error message rather than a generic "not a PNG": it can carry script, and serving it from our own origin would be a cross-site-scripting vector. An operator who tried one should learn that it is deliberate. - The crop is driven by number inputs, not by dragging. A drag-only cropper excludes keyboard and switch users outright; a number input is arrow-key operable and screen-reader readable without any custom aria. The resulting pixel size is stated in text, not only drawn as a frame. - The variant is chosen by CSS, not JavaScript. `theme-init.js` has already resolved `data-theme` before first paint, so the correct logo is the one painted rather than the one that appears after a flash. Without a dark variant the LIGHT logo carries both themes — the operator's own asset shown unchanged beats one they did not choose (the rule #307 extends to ponds). The settings screen warns; it never blocks. - The favicon link is static, its resource dynamic. index.html stays a static file and the api answers with the uploaded icon or a shipped default — that route must never 404, or the browser keeps its generic icon for good. The default is generated by a script from Node's own zlib (`gen-default-favicon.mjs`), for the same offline-build reason. - Both favicon sizes are uploaded together: one source, one crop, so the tab icon and the home-screen icon can never disagree. - Branding is served WITHOUT a session, because the login screen carries it and the browser fetches the favicon before anyone signs in. The admin screen says so — an operator may not expect their logo to be public. - The metadata is not writable through the settings endpoint: it describes bytes on disk, and hand-writing it would claim an asset that is not there. `./data/branding` follows the three-step rule #303 paid for: env default + `data-dirs.ts` entry, compose volume (repo AND the stages on ONE), and the `mkdir`/`chown` line in the api Dockerfile. `data-dirs.test.ts` is new and closes the hole that made #303's variant invisible: the nightly archive skips a missing directory WORDLESSLY, so the fence now demands that every `*_DIR` the backup env declares actually travels in the archive. Verified against the real defect — removing the line fails it by name. Audit catalogue v1.7 (`branding.changed`), carrying `scope` from the start so #307 is the same event with a different scope, not a second id. Verified: api suite 103 files green (a lone `public-api` ECONNRESET under local parallel load, green in isolation — the documented local flake); branding suite 12 tests against a real directory; crop arithmetic unit tests; a11y pack 11/11 in both schemes; /admin measured at 320px with the new section (overflow 0); and the whole flow walked in the browser: upload → crop 780×180 → stored as 512×118 → logo in the sidebar linking home with the instance name as its accessible name → topbar wordmark following `instance.name` → light logo still shown under `data-theme="dark"`.		2026-08-01 19:30:52 +02:00
..
adr	#303 : operator-uploaded fonts — storage, API, PDF embedding, backup	2026-08-01 14:49:13 +02:00
audit-events.md	#306 : instance branding — logo and favicon, cropped in the browser	2026-08-01 19:30:52 +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
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).