ADR-0009: Astro SSR + islands for web

Status: Accepted
Date: 2026-07-30
Supersedes: —
Superseded by: —

Context

Resolves the open question “Astro vs Vite SPA” from docs/architecture.md §7. ADR-0002 removed Next.js, leaving the web rendering strategy open.

Decision

Build the web app as Astro with SSR on Cloudflare Workers, using interactive islands only where genuinely needed — session logging, follow buttons, shelf controls.

Rationale

A Letterboxd-alike lives or dies on its game pages ranking in Google. Discovery and curated lists are content, not app chrome, and organic search is the only free acquisition channel this project has.

A client-rendered SPA shell forfeits that. Server rendering keeps every catalogue page, list page and profile crawlable.

Secondary benefit: Astro is also the docs subsite framework (ADR-0013), so the repo carries one web framework rather than two.

Consequences

The web app runs as a Worker, so it inherits the 10ms CPU per invocation ceiling. Page-level queries must be as lean as the API’s — this is the surface most at risk from the feed and discovery joins.
Islands are opt-in and must be justified. Defaulting a page to client rendering defeats the ADR.
Mobile (Expo) and web share packages/shared but not components. No cross-platform UI layer.

Alternatives considered

Vite SPA. Simplest mental model and closest to the Expo client’s patterns. Rejected on the SEO forfeit.

Astro static + client fetch. Cheapest to serve. Rejected: catalogue pages can’t be prerendered before the catalogue exists, so most of the SEO benefit evaporates while the complexity remains.