rdbms-playground/docs/adr/0042-public-website-and-documentation-site.md

ADR-0042: Public website and documentation site

Status

Accepted (2026-06-04). Implementation plan: docs/plans/20260604-adr-0042-website.md.

Context

RDBMS Playground is nearing its first public release and needs a public website that does two jobs: attract — a landing page that shows the playground in action — and document — a thorough, canonical reference for everything the playground can do.

The documentation-heavy surface is already implemented and verified (full simple- and advanced-mode command set, the ten-type vocabulary, relationships, constraints, indexes, EXPLAIN, undo/history/replay, projects, export/import, the teaching echo, clipboard, friendly errors, tab completion and syntax highlighting; 2151 tests passing at the time of writing). The site is therefore largely a presentation-and-writing effort, not a wait-for-features one. A grounded inventory of what is shippable now lives in the implementation plan.

Several choices here had no canonical default; they were settled during a planning + /runda pass with the user and are recorded below.

Decision

1. Stack — Astro 6 + Starlight + Tailwind v4. Astro's content-first, zero-JS-by-default model with the Starlight docs theme fits a marketing-landing-plus-heavy-docs site better than the alternative considered, SvelteKit + Tailwind (the usual go-to here). Interactive pieces are added as Astro islands (Svelte or vanilla), so Svelte is still available where it earns its place. Tailwind v4 is wired via the official @tailwindcss/vite plugin; the @astrojs/starlight-tailwind plugin bridges Tailwind with Starlight's theming.

2. Demo medium — asciinema. Showcase sequences are recorded as asciinema .cast files (text-based, small, faithful to the full alternate-screen render) and embedded with asciinema-player. The same casts are reused inline in the docs — one recording format serves both the landing page and documentation enrichment. Recordings are produced by a scripted-input driver that types commands into a real PTY with viewer-friendly pacing; the app's own history.log replay (ADR-0034) re-executes commands without typing animation or pacing and is therefore suitable only for state-deterministic docs snippets, not the hero demo.

3. In-page WASM playground — deferred (OOS: deferred, not rejected). A live, type-it-yourself playground compiled from the Rust app to WebAssembly is desirable but is a multi-week sub-project, so it does not block the site. The demo section is designed with a stable seam (a single Demo component contract) so a WASM playground island can replace the asciinema player later with no change to call sites. Recorded boundary for that future work:

   • Portable core (runs on wasm32-unknown-unknown largely as-is): src/dsl/* (parser, types, grammar, walker), the pure App::update(), ui.rs, theme.rs, friendly/*, output rendering; an in-memory DB path already exists (Connection::open_in_memory()). rusqlite compiles to the browser target via its ffi-sqlite-wasm-rs feature.
   • Native edge needing cfg-gated browser replacements: the multi-thread Tokio runtime + the dedicated DB worker thread (ADR-0010) → current-thread/in-line async; crossterm terminal + event-stream → a browser backend (e.g. Ratzilla's DOM/Canvas) + DOM events; arboard, zip, file persistence (ADR-0015), file logging; and the rusqlite backup-API undo (ADR-0006) → a SQL dump/restore. When taken up, this becomes its own ADR + iteration plan.

4. Hosting — portable static build; Vercel is the likely target. Astro 6 builds to static HTML/CSS with no adapter, so the output deploys equally to Vercel, Cloudflare Pages, Netlify, or GitHub Pages. We avoid coupling to any one host. No CI yet — the site is tested locally (pnpm dev / pnpm build) until the repo reaches its public home.

5. Repo topology — monorepo. The site lives under website/ in the playground repo; the crate stays at the repo root. The repo as a whole moves to its public home later; site and crate travel together.

6. Canonical docs home — the website. User-facing documentation lives on the site. In-repo docs/ keeps ADRs, handoffs, and development notes; docs/simple-mode-limitations.md (requirement DOC1) was a development aid and now feeds the site's content rather than competing with it. The sharing recipes promised by requirement E2 become a docs page.

7. Documentation scope and conventions. Document the full supported feature set. Any capability not yet fully implemented (a small minority — e.g. multi-line input, query cancellation, seed, m:n convenience, ER-diagram export, the show tables/relationships/indexes family) is either omitted or carries a clear "planned / not yet available" callout — never presented as shipped. Two wording rules bind all user-facing copy:

   • No engine name (SQLite/STRICT/rusqlite/PRAGMA) — continues the user-facing posture of ADR-0002; copy says "the database"/"the engine".
   • No "DSL" — it is internal jargon. The two input modes are simple mode (the playground's keyword command language) and advanced mode (SQL).

8. Install documentation — two mechanisms. The install page documents prebuilt release binaries (self-hosted download — not GitHub Releases, since the repo will move) and package managers. Both can be written now against the planned mechanisms; concrete download URLs slot in at release. (Distribution items D1–D3 in requirements.md remain the tracking home for the release tooling itself.)

Consequences

• The site can ship on the strength of already-implemented features; it is gated on writing and recording, not on finishing the app.
• One recording format (asciinema .cast) serves both marketing and docs, and is reusable as the app evolves (re-run the script, re-record).
• The WASM playground is preserved as a real future option without holding up launch; the demo seam keeps the upgrade cheap.
• A single canonical docs home removes the divergence risk of maintaining user docs in two places.
• Website build choices (Decisions 1, 2, 4, 5) are recorded here for traceability but do not, by themselves, warrant further ADRs; only app-architecture decisions (notably the future WASM port) will.

Out of scope

• In-page WASM playground — deferred (see Decision 3); revisit as its own ADR + iteration plan.
• Hosted/SaaS playground or a server-backed doc CMS — rejected: a static site fully satisfies the need, consistent with ADR-0007's no-hosted-publishing stance. Revisit only if real demand emerges.