life-docs/features/scheduling.md

Feature — Scheduling (Time Blocks, Daily Plans, Calendar)

Daily scheduling with time blocks, morning/evening assessments, and calendar views. Powers the /today timeline and /calendar page.

---

Schema

time_blocks

Column	Type	Constraints	Description
id	uuid	PK
domain_id	uuid	FK → domains.id, nullable	Associated domain
task_id	uuid	FK → tasks.id, nullable	Linked task
habit_id	uuid	FK → habits.id, nullable	Linked habit
title	varchar(255)	NOT NULL
date	date	NOT NULL
start_time	time	NOT NULL
end_time	time	NOT NULL
block_type	varchar(20)	NOT NULL	work, personal, health, break, transit
status	varchar(20)	NOT NULL, default 'planned'	planned, in_progress, completed, skipped, rescheduled
notes	text

Indexes: date, domain_id, (date, start_time)

daily_plans

Column	Type	Constraints	Description
id	uuid	PK
date	date	UNIQUE, NOT NULL	One per day
energy_level	varchar(10)		high, medium, low
focus_domains	uuid[]	default '{}'	Domain IDs to focus on
morning_intention	text
evening_reflection	text
mood_morning	integer		1-5
mood_evening	integer		1-5

Indexes: date (unique)

---

API

Time Blocks

Method	Endpoint	Description
GET	/api/scheduling/time-blocks	List (?date=, ?startDate=&endDate=, ?domainId=)
POST	/api/scheduling/time-blocks	Create block
PATCH	/api/scheduling/time-blocks/:id	Update block
POST	/api/scheduling/time-blocks/:id/reorder	Move block ({ startTime, endTime })
DELETE	/api/scheduling/time-blocks/:id	Delete block

Daily Plans

Method	Endpoint	Description
GET	/api/scheduling/daily-plan/:date	Get or initialize plan for date (returns with time blocks)
PUT	/api/scheduling/daily-plan/:date	Upsert plan ({ energyLevel, focusDomains, morningIntention, moodMorning })
PATCH	/api/scheduling/daily-plan/:date/reflection	Update evening reflection ({ eveningReflection, moodEvening })

---

Backend Module

SchedulingModule — imports DomainsModule, TasksModule, HabitsModule.

• Daily plan uses upsert pattern (one per day)
• Time blocks can link to tasks or habits (optional foreign keys)
• No domain events emitted
• No cron jobs
• Break reminders are client-side (localStorage Pomodoro timer)

---

Frontend

Routes

• /calendar — Week and month calendar views
• /today — Timeline section (time blocks for today)

Calendar Page Components

• CalendarHeader — navigation arrows, date range label, view toggle (week/month)
• WeekView — 7 day columns, hourly grid (06:00-22:00), time block cards positioned by start/end
• MonthView — day cells with mini colored block indicators
• NowIndicator — red horizontal line at current time
• ColorLegend — domain color → name mapping
• CreateTimeBlockModal — domain, title, date, time range, block type, task linker

Today Page Components

• MorningAssessmentCard — energy selector, mood rating, focus domain picker, intention input
• TimeBlockTimeline — vertical timeline with NowIndicator, domain-colored blocks
• EveningReflectionCard — appears after 18:00, mood rating + reflection textarea

Data

// Calendar
const { data: timeBlocks } = useTimeBlocks({ startDate, endDate });
const createBlock = useCreateTimeBlock();
const updateBlock = useUpdateTimeBlock();

// Daily plan
const updatePlan = useUpdateDailyPlan();
const updateReflection = useUpdateReflection();

Key Interactions

Calendar:

• Click empty slot → create time block (pre-fills date + time from position)
• Drag block vertically → change time (same day)
• Drag block horizontally → change day
• Resize bottom edge → change end time (min 15 min)
• Click day in month view → switch to week view for that week

Daily plan:

• Energy/mood/focus save immediately on change
• Energy selection re-filters task list on /today
• Evening reflection section appears after 18:00 local time

Visual rules:

• Block height proportional to duration
• Domain color as block background (transparent)
• Break blocks: grey, dashed border
• Today column: subtle background highlight
• Overlapping blocks: side-by-side within column

---

Implementation Phase

Phase 2 (Core Features) — SchedulingModule, /calendar page, /today timeline + morning assessment.