Domain Glossary
Relevant source files
The following files were used as context for generating this wiki page:
The Domain Glossary defines the business logic and technical terminology used within the GoCasa project. GoCasa provides a self-hosted family dashboard for a single household, including shared calendars, to-dos, shopping lists, chores, and photo screensavers.
Sources: GLOSSARY.md:1-5, README.md:1-5
People and Access Control
GoCasa manages members of a single household and applies specific roles and access restrictions to maintain privacy and data integrity.
Key Entities
- Household: The single family unit served by the GoCasa instance.
- Member: A person or pet belonging to the household. Members can have events and chores assigned to them.
- Admin: A Member with elevated privileges who can modify integrations and household settings. Admins use a PIN for authentication.
- Archived Member: A member who has left the household. The system hides them from UI pickers but retains their historical data and points.
Sources: GLOSSARY.md:9-25, internal/web/settings_templ.go:17-25
Access State Diagram
This diagram shows the relationship between different member states and access levels.
Calendar and Events
The calendar system handles complex recurring patterns and synchronization with external sources.
Event Types and Recurrence
| Term | Description |
|---|---|
| Household event | An event visible to everyone, regardless of filters, belonging to no specific Member. |
| Series | A recurring event definition containing a repeat rule. |
| Occurrence | A specific dated instance generated by a Series. |
| One-off edit | A change or deletion of a single Occurrence that does not affect the rest of the Series. |
| Split | The process of ending a Series and starting a new, independent Series from a specific Occurrence. |
Sources: GLOSSARY.md:29-50
Recurrence Management
The system tracks edits using an Edit scope to determine which occurrences a change applies to.
- This event: Applies only to the selected instance.
- This and following: Applies to the current and all future instances.
- All events: Modifies every instance in the series.
Sources: GLOSSARY.md:52-54, internal/web/calendar_templ.go:343-359
Technical Implementation of Events
The application represents events using the following structure:
type calendarEvent struct {
id int64 // Series ID
original int64 // Occurrence timestamp key
title string
allDay bool
start, end int64 // Timed timestamps
date, endDate string // All-day strings
colors []string // Member or calendar colors
readOnly bool // If from an external feed
}
Sources: internal/app/calendar.go:68-78
Integration and Synchronization
GoCasa connects to external services like Google Calendar and iCal feeds to aggregate household data.
- Google account: A Google login connected by an Admin to sync calendars.
- Reconnect needed: A state where external authentication has expired, requiring Admin intervention.
- Mirrored list: A shopping list sourced from Mealie. Changes are unavailable if the Mealie instance is offline.
- iCal Feed: A read-only external calendar (e.g., school or sports team) synced via URL.
Sources: GLOSSARY.md:56-65, GLOSSARY.md:112-114, internal/web/settings_templ.go:187-188
Integration Schema Extensions
Integrations are tracked in the database with fields for synchronization state and error tracking.
| Field | Description |
|---|---|
sync_interval_seconds | How often the integration refreshes data (default 900s). |
consecutive_failures | Number of failed sync attempts in a row. |
sync_cursor | Metadata used for delta syncs (e.g., ETags). |
read_only | Flag indicating if the source calendar can be edited in GoCasa. |
Sources: internal/db/migrations/0006_integrations.sql:3-13
Tasks and Chores
The system distinguishes between one-time tasks and recurring household maintenance.
To-dos vs. Chores
- Recurring to-do: A task that creates a new copy upon completion. It can repeat from a fixed schedule or from the last completion date.
- Chore: A scheduled job that earns points. Unlike a to-do, if a chore is not done, it is never "owed" later; it simply lapses.
- Round: A specific period (day/week) for a chore completion.
Sources: GLOSSARY.md:69-89
Chore Completion Logic
Sources: GLOSSARY.md:91-103
Dashboard and Display
Terminology for the user interface and hardware setups.
- Today: The primary dashboard view showing current events, weather, and active tasks.
- Wall display: A device configured in an always-on "dashboard mode."
- Night mode: Specific hours when the Wall display dims or shows a black screen.
- Fallback folder: Local images displayed when primary photo integrations (like Immich) have no content.
Sources: GLOSSARY.md:118-139
Summary
The Domain Glossary centralizes the language used across GoCasa's calendar, task, and member management systems. By enforcing specific terms—such as "Member" instead of "User" and "Round" for chores—the project maintains a consistent logic for its single-household architecture.
Sources: GLOSSARY.md:1-139