Shopping Lists (Mealie Integration)

Relevant source files

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

• GLOSSARY.md
• internal/app/app.go
• internal/app/integrations.go
• internal/db/migrations/0006_integrations.sql
• internal/app/calendar.go

Shopping lists in GoCasa operate as Mirrored lists that connect directly to a Mealie instance. GoCasa displays and modifies these lists in real-time, relying on the external Mealie service for data persistence.

Sources: GLOSSARY.md:96-98

Mirrored List Architecture

A Mirrored list lives in Mealie while GoCasa acts as a client interface. Unlike the calendar or chores which may have local state, a mirrored shopping list requires Mealie to be available for any changes to occur. If Mealie is offline, the list becomes read-only or unavailable within the GoCasa dashboard.

Sources: GLOSSARY.md:96-98

Integration Framework

GoCasa manages the Mealie connection through its generalized integration framework. This framework handles background synchronization, credential security, and error backoff.

The diagram shows how the GoCasa Scheduler triggers the integration logic to interact with external services like Mealie.
Sources: internal/app/integrations.go:37-65, internal/app/app.go:78

Data Model and Security

Integrations, including Mealie, are stored in the integrations table. Credentials such as API keys are encrypted at rest using AES-256-GCM.

Encryption Logic

GoCasa uses the APP_ENCRYPTION_KEY environment variable to secure Mealie credentials. The application performs the following actions:

1. Sealing: Encrypts the plain text API key or token with a random nonce before storage.
2. Unsealing: Decrypts the stored BLOB when the sync process requires authentication with Mealie.

Sources: internal/app/integrations.go:106-130, internal/db/migrations/0006_integrations.sql:4

Integration Table Schema

The database tracks the health and configuration of the Mealie link using several specific fields:

Field	Type	Description
type	TEXT	Identifies the integration (e.g., 'mealie').
credentials_enc	BLOB	The encrypted Mealie API credentials.
sync_interval_seconds	INTEGER	Frequency of background updates (Default: 900s).
last_error	TEXT	Stores the last failure message from Mealie.
consecutive_failures	INTEGER	Counter used for exponential backoff logic.

Sources: internal/db/migrations/0006_integrations.sql:2-10, internal/app/integrations.go:72-88

Synchronization Logic

The GoCasa Scheduler manages the life cycle of the Mealie connection. Synchronization occurs periodically based on the next_sync_at timestamp in the database.

Sync Workflow

1. Check Due: The application queries for enabled integrations where next_sync_at is less than or equal to the current time.
2. Execution: The syncIntegration function initiates the Sync method of the Mealie integration implementation.
3. Timeout: Every sync attempt is capped at a 2-minute timeout to prevent hanging connections.
4. Error Handling: If a sync fails, GoCasa increments the failure count and schedules a retry using an exponential backoff, capped at 6 hours.

Sources: internal/app/integrations.go:27-28, internal/app/integrations.go:37-65, internal/app/integrations.go:78-88

The sequence diagram illustrates the polling mechanism GoCasa uses to keep mirrored lists updated.
Sources: internal/app/integrations.go:37-90

Summary

The Mealie integration enables mirrored shopping lists within the GoCasa dashboard. By leveraging a centralized integration framework, the system ensures that list data remains synced with the Mealie instance while maintaining security through AES-256 encryption for all sensitive connection credentials.