docs: add landing-page + doc-reconciliation build spec
Workstream A: public /welcome landing page (bubbletea aesthetic, one Dex login flow, logged-in shortcuts) — with the oidc.go facts verified against main, incl. the two corrections that only surface from reading the code (logout must redirect to /welcome not /auth/login; bare-/ vs deep-link redirect split). Workstream B: reconcile the guardrail docs against deployed reality (v0.4.0) — auth.go comments, data-model isolation status + migrations 002-006 schema, architecture web surface, use-case scenarios for the Stage-1 features, ADR ordering, and a requirements-vs-shipped deviation check. Structured as two parallel workstreams so the doc audit isn't done cursorily alongside the build.
This commit is contained in:
mathias
@@ -0,0 +1,153 @@
|
|||||||
|
# Spec — Landing page + documentation reconciliation
|
||||||
|
|
||||||
|
**Date:** 2026-06-03
|
||||||
|
**Status:** Ready to build
|
||||||
|
**Scope:** Two parallel workstreams — (A) a public landing page; (B) reconciling the
|
||||||
|
requirements / use-case / architecture / data-model docs against the deployed reality
|
||||||
|
(v0.4.0). These are separate concerns; do not let one worker do both, or the audit gets
|
||||||
|
done cursorily.
|
||||||
|
|
||||||
|
All work: read `CLAUDE.md` + `DECISIONS.md` first. TBD — commit directly to `main`, one
|
||||||
|
logical change per commit, conventional commits, `task check` green before every commit.
|
||||||
|
After editing any `.templ`, run `templ generate` (the repo commits both `views.templ` and the
|
||||||
|
generated `views_templ.go`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workstream A — Public landing page
|
||||||
|
|
||||||
|
### Goal
|
||||||
|
A public landing page at `/welcome`, in the established bubbletea aesthetic, that lets a
|
||||||
|
visitor sign in (one Dex flow) and, if already logged in, jump to their Tapir page or log out.
|
||||||
|
New public transport surface only — no engine/core change (ADR-003).
|
||||||
|
|
||||||
|
### Verified facts (read from `internal/web/oidc/oidc.go` @ main — do not re-guess)
|
||||||
|
- Auth endpoints are exactly `/auth/login`, `/auth/callback`, `/auth/logout`.
|
||||||
|
- `isPublicPath(p)` = `p == "/healthz" || strings.HasPrefix(p, "/auth/")` — the single
|
||||||
|
public-route chokepoint inside `DexAuth.Middleware`.
|
||||||
|
- `DexAuth.CurrentUser(r) (web.User, bool)` reads the session cookie and does NOT redirect —
|
||||||
|
this is the "peek" the landing page uses to branch logged-in vs logged-out.
|
||||||
|
- `handleCallback` redirects to `/` on success (correct — leave as-is).
|
||||||
|
- `handleLogout` currently redirects to `loginPath` (`/auth/login`) — this is wrong for this
|
||||||
|
feature (see A3).
|
||||||
|
- There is NO separate "sign up" against Dex/OIDC: one authorization flow. Registration is
|
||||||
|
Tapir's own `/register` step (ADR-012), reached after first login for an unknown subject.
|
||||||
|
|
||||||
|
### Tasks
|
||||||
|
**A1 — make `/welcome` public.** In `oidc.go`, extend `isPublicPath`:
|
||||||
|
```go
|
||||||
|
func isPublicPath(p string) bool {
|
||||||
|
return p == "/healthz" || p == "/welcome" || strings.HasPrefix(p, "/auth/")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**A2 — unauthenticated bare-`/` → `/welcome`; deep links unchanged.** In `DexAuth.Middleware`,
|
||||||
|
the unauthenticated branch currently always calls `redirectToLogin`. Change it so that when
|
||||||
|
`r.URL.Path == "/"` an unauthenticated visitor is redirected to `/welcome`; for any other
|
||||||
|
guarded path keep `redirectToLogin` (so a shared `/v/{id}` deep link still bounces through Dex
|
||||||
|
and returns to the destination). Keep the `isPublicPath` check first (redirect-loop guard).
|
||||||
|
|
||||||
|
**A3 — logout lands on `/welcome`, not login.** In `handleLogout`, change the final redirect
|
||||||
|
from `loginPath` to `/welcome`. As written it sends the user to `/auth/login`, which
|
||||||
|
immediately starts a fresh Dex login — visibly failing to log out. This intentionally breaks
|
||||||
|
the existing logout test (oidc_test.go) which asserts redirect to `/auth/login`; update that
|
||||||
|
test to expect `/welcome`. That break is expected, not a regression.
|
||||||
|
|
||||||
|
**A4 — mount the landing handler** in `internal/web/handlers.go` `Router()`, on `root`,
|
||||||
|
OUTSIDE `Auth.Middleware`, alongside `/healthz`:
|
||||||
|
```go
|
||||||
|
root.HandleFunc("GET /welcome", a.handleWelcome)
|
||||||
|
```
|
||||||
|
`handleWelcome` peeks `a.Auth.CurrentUser(r)` and renders `WelcomePage(user, ok)`. Not behind
|
||||||
|
`Auth.Middleware` or `registrationGate`.
|
||||||
|
|
||||||
|
**A5 — `WelcomePage` templ component** in `views.templ`. Reuse the existing shared
|
||||||
|
layout/header partial and the established aesthetic (#7653FC purple rounded ╭─╮╰─╯ box, pink
|
||||||
|
tapir mascot, #0EF9B6 mint accents) — match the existing pages, do not reinvent styling.
|
||||||
|
- Logged out (`ok == false`): tapir mascot + tagline; one primary CTA **"Get Started"** →
|
||||||
|
`/auth/login`; honest sub-text: "New here? You'll set up your account right after signing in
|
||||||
|
— returning users go straight through." One button only (see verified facts: no separate
|
||||||
|
Dex sign-up; two buttons to the same URL would mislead).
|
||||||
|
- Logged in (`ok == true`): "Go to my Tapir" → `/`; "Log Out" → `/auth/logout`. May greet via
|
||||||
|
`user.Email`.
|
||||||
|
|
||||||
|
**A6 — tests** (extend `handlers_test.go` patterns). Note `StubAuth.CurrentUser` always returns
|
||||||
|
true; for the logged-out case use a fake Auth returning `(web.User{}, false)`.
|
||||||
|
- `GET /welcome`, no session → "Get Started" → `/auth/login`.
|
||||||
|
- `GET /welcome`, with session → "Go to my Tapir" + "Log Out".
|
||||||
|
- Unauthenticated `GET /` → 302 `/welcome`.
|
||||||
|
- Unauthenticated `GET /v/{id}` → still 302 `/auth/login` (deep link preserved).
|
||||||
|
- Authenticated `GET /` → still serves the list, unchanged.
|
||||||
|
- oidc: `handleLogout` → 302 `/welcome` (update the existing test).
|
||||||
|
|
||||||
|
**A out of scope:** no Dex config change, no new auth/session logic, no sign-up backend.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workstream B — Documentation reconciliation
|
||||||
|
|
||||||
|
### Why
|
||||||
|
The guardrail docs were written before Stage 1 and the web surface. Several now describe the
|
||||||
|
opposite of the deployed reality (v0.4.0). Stale guardrail docs are worse than none — a future
|
||||||
|
cold session (human or agent) trusts them. This workstream brings requirements, use cases,
|
||||||
|
architecture, and data-model back in sync with `main`. Each fix is one commit; cite the ADR or
|
||||||
|
migration that is the source of truth.
|
||||||
|
|
||||||
|
### Known drift to fix (verified this session — not exhaustive; the worker confirms against code)
|
||||||
|
**B1 — `internal/web/auth.go` comments.** The `User.Subject` doc and package doc still say
|
||||||
|
"single-user allowlist (ADR-011)" / "Stage-0". Code is multi-user (ADR-012). Update the
|
||||||
|
comments to describe the current multi-user reality; reference ADR-012.
|
||||||
|
|
||||||
|
**B2 — `docs/data-model.md` isolation status.** It says isolation enforcement is "dormant at
|
||||||
|
Stage 0". It is now LIVE: Postgres RLS, `FORCE`d on all user-owned tables, with a passing
|
||||||
|
two-user isolation test (ADR-012, migration 003). Rewrite that section to describe enforced
|
||||||
|
RLS as the current state; keep the history honest (was dormant at Stage 0, enforced from
|
||||||
|
Stage 1).
|
||||||
|
|
||||||
|
**B3 — `docs/data-model.md` schema completeness.** The doc predates migrations 002–006. Add
|
||||||
|
the entities/columns that now exist: `summary_actions` (002), RLS (003), `user_identities`
|
||||||
|
(004, dex_subject→user_id), `video_connections` (005), `users.auto_summarize` +
|
||||||
|
`videos.summarize_requested` (006). The ER section should match the live schema. Cross-check
|
||||||
|
against `internal/adapters/store/migrations/*.up.sql` — those are ground truth.
|
||||||
|
|
||||||
|
**B4 — `docs/architecture/architecture.md`.** Predates the entire web surface. Update the C4
|
||||||
|
container diagram and text to include: `tapir serve` (HTMX+Templ web reader/writer), the Dex
|
||||||
|
OIDC session layer (`internal/web/oidc`), registration gate, web-initiated YouTube connect,
|
||||||
|
account management, and the immediate-processing path (web "Summarize" button → background
|
||||||
|
goroutine → status poll). The engine/ports/sinks core is unchanged (ADR-003) — show the web
|
||||||
|
surface as a new transport over the same core, not a core change.
|
||||||
|
|
||||||
|
**B5 — `docs/use-cases/*.feature`.** Add scenarios for the behaviours now live and unspecced:
|
||||||
|
register (new subject → registration → user row; returning user straight through), connect
|
||||||
|
YouTube (web OAuth), disconnect, delete-account (cascade + secret purge, Dex untouched —
|
||||||
|
ADR-013), manual-vs-auto summarize mode + the Summarize button, and the landing page
|
||||||
|
(logged-out CTA; logged-in shortcuts). Keep them as executable-style Gherkin consistent with
|
||||||
|
the existing files.
|
||||||
|
|
||||||
|
**B6 — `DECISIONS.md` ADR ordering (cosmetic).** ADR-010 sits before ADR-009/011 (append
|
||||||
|
order). Reorder to numeric while you're in the file. Pure tidy, no content change.
|
||||||
|
|
||||||
|
**B7 — requirements check.** If a requirements doc exists (e.g. `docs/ui-spec.md`, referenced
|
||||||
|
by ADR-011), reconcile it with what shipped: note where the build deviated (e.g. the spinner /
|
||||||
|
immediate processing / summarize mode were beyond the original spec) so the spec reflects
|
||||||
|
reality or explicitly records the deviation. Do not silently rewrite history — record
|
||||||
|
deviations as deviations.
|
||||||
|
|
||||||
|
### B working method
|
||||||
|
- Source of truth order: migrations + code > ADRs > prose docs. When a prose doc disagrees
|
||||||
|
with code, the code wins and the doc is corrected (unless the code is the bug — then flag it,
|
||||||
|
don't quietly doc around it).
|
||||||
|
- One logical doc per commit. Cite the ADR/migration that justifies each change in the commit
|
||||||
|
body.
|
||||||
|
- This is an audit, not a rewrite: preserve the docs' structure and the "rejected alternatives
|
||||||
|
/ history" honesty. The goal is *current and trustworthy*, not *pretty*.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Coordination
|
||||||
|
A and B touch mostly different files (A: oidc.go, handlers.go, views.templ, tests; B: docs/* +
|
||||||
|
auth.go comments). The one overlap is `auth.go` (B1 edits comments) vs A (reads it) — no
|
||||||
|
conflict. Run A and B in parallel; commit independently to `main`.
|
||||||
|
|
||||||
|
If anything in B reveals that code, not docs, is wrong (e.g. an isolation gap, a migration that
|
||||||
|
doesn't match the data-model intent), STOP and surface it — that's a finding, not a doc edit.
|
||||||
Reference in New Issue
Block a user