Xtablo — Go + HTMX Product

What This Is

A Go + HTMX version of Xtablo centered on tablos as collaborative workspaces. v1 established the authenticated Tablos workflow with tasks, files, worker, and deploy scaffolding; v2 added collaboration, messaging, etapes, events, planning, and Google sign-in; v3 replaces the minimal backend UI with a full design system that makes the product look like the existing JS app.

Built for a developer who wants a simpler, durable product stack: one Go server, Postgres, server-rendered UI, and no managed chat provider.

Core Value

A user can sign in and run the Tablos workflow — organize work, attach files, discuss, and plan scheduled events — without a JS framework or managed chat provider.

If everything else fails, this must work end-to-end on a single Go binary backed by Postgres and an S3-compatible bucket.

Current Milestone: v3.0 Design System & Visual Polish

Goal: Replace the minimal backend UI layer with a full design system ported from go-backend/internal/web/ui, then apply it to every surface using the JS app as the visual reference.

Target features:

Design system foundation: port CSS tokens and component library (button, input, card, badge, modal, select, textarea, table, empty-state) into backend/internal/web/ui
Auth pages (login/signup) restyled to match the JS product visual
Dashboard & Tablos (sidebar, tablo list, project cards) restyled
Tablo detail (tasks/kanban, etapes, files) restyled
Chat & Planning pages restyled

Requirements

Validated

✓ Server-managed sessions with email/password auth — Phase 2 (v1.0)
✓ Tablos CRUD with ownership — Phase 3 (v1.0)
✓ Tasks kanban with drag-and-drop reorder — Phase 4 (v1.0)
✓ File attachments with orphan cleanup worker — Phases 5–6 (v1.0)
✓ Single-binary production deploy with Caddy TLS — Phase 7 (v1.0)
✓ Google sign-in (server-managed sessions) — Phase 8 (v2.0)
✓ Etapes as one-level task wrappers — Phase 9 (v2.0)
✓ Tablo events with CRUD — Phase 10 (v2.0)
✓ Individual planning view (/planning) — Phase 11 (v2.0)
✓ Native per-tablo chat with real-time SSE — Phase 12 (v2.0)

Active

A full design system (tokens + component library) lives in backend/internal/web/ui and can be used by all templates
Auth pages look visually equivalent to the JS app (login/signup)
Dashboard and tablo list match the sidebar + project-card layout from the JS app
Tablo detail (tasks, etapes, files) matches the JS app's visual treatment
Chat and planning views have consistent, polished styling

Out of Scope

Managed chat/messaging providers — no Stream Chat, Ably, Pusher, Firebase Realtime Database, or equivalent for v2 chat
Stripe / billing — defer monetization until product loop is validated
Public booking widget — apps/external rewrite not in v1 (may return in a later milestone)
Client portal — apps/clients magic-link experience deferred
Admin app — apps/admin internal tooling deferred
Notes / rich documents inside a Tablo — not part of this milestone
Managed auth platforms — no Clerk/Auth0/Lucia; Google and Apple are identity providers only, with Xtablo still owning users and sessions
Mobile / Expo app — out of scope for this rewrite
Supabase as a runtime dependency — Postgres only; Supabase Auth / RLS replaced by Go-side authz
The existing go-backend/ directory — treated as scratch; new code lives in a fresh backend/ Go package

Context

The JS monorepo (this repository) is the source of truth for product behavior and is fully mapped in .planning/codebase/ (ARCHITECTURE, STACK, STRUCTURE, INTEGRATIONS, CONVENTIONS, CONCERNS, TESTING). Use these to derive expected behavior — but the rewrite is free to simplify both schema and visuals.
The DB schema will change during the rewrite — the JS version's Supabase schema is a reference, not a constraint. The user wants to be in the loop on schema decisions for each domain (users/sessions, tablos, tasks, files).
Visuals will also change — no requirement to mirror the existing UI; Tailwind + HTMX patterns drive the new look.
go-backend/ already contains real scaffolding (router, sqlc, air, tailwind input). It is not the foundation — a fresh backend/ package will be created.
Developer is comfortable in Go and wants a low-dependency, server-rendered stack going forward.
v2 shipped functional and plain UI for collaboration and planning. v3 is the visual pass that ports the richer design system and applies it across product surfaces.

Constraints

Tech stack: Go (server + templates) + HTMX + Tailwind + Postgres + sqlc — no JS framework, no managed BaaS
Auth: Server-managed sessions remain authoritative; Google/Apple sign-in may verify external ID tokens but must end by issuing Xtablo's own session cookie
Chat: No third-party chat provider; messages and read state live in Postgres, with real-time delivery handled by the Go app
Storage: Files in S3-compatible object storage (Cloudflare R2 to start)
Architecture: One web server binary + one background worker (same repo, possibly same binary with subcommand)
Deploy target: Single VPS / container — no Kubernetes
Planning: Events belong to tablos, but each individual user can access their own planning view
Etapes: One level only — a task can have at most one parent/wrapper, and a parent cannot itself have a parent
Scope discipline: v2 adds collaboration and planning only; billing, booking, portal, admin, notes, and mobile remain deferred

Key Decisions

Decision	Rationale	Outcome
Rewrite in Go + HTMX (no SPA)	Simpler stack, developer preference, product pivot	✓ Validated through v1-v2
Built-in sessions, no 3rd-party auth	Avoid vendor coupling; sessions are well-trodden ground	✓ Validated through email/password and Google sign-in
Drop Supabase (keep Postgres)	Owning the auth + RLS story in Go is simpler than maintaining the boundary	✓ Validated through owned authz queries
Fresh `backend/` Go package, set `go-backend/` aside	Existing scaffold has decisions to revisit; cleaner to start over	✓ Validated
v1 = Tablos workflow only (Tasks + Files), defer chat/billing/booking/portal/admin	Focus the rewrite around the load-bearing user loop first	✓ Completed
Single binary + background worker, single VPS deploy	Matches the "simpler stack" thesis; avoid orchestration cost early	✓ Validated for current deploy target
User-in-the-loop on Postgres schema for each domain	Schema is changing from JS version; explicit review before sqlc generation	— Pending
v2 chat is native, not vendor-backed	User explicitly does not want third-party chat; Postgres + Go should be enough for the first real-time version	✓ Validated with SSE receive + HTMX POST send
Google/Apple are identity providers only	Preserve server-owned users/sessions while allowing social sign-in	✓ Google validated; Apple disabled for now
Etapes are one-level wrappers around tasks	Matches the requested mental model and avoids recursive planning complexity	✓ Validated
Planning is individual, events remain tablo-scoped	Lets users see their schedule while preserving tablos as the source of work context	✓ Validated

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

Requirements invalidated? → Move to Out of Scope with reason
Requirements validated? → Move to Validated with phase reference
New requirements emerged? → Add to Active
Decisions to log? → Add to Key Decisions
"What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

Full review of all sections
Core Value check — still the right priority?
Audit Out of Scope — reasons still valid?
Update Context with current state

Phase History

Phase 1: Foundation — Completed 2026-05-14. Fresh backend/ Go package boots a web server, renders an HTMX-driven base layout, connects to local Postgres with goose migrations. FOUND-01..FOUND-05 satisfied; user-approved manual walkthrough. Two inline justfile/tailwind fixes during UAT (commit fix(01): guard sqlc on empty queries and correct tailwind paths).
Phase 7: deploy-v1 — Completed 2026-05-15. Multi-stage Dockerfile (assets→builder→distroless nonroot), docker-compose.prod.yaml with 4 services (postgres/web/worker/caddy), Caddyfile with {$DOMAIN} TLS, README runbook covering first-deploy/rollback/incident. DEPLOY-01..DEPLOY-05 satisfied. 3 UAT items (Docker build, compose config, live smoke test) pending on a Docker-equipped machine.
Milestone v2.0 started: Collaboration, planning, and social sign-in — Started 2026-05-15. Scope: native per-tablo chat, one-level etapes, Google/Apple sign-in, and individual planning with tablo events.
Milestone v2.0 shipped: Collaboration, planning, and social sign-in — Shipped 2026-05-16. Delivered Google sign-in, etapes, events, individual planning, and native SSE-backed tablo discussions. Closed with 7 acknowledged deferred artifact items; see .planning/milestones/v2.0-MILESTONE-AUDIT.md.

Last updated: 2026-05-16 — Phase 16 complete (tablo detail restyled with design system components)

9.5 KiB Raw Blame History Unescape Escape