Google Calendar Integration

Relevant source files

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

• internal/app/app.go
• internal/app/integrations.go
• internal/db/migrations/0006_integrations.sql
• internal/db/migrations/0004_local_calendar.sql
• GLOSSARY.md
• README.md

The Google Calendar Integration allows an Admin to connect Google accounts to GoCasa. This system syncs external calendars into the local database to display them on the family dashboard alongside local events.

A Google account represents one Google login. GoCasa supports multiple connections, and each account can sync multiple calendars. If Google withdraws access, the integration enters a "Reconnect needed" state, where it stops syncing but continues to display the last known events until re-authenticated by an Admin.

Sources: GLOSSARY.md:61-70, README.md:57-59

Integration Architecture

GoCasa uses a generic integration framework to handle external data sources. The Google integration relies on specific upstreams and encrypted storage for credentials.

Components and Upstreams

The application defines fixed third-party base URLs for Google services:

• GoogleAPI: https://www.googleapis.com
• GoogleOAuth: https://oauth2.googleapis.com

Sources: internal/app/app.go:21-31

Data Flow

The following diagram illustrates how the application schedules and executes integration syncs.

The Scheduler triggers the syncDue function, which identifies integrations requiring updates based on the next_sync_at timestamp.

Sources: internal/app/app.go:102, internal/app/integrations.go:40-101

Data Model

The integration system extends the database to support external syncing, encrypted credentials, and error tracking.

Integrations Table

The integrations table tracks the state and configuration of each connection.

Column	Type	Description
type	TEXT	The integration type (e.g., 'local', 'ical', or google related).
config_json	TEXT	Configuration parameters stored as JSON.
credentials_enc	BLOB	Encrypted OAuth tokens or API keys.
sync_interval_seconds	INTEGER	Frequency of sync attempts (default 900s).
next_sync_at	INTEGER	Unix timestamp for the next scheduled sync.
consecutive_failures	INTEGER	Count of failed attempts for backoff logic.
sync_cursor	TEXT	Internal state used by the integration to track progress.

Sources: internal/db/migrations/0006_integrations.sql:3-13, internal/db/migrations/0004_local_calendar.sql:4-8

Relationship Schema

The following diagram shows the relationship between integrations, calendars, and events.

Security and Encryption

GoCasa encrypts sensitive integration data at rest using AES-256-GCM.

• Encryption Key: The APP_ENCRYPTION_KEY environment variable must provide 32 random bytes.
• Sealing Process: The seal function encrypts plain credentials with a random nonce.
• Unsealing Process: The unseal function decrypts stored credentials. If the APP_ENCRYPTION_KEY changes, existing credentials cannot be decrypted, requiring the Admin to reconnect the integration.

Sources: internal/app/integrations.go:111-137, README.md:30-31

Sync Logic and Error Handling

The system manages external API limitations and network issues through automated retries and backoffs.

Backoff Strategy

When a sync fails, the system records the error and schedules a retry with an exponential backoff.

1. The consecutive_failures count increments.
2. The delay is calculated as 1 minute << failures, capped at 6 hours (maxBackoff).
3. The error message is truncated to 500 characters and stored in last_error.

Sources: internal/app/integrations.go:36, internal/app/integrations.go:88-93

Sync Recovery

A successful sync resets consecutive_failures to 0 and clears the last_error field.

Sources: internal/app/integrations.go:81-83

Conclusion

The Google Calendar Integration is a robust system within GoCasa that utilizes a centralized integration framework. It ensures data security through AES encryption and maintains dashboard reliability via automated background synchronization and error-aware scheduling.