arthur/xtablo-source
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 5

docs: define v1 requirements

Browse source
This commit is contained in:
Arthur Belleville 2026-05-14 16:27:20 +02:00
parent 39c7608851
commit b46d314a35
No known key found for this signature in database
1 changed files with 133 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

133
.planning/REQUIREMENTS.md Normal file
View file

@ -0,0 +1,133 @@
# 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*