Data Flow

Flow Philosophy

All runtime paths converge through the same center: providers ingest and persist data, while EventCache arbitrates state and publishes updates. This keeps read/write behavior consistent across local and remote calendars.

Runtime Flows

Initial Load

Plugin startup initializes registry, cache, and managers; providers supply raw records; normalization/enhancement runs; EventStore indexes results; subscribers then render the first stable state.

User-Initiated Mutation

UI captures intent (create/edit/drag/resize), EventCache applies optimistic state transition (1), ProviderRegistry routes the write to the owning provider (2), and cache confirms or rolls back based on provider result (3).

1. Optimistic UI ensures zero latency for the user.
2. Routing is based on the calendar source's unique ID.
3. Rollbacks handle network failures or permission issues gracefully.

External Update Ingestion

Vault or remote changes are observed by providers, affected records are re-read (1), EventCache performs sync and diff (2), and subscribers receive batched notifications (3).

1. Only modified files/records are processed to maintain performance.
2. The diffing engine prevents duplicate event notifications.
3. Batching ensures the UI only redraws once even for multiple simultaneous updates.

Time Tick and Reminder Path

TimeEngine computes upcoming occurrences within its horizon, emits time state through cache notifications, and notification features trigger reminders according to configured rules.

Flow Invariants

Flow Invariants

Do not bypass EventCache for mutations. Do not emit provider-specific state directly to UI subscribers. Normalization and diffing must occur before broad publish to keep UI behavior deterministic.

Code Anchors

Primary orchestrator: src/core/EventCache.ts
Temporal computation: src/core/TimeEngine.ts
Notification handling: src/features/notifications/NotificationManager.ts
Provider dispatch: src/providers/ProviderRegistry.ts