Astro Pages & Islands

The frontend is Astro pages that ship mostly static HTML and hydrate small React islands only where interactivity is needed (constitution §7.11, §8.2).

The diagram below shows how the pages, the prerendered shell, and the islands relate to the offline layer and the Worker.

flowchart LR
  Index["index.astro<br/>(landing)"]
  AppRoute["app/index.astro<br/>(workspace)"]
  Auth["sign-in / sign-up.astro<br/>(Clerk UI)"]
  ApiCatch["api/[...path].ts<br/>(Hono delegate)"]
  Shell["AppShell.astro<br/>(prerendered shell)"]
  Islands["src/islands<br/>(React, client:*)"]
  Dexie[("Dexie cache<br/>(IndexedDB)")]
  Worker{{"Hono Worker<br/>(createApp().fetch)"}}

  AppRoute --> Shell
  Shell -->|hydrates| Islands
  Islands -->|liveQuery| Dexie
  ApiCatch --> Worker
  Islands -->|"/api"| ApiCatch
  Auth --> Worker
  Index --> AppRoute

Pages & layout

• src/pages/index.astro — marketing/landing entry.
• src/pages/app/ — the authenticated app routes (the workspace).
• src/pages/sign-in.astro / sign-up.astro — Clerk prebuilt auth UI (ADR-010).
• src/pages/api/ — the catch-all that delegates to the Hono Worker app ([...path].ts → createApp().fetch).
• src/layouts/AppShell.astro — the prerendered application shell that the service worker precaches for offline launch (ADR-009, constitution §7.14.2).

Islands model

Interactive components live in src/islands and hydrate via client:* directives; everything else is static Astro output. This keeps the client JS budget small (§8.2): only the strings/components a route uses ship, and the offline layer (SW, Dexie, i18n catalogs) loads without blocking first paint.

The sequence below traces a workspace route load from static HTML through island hydration to the first liveQuery subscription.

sequenceDiagram
  participant Browser
  participant Shell as AppShell.astro
  participant Island as src/islands
  participant Dexie as Dexie cache
  Browser->>Shell: request app/index.astro
  Shell-->>Browser: prerendered HTML (precached by SW)
  Browser->>Island: hydrate (client:*)
  Island->>Dexie: liveQuery subscribe
  Dexie-->>Island: reconciled data
  Island-->>Browser: interactive UI

Related: Mobile Shell & Navigation, Client Sync & Steps Islands, Worker API & Clerk Auth (the /api delegate).