generated from bisco/codex-bootstrap
bisco
57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
# 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.
|