xtablo-source/.planning/PROJECT.md

# 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

<!-- Shipped and confirmed valuable. -->

- ✓ 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

<!-- v3.0 hypotheses. See REQUIREMENTS.md for the canonical list with REQ-IDs. -->

- [ ] 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
- [x] Chat and planning views have consistent, polished styling — Phase 17

### Out of Scope

<!-- Explicit boundaries. -->

- **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`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd-complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. 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-17 — Phase 17 complete (discussion view and planning page restyled with design system components; IsOwn bubble alignment, day separators, HTMX tab fix, discussion max-height with auto-scroll)*