Remove the leftover file content layer and align the docs

This commit is contained in:
tleininger committed 2026-09-23 15:30:53 +02:00
1 parent 3fd3796d73
commit 47d9841532
21 files changed
+154 -327

No files matched your search

+42 -22
View File
@@ -2,12 +2,13 @@
Why the site is built the way it is. Read this before questioning one of these
decisions — each records the reasoning, not just the choice. Operational how-to
lives in `docs/deployment.md`; open work lives in `tasks/`.
lives in `docs/deployment.md`; open work lives in the Gitea issues (milestone
„Elternbeirat-Website").
> **Note on scope.** These decisions describe stage 1: a static information site
> with content as files. The move to editor-based content maintenance
> (`tasks/001-redaktion-ohne-entwickler.md`) deliberately revisits AE-2 and AE-3 —
> when that lands, update this file.
> **Note on scope.** The site started as a static information site with content
> as files (stage 1). Editorial maintenance without a developer then replaced
> that file layer with PocketBase, which revised **AE-2** and **AE-3** below —
> each now records both the original decision and why it changed.
## AE-1: Blazor with static server-side rendering, not WebAssembly
@@ -24,30 +25,49 @@ costs around 60 MB of RAM in the container.
(`@rendermode InteractiveServer` on exactly that one component), without changing the
architecture. Never global.
## AE-2: Content as files in the repo, not in a database
## AE-2: Content in PocketBase, read per request (revised)
**Decision:** Page content as Markdown with YAML frontmatter, events as structured
YAML (`Content/events.yml`), documents as PDF under `wwwroot`.
**Decision:** All visible content lives in **PocketBase** (collections `pages`,
`posts`, `events`, `faqs`); the app reads it over the REST API per request via a
typed `PocketBaseClient`. Documents remain PDFs under `wwwroot`.
**Rationale:** No DB backup, no migration schema, no consistency problems between
files and database. Changes are commits and are therefore traceable and reversible.
For a site with ~10 subpages and a few events per year, anything else is overhead.
**Original decision (stage 1):** Content as files in the repo — Markdown with YAML
frontmatter, events as `Content/events.yml`. The rationale then was: no DB backup,
no migration schema, no file/DB drift, and "backup = `git clone`". For a handful of
pages that was the leanest option.
**Consequence:** Text changes require a commit and a redeploy. With an expected five
changes a year that is acceptable — and the reason the editor expansion
(`tasks/001`) is treated as a separate stage.
**Why it changed:** The site needs to be maintainable by the board **without a
developer and without a redeploy**. Files meant every text fix was a commit and a
rebuild. PocketBase keeps the "small, self-hostable, one binary" spirit while
letting an editor change content live in its admin UI. It has **no** migration
schema of the EF/ORM kind — the collections are its data — so the objection that
weighed against "a database" in stage 1 does not apply here.
## AE-3: Content is baked into the image, not mounted as a volume
**Consequence:** Editing is now a task in the PocketBase admin, not a commit (see
`redaktion.md`). The app holds no content of its own; if PocketBase is unreachable a
page degrades to empty rather than failing. "Backup = `git clone`" no longer covers
the content — the backup is now `pb_data` (see AE-3 and `deployment.md`).
**Decision:** `Content/` and `wwwroot/` are part of the image.
## AE-3: Content lives in PocketBase's `pb_data`, not baked into the image (revised)
**Rationale:** Mounted content from the appdata share could be edited directly on the
NAS, but that is exactly when the repo and the live state drift apart — and the
"backup = `git clone`" property from AE-2 would be worthless.
**Decision:** The editable content lives in PocketBase's `pb_data`, a persistent
volume separate from the app image. Only the static assets under `wwwroot/` (CSS,
fonts, PDFs) are baked into the image.
**Consequence:** No quick fix on the live system. Typos are corrected properly via a
commit. Note: the content is read once at startup and cached — there is **no**
`FileSystemWatcher` (a change needs a restart / `dotnet watch`).
**Original decision (stage 1):** `Content/` and `wwwroot/` were both baked into the
image, deliberately **not** a mounted volume, so the live state could never drift
from the repo and "backup = `git clone`" held.
**Why it changed:** Editing content live (AE-2) is only possible if that content
survives a redeploy — so it must be a volume, not part of the image. The drift
concern is answered differently now: the content simply has one home (PocketBase),
and the repo no longer claims to hold it. The app image stays stateless and can be
rebuilt and redeployed at any time without touching the data.
**Consequence:** The backup is a copy of `pb_data` (plus a restore test), not a
`git clone` (set up in issue #9, see `deployment.md`). The app reads content per
request over HTTP, so there is nothing cached at startup and no `FileSystemWatcher`
— an editorial change is live immediately, no restart needed.
## AE-4: TLS and certificates exclusively in the Nginx Proxy Manager