xtablo-source/.planning/REQUIREMENTS.md

Requirements: Xtablo Go+HTMX Rewrite

Defined: 2026-05-14 Core Value: A user can sign in and run the Tablos workflow — create tablos, manage their tasks (kanban), and attach files — without a JS framework.

v1 Requirements

Requirements for the initial Go+HTMX milestone. Each maps to exactly one roadmap phase.

Foundation

• FOUND-01: Fresh backend/ Go package with module init, cmd/web and cmd/worker entrypoints, and a runnable HTTP server returning /healthz
• FOUND-02: Postgres connection pool with env-driven config and a versioned migration tool (e.g. goose or migrate) wired into a justfile/Makefile
• FOUND-03: HTMX + Tailwind + templ rendering pipeline producing a base layout with a working dev loop (template hot-reload, CSS rebuild)
• FOUND-04: Structured logging, request ID middleware, and graceful shutdown on the web server
• FOUND-05: .env.example, local Postgres via compose.yaml, and a justfile documenting dev, migrate, test, lint

Authentication

• AUTH-01: User can sign up with email and password (server-side validation, bcrypt/argon2 hash)
• AUTH-02: User can log in with email and password and receives a server-managed session
• AUTH-03: Sessions persist via HTTP-only, signed cookies (Secure + SameSite=Lax) and survive browser refresh
• AUTH-04: User can log out from any authenticated page (server invalidates session)
• AUTH-05: Protected routes redirect unauthenticated requests to the login page; authenticated users on auth pages are sent to the dashboard
• AUTH-06: CSRF protection on all state-changing requests
• AUTH-07: Rate-limited login attempts per email + IP to discourage credential stuffing

Tablos

• TABLO-01: Authenticated user can list their tablos on the dashboard (newest first)
• TABLO-02: User can create a tablo with at minimum a title (and optional description)
• TABLO-03: User can view a single tablo's detail page (only owners can view in v1)
• TABLO-04: User can edit a tablo's title and description
• TABLO-05: User can delete a tablo (soft delete or hard delete; user-in-loop on schema decision)
• TABLO-06: All tablo mutations are HTMX-driven (no full page reloads for CRUD actions)

Tasks (Kanban)

• TASK-01: Each tablo has a kanban board with named columns (e.g. To do / Doing / Done; configurable in v1 or fixed — user-in-loop on schema)
• TASK-02: User can create a task inside a column with a title
• TASK-03: User can edit a task's title and description
• TASK-04: User can move a task between columns (HTMX + drag-and-drop or button-based reorder, decided in plan-phase)
• TASK-05: User can reorder tasks within a column
• TASK-06: User can delete a task
• TASK-07: Task ordering persists across refreshes

Files

• FILE-01: User can upload a file (with size limit) to a tablo; metadata stored in Postgres, bytes stored in S3-compatible storage (R2)
• FILE-02: Uploads use direct-to-S3 presigned PUT URLs OR server-proxied upload (decided in plan-phase)
• FILE-03: User can list files attached to a tablo with original filename and size
• FILE-04: User can download a file via a signed time-limited URL
• FILE-05: User can delete an attached file (removes both DB row and S3 object)
• FILE-06: Authorization checks ensure only the tablo owner can upload/list/download/delete

Worker

• WORK-01: cmd/worker binary connects to the same Postgres and runs a job queue (e.g. river, asynq, or a hand-rolled pg_notify queue — decided in plan-phase)
• WORK-02: At least one real job runs end-to-end (e.g. periodic signed-URL prewarm OR scheduled file-orphan cleanup) to prove the wiring
• WORK-03: Worker has structured logging and graceful shutdown matching the web binary
• WORK-04: Failed jobs are retried with backoff and visible in a simple admin/CLI surface

Deploy

• DEPLOY-01: Both binaries build into a single multi-stage Docker image (or two stages from one Dockerfile)
• DEPLOY-02: Image runs on a single VPS / Cloud Run-style host with env-injected config (no Supabase, no GCP Secret Manager required for v1)
• DEPLOY-03: Migrations run on deploy (entrypoint or pre-deploy step) without manual intervention
• DEPLOY-04: Health checks (/healthz, /readyz) and structured logs that a basic uptime monitor can consume
• DEPLOY-05: A documented runbook in backend/README.md covers local dev, deploy, and rollback

v2 Requirements

Acknowledged, not in current roadmap.

Booking

• BOOK-01: Public embeddable booking widget (port of apps/external)
• BOOK-02: Event types + availabilities backend

Client Portal

• CLIENT-01: Magic-link client portal (port of apps/clients)

Admin

• ADMIN-01: Internal admin tooling (port of apps/admin)

Tablo Sub-features

• TABLO-NOTES: Rich notes inside a tablo
• TABLO-ETAPES: Etapes / roadmap sections inside a tablo
• TABLO-EVENTS: Calendar events tied to a tablo

Communication & Billing

• CHAT-01: Real-time discussion inside a tablo (replacement for Stream Chat)
• BILL-01: Stripe subscriptions + entitlement gating

Out of Scope

Feature	Reason
Third-party auth (Clerk, Auth0, Lucia)	Explicit "no 3rd party" decision — built-in sessions only
Supabase as runtime dependency	Drop the BaaS; Postgres only
React / SPA frontend	Whole point of the rewrite is HTMX + server templates
Stream Chat / Durable Object chat	Complexity not justified for v1; possibly revisited as a Go-native version
Mobile / Expo app	Web rewrite first; mobile not in scope
Existing go-backend/ directory as foundation	Set aside; fresh backend/ package
Full feature parity with JS app before cutover	Leaner-by-design — v2 milestones add back what's worth keeping
Kubernetes / multi-node deployment	Single VPS/container target only

Traceability

Populated during roadmap creation in Step 8.

Requirement	Phase	Status
FOUND-01..05	Phase 1	Pending
AUTH-01..07	Phase 2	Pending
TABLO-01..06	Phase 3	Pending
TASK-01..07	Phase 4	Pending
FILE-01..06	Phase 5	Pending
WORK-01..04	Phase 6	Pending
DEPLOY-01..05	Phase 7	Pending

Coverage:

• v1 requirements: 40 total
• Mapped to phases: 40
• Unmapped: 0 ✓

---

Requirements defined: 2026-05-14 Last updated: 2026-05-14 after initial definition