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 UI can stay functional and plain; the user will provide a more polished visual design later. The milestone should focus on working behavior and clean integration points.

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	— Pending
Built-in sessions, no 3rd-party auth	Avoid vendor coupling; sessions are well-trodden ground	— Pending
Drop Supabase (keep Postgres)	Owning the auth + RLS story in Go is simpler than maintaining the boundary	— Pending
Fresh `backend/` Go package, set `go-backend/` aside	Existing scaffold has decisions to revisit; cleaner to start over	— Pending
v1 = Tablos workflow only (Tasks + Files), defer chat/billing/booking/portal/admin	Focus the rewrite around the load-bearing user loop first	— Pending
Single binary + background worker, single VPS deploy	Matches the "simpler stack" thesis; avoid orchestration cost early	— Pending
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	— Pending
Google/Apple are identity providers only	Preserve server-owned users/sessions while allowing social sign-in	— Pending
Etapes are one-level wrappers around tasks	Matches the requested mental model and avoids recursive planning complexity	— Pending
Planning is individual, events remain tablo-scoped	Lets users see their schedule while preserving tablos as the source of work context	— Pending

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.

Last updated: 2026-05-16 after starting milestone v3.0

9 KiB Raw Blame History Unescape Escape