docs: define v1 requirements
This commit is contained in:
Arthur Belleville
parent
39c7608851
commit
b46d314a35
1 changed files with 133 additions and 0 deletions
133
.planning/REQUIREMENTS.md
Normal file
133
.planning/REQUIREMENTS.md
Normal 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*
|
||||
Loading…
Reference in a new issue