feat: build headless theatre laboratory website

2026-06-22 19:42:43 +02:00
parent cae9180bc6
commit cff9a17c3c
65 changed files with 8994 additions and 128 deletions
@@ -0,0 +1,56 @@
+# ADR-0001: Headless Wagtail with an Astro frontend
+
+Date: 2026-06-22
+
+Status: Accepted
+
+## Context
+
+The theatre workshop needs an editorially polished public single page whose core
+content can be updated without code changes. The required stack is Wagtail/Django,
+Astro, PostgreSQL, and Docker Compose. A small team must be able to run and maintain
+the system locally without unnecessary services.
+
+## Decision
+
+Use Wagtail as a headless CMS backed by PostgreSQL and Astro as the public frontend.
+Wagtail owns uploaded media and exposes a read-only aggregate endpoint at
+`/api/site/home/`. Astro renders the page server-side in development/build time and
+uses curated Italian fallback content when the CMS is temporarily unavailable.
+Docker Compose runs PostgreSQL, Django, and Astro on one private default network.
+
+The content model uses one Wagtail `HomePage` with three ordered feature cards, site
+settings, and reusable snippets for teacher details, lesson details, shows, and gallery
+items. This keeps editing simple and avoids a custom frontend state layer.
+
+## Consequences
+
+- Editors use the authenticated Wagtail admin while the public API remains read-only.
+- The public page needs only one API request and degrades gracefully during CMS outages.
+- Uploaded media and PostgreSQL data require separate persistent volumes and backups.
+- Local frontend rendering depends on container networking; browser-facing media URLs
+  are generated from the configured public Wagtail base URL.
+
+## Alternatives considered
+
+- Calling the standard Wagtail endpoints separately was rejected because it adds
+  frontend orchestration for a single page.
+- Embedding the frontend in Django templates was rejected because Astro is required.
+- A JavaScript SPA and client-side state library were rejected as unnecessary.
+
+## Security impact
+
+The aggregate endpoint exposes published editorial content only. Wagtail admin keeps
+its normal authentication and CSRF protections. Services bind to loopback for local
+development, containers are not privileged, and secrets are supplied through the
+environment.
+
+## Operational impact
+
+Operators must back up the PostgreSQL and media volumes. CMS schema changes require
+normal Django migrations. Health checks order local startup.
+
+## Rollback
+
+Revert the feature commit and remove the Compose volumes only if their stored content
+is no longer needed. Keep database and media backups when rolling back code alone.