xtablo-source/CONTEXT.md

Xtablo

The Go + HTMX backend that powers the Tablos workflow — a server-rendered, single-binary product replacing the original TypeScript monorepo (apps/).

Language

My Tasks: A cross-Tablo view showing all Tasks assigned to the current User across all their Tablos. The Task equivalent of Planning (which does the same for Events). Avoid: Task inbox, assigned tasks

Planning: The user-scoped calendar view that aggregates Events across all Tablos the user owns. Shows month, week, and day perspectives. Not a Tablo-level concept — it is the user's personal schedule. Avoid: Calendar, schedule, agenda

File: A file attachment belonging to a Tablo, stored in object storage (Cloudflare R2). Scoped to the Tablo only — not attachable to individual Tasks or Etapes. Immutable once uploaded. Avoid: Attachment, document, asset

Chat: The per-Tablo real-time message thread where members exchange messages. Each Tablo has exactly one Chat. Implemented via discussion_messages in the DB — "discussion" is the table name only; the domain term is Chat. Avoid: Discussion, thread, messaging

Event: A scheduled calendar entry (meeting, appointment, deadline) belonging to a Tablo. Carries a date, start time, and optional end time. Not linked to Tasks. Avoid: Meeting, appointment, reminder

Task: A unit of work within a Tablo, carrying a status (todo, in_progress, in_review, done), an optional priority (high, medium, low), an optional assignee, and an optional date range (start + due). Displayed in three views: Kanban, List, and Roadmap. Currently only the Tablo owner can be assigned; multi-member assignment becomes meaningful once collaborative Tablos land. Avoid: Todo, card, item, ticket

Kanban: The default board view of Tasks in a Tablo, organized into columns by status (todo, in_progress, in_review, done). One of three task views alongside List and Roadmap. Avoid: Board (use "Kanban" when naming the view; "Board" is a tab label only)

List View: A table layout of all Tasks in a Tablo, grouped by status, with columns for task name, assignee(s), due date, and priority. One of three task views alongside Kanban and Roadmap. Avoid: Grid view, table view

Roadmap: A timeline view of Tasks in a Tablo, placing each task as a bar spanning its start-to-due date range. One of three task views alongside Kanban and List. Avoid: Gantt, Gantt chart, timeline view

Etape: A named grouping of tasks within a Tablo, used to organize work into stages. Has no lifecycle or status of its own — it is a container only. Avoid: Stage (use "Etape" in code and UI; "stage" is the English gloss only), sprint, milestone, phase

User: A person with a Xtablo account, authenticated via email/password or Google. The only identity concept in the current backend. Users will eventually belong to Organizations for management and billing purposes — but Tablos remain User-owned regardless. Avoid: Member, Account, Owner

Organization: A management and billing grouping of Users. Deferred — not present in the current backend. Tablos are owned by Users, not Organizations. Avoid: Team, Workspace, Company

Tablo: A project workspace that belongs to one owner. The primary organizing unit of all work in Xtablo. Carries a lifecycle status (active or archived) and a derived progress value. Collaborative membership is deferred — the current backend supports single-owner only. Avoid: Project, workspace, board

Tablo Progress: A derived read-only value: the percentage of a Tablo's Tasks that are in done status. Not stored — computed on the fly. Displayed as a progress bar in the UI. Avoid: Completion rate, score

Relationships

• A Tablo belongs to exactly one User (current backend; multi-member model is a future concern)
• A Tablo contains zero or more Etapes
• A Task optionally belongs to one Etape; an Etape has no status of its own
• A Task has its own date range (start + due) — not inherited from its Etape or from Events
• Events and Tasks are independent; an Event is not linked to a Task
• A Tablo has exactly one Chat (the message thread is implicit, not a separate entity to create)
• A File belongs to a Tablo directly — not to a Task or Etape
• Planning aggregates Events from all Tablos a User owns into a single personal calendar
• The Tablo Calendar tab shows the same Events scoped to one Tablo; Planning is the cross-Tablo view of the same data

Example dialogue

Dev: "When a User opens their Planning, do we show Events from archived Tablos?" Domain expert: "No — Planning only shows Events from active Tablos."

Dev: "Should Tablo Progress count Tasks inside an Etape differently?" Domain expert: "No — all Tasks count equally. An Etape is just a container, it doesn't affect the progress calculation."

Dev: "Can I assign a Task to someone who isn't the Tablo owner?" Domain expert: "Not yet — until collaborative Tablos land, the only valid assignee is the owner."

Flagged ambiguities

• "Gantt" appears in the Figma/screenshot tab label — resolved: the canonical term is Roadmap.
• "Not Started" appears as a status group label in the list view — resolved: it is the display label for the todo status, not a separate status value.
• "Discussion" appears in DB table names (discussion_messages) — resolved: the domain term is Chat; "discussion" is an implementation artifact.