Phase 11: Individual Planning - Context

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

## Phase Boundary

Phase 11 delivers a protected personal planning page at /planning for each authenticated user. The page aggregates that user's scheduled events across accessible tablos, presents them as a chronological agenda, and links each event back to its tablo context. This phase does not add new event creation/editing semantics beyond using the Phase 10 event model and tablo Events tab.

## Implementation Decisions

D-01: /planning defaults to an upcoming agenda view rather than a week or month calendar.
D-02: The default agenda range is the next 14 days starting from today.
D-03: Navigation uses fixed 14-day windows with Today, previous-window, and next-window controls.
D-04: Past events are not shown by default, but users can reach past events intentionally through previous-window navigation.
D-05: Keep the first planning view focused on agenda browsing. Do not recreate the Phase 10 tablo Events month calendar on the personal planning page.

Agenda Row Content

D-06: The agenda renders as a single continuous chronological list, not grouped by day or by tablo.
D-07: Each event row shows time, title, tablo context, and location when present.
D-08: Do not show description snippets in the first planning agenda rows; avoid noisy/tall rows.
D-09: Tablo context appears as the tablo title plus a small color dot using tablo_color when present.
D-10: Events without an end time display the start time only. Do not add "no end" copy or infer a default duration.

the agent's Discretion

Exact route handler names, template names, query parameter names, and HTMX fragment boundaries are planner discretion if they preserve the decisions above and match existing Go/HTMX patterns.
Exact empty-state wording is planner discretion, but it must be functional and plain.
Exact date label formatting is planner discretion, but the list must remain chronological and easy to scan.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Product Scope

.planning/ROADMAP.md - Phase 11 goal, MVP mode, success criteria, and user-in-loop decision about today/upcoming versus week navigation.
.planning/REQUIREMENTS.md - PLAN-01 through PLAN-04 and Phase 11 traceability.
.planning/PROJECT.md - v2 constraints: Go + HTMX, individual planning, plain functional UI, and no JS framework.

Event Handoff

.planning/phases/10-events/10-CONTEXT.md - Event date/time semantics, planning handoff decisions, and deep-link expectations.
.planning/phases/10-events/10-03-SUMMARY.md - User-scoped event range query and navigation/prefill behavior delivered for planning.
.planning/phases/10-events/10-04-SUMMARY.md - Final Phase 10 verification and browser UAT approval.
.planning/phases/10-events/10-VERIFICATION.md - Evidence that EVENT-01..05 and planning handoff query passed.

Go Backend Entry Points

backend/internal/db/queries/events.sql - ListUserEventsRange query returns event fields plus tablo_title and tablo_color filtered by tablos.user_id.
backend/internal/web/router.go - Protected route group and static route ordering pattern where /planning should mount.
backend/internal/web/handlers_events.go - Event date/month parsing and event ownership conventions to reuse where relevant.
backend/templates/events_forms.go - Event date/time formatting helpers and EventTimeRange behavior for no-end-time display.
backend/templates/layout.templ - Authenticated shell and navigation integration point.
backend/templates/tablos.templ - Existing server-rendered page/tab patterns and plain UI style.
backend/internal/web/handlers_events_test.go - DB-backed event aggregation, ordering, ownership, and formatting tests to mirror for planning.

Historical TypeScript Reference

apps/main/src/pages/planning.tsx - Old planning page reference for possible agenda concepts only; do not recreate its imports/exports/month/week/day complexity in Phase 11.
packages/shared-types/src/events.types.ts - Historical EventAndTablo shape for reference only.

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

ListUserEventsRange already provides the core data needed for /planning: event date/time fields, title, location, description, tablo_id, tablo_title, and tablo_color.
templates.FormatEventDate, templates.FormatEventTime, and templates.EventTimeRange provide event formatting behavior that keeps Phase 11 consistent with Phase 10.
Existing Layout templates provide the authenticated page shell; /planning should be a normal protected page, not a tablo tab.
Existing ui.Button and form/error helpers are enough for a plain toolbar with Today/previous/next navigation.

Established Patterns

Protected pages live inside the auth.RequireAuth route group and get the authenticated user from context.
SQLC query files are canonical; generated Go files are reproduced by just generate and should not be hand-edited.
DB-backed web tests use setupTestDB, preInsertUser, session cookies, and the full router to prove auth and query behavior.
User-scoped aggregation must filter by tablos.user_id, not by trusting event IDs or client-supplied tablo IDs.
Non-HTMX full-page behavior should work for primary pages; HTMX can be used for navigation fragments if the planner chooses.

Integration Points

Add a /planning route in the protected router group.
Add a planning handler/dependency shape using sqlc.Queries.
Add a planning template rendering the 14-day agenda, toolbar, empty state, and event rows.
Use ListUserEventsRange with a calculated start/end date based on query params or defaults.
Add handler tests for unauthenticated redirect, owned-only aggregation, chronological ordering, navigation links, empty state, and event links back to tablo context.

</code_context>

## Specific Ideas

The first personal planning page should feel like an agenda, not another calendar.
Default to the next 14 days from today.
Keep rows compact: time, event title, tablo title/color, and location if present.
Event links should carry users back to the tablo context; Phase 10 established /tablos/{id}/events?month=YYYY-MM as the planning deep-link shape.

## Deferred Ideas

Week and month planning views.
Date picker navigation.
Grouped-by-day or grouped-by-tablo planning layouts.
Description snippets in agenda rows.
ICS import/export, external calendar sync, and recurrence.

Phase: 11-Individual Planning Context gathered: 2026-05-16

6.7 KiB Raw Blame History