Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• cmd/gocasa/main.go
• internal/app/app.go
• internal/app/calendar.go
• internal/config/config.go
• internal/app/ics.go
• GLOSSARY.md

GoCasa is a self-hosted family calendar dashboard distributed as a single static Go binary. It uses a SQLite database for persistence and provides a server-rendered user interface. The system manages shared calendars, to-dos, chores, and household settings within a single-instance architecture.

Sources: README.md:3-5, GLOSSARY.md:3-5

System Structure

The application follows a modular monolith structure. The main package initializes the configuration, database, and application services before starting an HTTP server.

The diagram shows the high-level dependency flow from the entry point to the core internal modules.
Sources: cmd/gocasa/main.go:49-75, internal/app/app.go:51-82

Core Components

Component	Responsibility
App	Wires dependencies into an http.Handler and manages core business logic.
Config	Loads and validates environment-based configuration variables.
Scheduler	Manages background tasks like database backups and integration syncing.
Bus	Provides a server-sent events (SSE) stream for live UI updates.
Web	Contains server-rendered components generated via templ.

Sources: internal/app/app.go:34-45, internal/config/config.go:21-72, internal/web/calendar_templ.go:214-239

Data Management

GoCasa uses a single SQLite file (app.db) located in the DATA_DIR. The application manages the database lifecycle through automated migrations and daily backups.

Database Lifecycle and Migrations

At startup, the application checks the PRAGMA user_version. If the database version is newer than the binary supports, the application refuses to start. Before running pending migrations, the system creates a pre-migration backup in the backups/ directory.

Sources: README.md:36-46, internal/app/app.go:61-71

Backup Strategy

The Scheduler triggers a VACUUM INTO backup every day at 03:00 (local time). The system maintains a rolling window of the newest 14 backups.

Sources: README.md:23-28, internal/app/app.go:80

Request Flow and Routing

The App struct implements http.Handler via a ServeMux. It includes middleware for cross-origin protection and session unlocking.

The diagram illustrates the flow of a standard HTTP request through the security layers to the database.
Sources: internal/app/app.go:85-117, internal/app/calendar.go:121-140

Security and Authentication

The application uses a PIN-based lock system for Admin actions.

• CSRF Protection: The system refuses cross-site unsafe requests by checking Sec-Fetch-Site or Origin headers.
• Encryption: APP_ENCRYPTION_KEY (32 bytes) encrypts OAuth tokens and API keys at rest.
• Access Control: Actions like creating members or adding feeds are wrapped in requireUnlock decorators.

Sources: README.md:15-18, internal/app/app.go:94-110, internal/config/config.go:58-62

Integration and Scheduling

The application synchronizes data from third-party services and exports internal data via standard formats.

Background Tasks

The Scheduler runs every 30 seconds to process due jobs. It handles:

1. Integration Syncing: Fetches data from Google Calendar, Mealie, or iCal feeds.
2. Backups: Performs the daily 03:00 database backup.

Sources: cmd/gocasa/main.go:82, internal/app/app.go:76-80

ICS Export

GoCasa provides an iCalendar (ICS) export endpoint. It translates internal SQLite events, including recurring series and one-off edits, into RFC 5545 compliant calendar data.

Sources: internal/app/ics.go:20-50

Configuration Options

GoCasa is configured exclusively via environment variables.

Variable	Type	Default	Description
ADDR	string	:8080	Network address to listen on.
BASE_URL	URL	(Required)	Absolute URL for links and secure cookies.
DATA_DIR	path	/data	Directory for the DB and backups.
TZ	string	UTC	Default IANA time zone for the household.
APP_ENCRYPTION_KEY	base64	(Required)	32-byte key for at-rest encryption.
SESSION_SECRET	string	(Required)	Secret for session signing (min 32 chars).

Sources: README.md:12-21, internal/config/config.go:21-72

Summary

The GoCasa architecture prioritizes simplicity and self-containment. By combining a Go backend, a SQLite database, and server-rendered Templ components into one binary, it minimizes deployment complexity. Background tasks are managed internally via a custom scheduler, while security is enforced through environment-driven configuration and origin validation.