Local Calendar & Events
Relevant source files
The following files were used as context for generating this wiki page:
The Local Calendar & Events system manages household schedules, recurring series, and individual occurrences. It provides a web-based interface for viewing schedules in multiple formats and allows members to track events either as a household or individually. The system supports complex recurrence rules, iCalendar (ICS) exports, and multi-timezone handling for timed events.
Sources: GLOSSARY.md:1-25, internal/app/calendar.go:15-30
Data Architecture
The calendar system relies on a relational schema that separates integrations, calendar sources, and the events themselves. A "Local" integration is built-in by default to handle events created directly within GoCasa.
Database Schema
The core entities include integrations, source_calendars, and events.
The system distinguishes between timed events (stored with UTC timestamps and IANA timezone IDs) and all-day events (stored as YYYY-MM-DD strings).
Sources: internal/db/migrations/0004_local_calendar.sql:1-55
Event Management
The system manages both single events and complex recurring series. A Series is a recurring event defined by a repeat rule (RRULE), while an Occurrence is a specific instance of that series.
Recurrence and Scoping
When you edit a recurring event, you must select an Edit Scope:
- This event: Creates a "One-off edit" (exception) for a single occurrence.
- This and following: Splits the series, ending the current one and starting a new series from the selected date.
- All events: Updates the master series definition (limited to title, location, description, and members).
Sources: GLOSSARY.md:27-45, internal/app/calendar.go:340-350, internal/web/calendar_templ.go:320-330
Key Data Structures
| Structure | Description | File Reference |
|---|---|---|
calendarEvent | Internal representation of an event or occurrence used for rendering logic. | calendar.go:73-83 |
EventForm | Field mapping for the event creation/edit dialog. | calendar_templ.go:56-72 |
CalendarPage | Data structure for rendering the main calendar views. | calendar_templ.go:44-54 |
Calendar Views
The application provides four primary viewing modes to display events.
Month*: Shows a standard grid; days outside the current month appear faded.
- Week: Displays 7 days starting from Sunday (or preferred start day).
- Day: Detailed view of a single date.
- Agenda: A chronological list of upcoming events for the next 30 days.
Sources: internal/app/calendar.go:59-71, internal/app/calendar.go:85-150, internal/web/calendar_templ.go:126-210
iCalendar (ICS) Export
The system generates iCalendar feeds for external subscription. It uses the go-ical library to encode events into RFC 5545 compliant data.
- Endpoint:
/calendar.ics - Functionality: Maps internal SQL rows to
VTIMEZONEandVEVENTcomponents. - Series Handling: Exports the master series with its
RRULE. - Exception Handling: One-off edits are exported using the
RECURRENCE-IDproperty to override specific instances in the series.
Sources: internal/app/ics.go:20-60, internal/app/ics.go:107-130
Technical Implementation Details
Date and Time Handling
The system uses specific layouts for parsing and formatting:
dateLayout("2006-01-02"): Used for all-day events and URL parameters.localLayout("2006-01-02T15:04"): Matches the HTML<input type="datetime-local">format.
When you save a timed event, the application converts the input to a UTC Unix timestamp based on the provided IANA timezone. It explicitly refuses times that fall within a "Spring Forward" DST gap.
Sources: internal/app/calendar.go:18-42, internal/app/calendar_test.go:180-195
Live Updates
The calendar page includes a JavaScript-based live update mechanism.
- It establishes a connection to
/events/streamusing a nativeEventSource. - When a message is received, it triggers an asynchronous
fetchfor the current URL. - It extracts the
#liveregion from the response and replaces the current DOM element to update the UI without a full page reload.
Sources: internal/web/calendar_templ.go:217-245
Conclusion
The Local Calendar & Events module provides a robust framework for household scheduling. By leveraging a strict distinction between timed and all-day events and implementing a standard-compliant recurrence engine, it ensures data integrity across different timezones and external calendar clients. Its integration with the web UI via server-side rendering and live updates provides a responsive experience for family dashboard displays.