# Phase 10: Events - Context

**Gathered:** 2026-05-16
**Status:** Ready for planning

<domain>
## Phase Boundary

Phase 10 delivers scheduled events attached to tablos. Users can create, edit, delete, and browse events inside a tablo with the same authorization expectations as tasks, files, and etapes. The first UI is a functional Events tab with a simple month calendar, not a polished calendar product. Phase 10 should also expose enough query surface for Phase 11 to build an individual planning page without reworking the event model.

</domain>

<decisions>
## Implementation Decisions

### Time Model
- **D-01:** Use local date/time semantics in the first version; do not add timezone selection or timezone conversion UI.
- **D-02:** Event start date and start time are required.
- **D-03:** End time is optional and same-day only.
- **D-04:** If an event has no end time, display only the start time. Do not infer or store a default duration.
- **D-05:** Store event time as separate `event_date`, `start_time`, and nullable `end_time` columns. Do not use `timestamptz` for Phase 10 event scheduling.

### Events Tab Shape
- **D-06:** Add an `Events` tab to the existing tablo detail tabs beside Overview, Tasks, and Files.
- **D-07:** The first Events tab view is a simple month grid.
- **D-08:** Include previous/next month navigation.
- **D-09:** Users can create events from both a general `New event` button and by clicking a day cell with that date prefilled.
- **D-10:** Day cells show event titles only, not start times.
- **D-11:** When a day has more events than fit cleanly, show the first few titles plus a `+N more` indicator.

### Create/Edit Flow
- **D-12:** Render create/edit forms inline inside the Events tab using HTMX fragments.
- **D-13:** The form fields are: required title, date, start time; optional end time, description, and location.
- **D-14:** Clicking an event title in the calendar opens the inline edit form.
- **D-15:** Create, edit, and delete operations refresh the whole Events tab/calendar rather than only one day cell.

### Event Lifecycle
- **D-16:** Delete is hard delete after confirmation. Do not add `deleted_at`, archive, cancel, or restore semantics in Phase 10.
- **D-17:** Past events remain visible when browsing past months.
- **D-18:** Events within a day are ordered by start time ascending, then title.
- **D-19:** Do not add a special empty state beyond the calendar and the `New event` action.

### Phase 11 Handoff
- **D-20:** Phase 10 should include a user-scoped query surface for events across tablos the authenticated user can access, even if Phase 10 only renders tablo-local events.
- **D-21:** Planning links should target the tablo Events tab with month query params, e.g. `/tablos/{id}/events?month=YYYY-MM`.
- **D-22:** User-scoped event rows should include event fields plus tablo title and tablo color.
- **D-23:** User-scoped query surface should support date-range filtering so Phase 11 can implement planning navigation cleanly.

### the agent's Discretion
- Exact route names, query names, and HTMX fragment boundaries are planner discretion if they preserve the decisions above and match existing local patterns.
- Exact calendar CSS and mobile layout are planner discretion; the result should remain functional and restrained until the user supplies a richer UI later.
- Exact validation copy is planner discretion, but it must clearly explain that an end time must be after the start time when provided.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Product Scope
- `.planning/ROADMAP.md` - Phase 10 goal, MVP mode, success criteria, and user-in-loop checkpoint.
- `.planning/REQUIREMENTS.md` - EVENT-01 through EVENT-05 and Phase 11 PLAN requirements that depend on event aggregation.
- `.planning/PROJECT.md` - v2 constraints: Go + HTMX, Postgres, plain functional UI, events belong to tablos, planning is individual.

### Prior Phase Patterns
- `.planning/phases/09-etapes/09-CONTEXT.md` - Recent tablo-scoped child-resource decisions, Tasks tab integration, and HTMX fragment patterns.
- `.planning/phases/09-etapes/09-04-SUMMARY.md` - Most recent UAT lessons around HTMX tab refreshes and filter/form precedence.

### Go Backend Entry Points
- `backend/migrations/0003_tablos.sql` - Current `tablos` ownership model and FK target.
- `backend/migrations/0007_etapes.sql` - Recent example of adding a tablo-owned child table and indices.
- `backend/internal/db/queries/tablos.sql` - Existing owner-scoped tablo query shape.
- `backend/internal/db/queries/tasks.sql` - Existing tablo-scoped list/create/update/delete query style.
- `backend/templates/tablos.templ` - Current tab navigation and tab fragment integration point for adding Events.
- `backend/internal/web/router.go` - Protected route mounting order and static-before-parametric route pattern.
- `backend/internal/web/handlers_tablos.go` - Tablo detail/tab handlers and `loadOwnedTablo` authorization pattern.
- `backend/internal/web/handlers_tasks.go` - Task child-resource create/update/delete patterns to mirror for events.
- `backend/internal/web/handlers_etapes.go` - Recent full-tab refresh pattern for child-resource mutations.
- `backend/internal/web/handlers_tasks_test.go` - DB-backed authorization and HTMX regression testing style.

### Historical TypeScript Reference
- `packages/tablo-views/src/TabloEventsSection.tsx` - Old product reference for event display, upcoming filtering, and empty-state wording; use as reference only, not a visual contract.
- `packages/shared-types/src/events.types.ts` - Old event domain type names and event-with-tablo shape.
- `packages/shared-types/src/database.types.ts` - Old schema had `start_date`, `start_time`, `end_time`, `created_by`, and `deleted_at`; Phase 10 intentionally keeps date/time split but chooses hard delete and no `deleted_at`.
- `apps/main/src/hooks/events.ts` - Old event query/mutation surface and aggregation ideas; use as behavior reference only.
- `apps/main/src/pages/planning.tsx` - Old planning page reference for why Phase 10 should expose user-scoped date-range queries.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `TabloDetailPage` already renders tab navigation with HTMX links targeting `#tab-content`; Events should follow the same tab pattern.
- `TasksTabFragment` and `FilesTabFragment` show the current pattern for standalone tab fragments returned by HTMX tab routes.
- `loadOwnedTablo` and existing child-resource handlers enforce ownership through the parent tablo and return 404 for inaccessible resources.
- `ui.Button`, `ui.Card`, and existing form field/error patterns are enough for the first functional Events UI.

### Established Patterns
- Tablo-owned resources mount under `/tablos/{id}/...` protected by `auth.RequireAuth`.
- Static child routes are declared before parametric child routes in `router.go`.
- SQLC query files are canonical; generated Go files are reproduced by `just generate` and not hand-edited.
- Mutations that affect a whole tab can return the full tab fragment for reliability.
- DB-backed tests use `setupTestDB`, `newTaskTestRouter`/similar router helpers, session cookies, and CSRF tokens.
- Unauthorized access to resources owned by another user's tablo should return 404 rather than 403.

### Integration Points
- Add a migration after `0007_etapes.sql` for a tablo-owned `events` table.
- Add `backend/internal/db/queries/events.sql` with tablo-scoped CRUD, month/date-range list queries, and user-scoped aggregation query including tablo title/color.
- Add event dependencies to `web.NewRouter` similarly to `TasksDeps`, `EtapesDeps`, and `FilesDeps`.
- Extend `TabloDetailPage` with an Events tab and render Events tab content when active.
- Add event handlers and templates under the existing `backend/internal/web` and `backend/templates` patterns.
- Add tests proving owner-only read/create/update/delete and end-time validation.

</code_context>

<specifics>
## Specific Ideas

- The Events tab should be a simple month calendar grid, not an agenda list.
- Day-cell clicks should prefill the create form date.
- Event titles are enough inside calendar cells for Phase 10.
- Planning deep links should preserve month context with `?month=YYYY-MM`.

</specifics>

<deferred>
## Deferred Ideas

- Timezone selection or conversion.
- Multi-day events.
- Date-only/all-day events.
- Event colors, categories, archive/cancel states, or soft-delete restore flows.
- Week/day calendar views.
- Rich day-detail panels.
- Full individual planning UI; Phase 11 owns that screen.

</deferred>

---

*Phase: 10-Events*
*Context gathered: 2026-05-16*
