Skip to content

Provider Blueprint (How to Add a New Provider)

Blueprint goal

A provider is valid only when it respects the shared contract and integrates with registry, cache, and docs/test policies. This page is the canonical add-provider checklist.

Step 1: Define provider config and UI

  1. Add typed config schema/type for the provider.
  2. Implement a configuration component for settings modal flow.
  3. Keep source-specific validation inside the provider domain.

Step 2: Implement provider contract

Implement the CalendarProvider interface with clear source capability boundaries (see Provider Architecture for orchestration model and Provider Implementations and Patches for non-standard cases):

  • getEvents is mandatory.
  • createEvent / updateEvent / deleteEvent should throw explicit read-only errors if unsupported.
  • getEventHandle must return stable persistent identity.
  • Optional hooks (initialize, toggleComplete, canBeScheduledAt) are allowed only when needed.

If recurring instance complete/skip semantics are provider-owned, implement the normalized recurring-instance hooks described in Provider Implementations and Patches.

Step 3: Register and instantiate via registry

  1. Register dynamic loader in registerBuiltInProviders.
  2. Ensure source type maps to the exported class static type.
  3. Verify initialization path in initializeInstances and runtime source updates (mutation/write routing behavior is defined in EventCache Contract).

Step 4: Choose load priority intentionally

Load priority controls staged loading behavior (profiling context: Calendar Load Profiling Audit):

  • Lower values load earlier and improve perceived first render.
  • Higher values can defer expensive or non-critical providers.
  • Priorities should reflect startup UX and source latency profile.

Step 5: Validate identifier and sync behavior

  • Ensure getEventHandle produces durable IDs across reads.
  • Confirm mapping calendarId::persistentId remains stable.
  • Verify update ingestion paths do not duplicate or orphan events.

Step 6: Ship with docs and tests

Minimum expectation before merge:

  • Unit tests for parser/serializer or source edge cases.
  • Integration tests for cache-provider mutation path.
  • Architecture docs update in Provider Architecture and, when behavior is specialized, Provider Implementations and Patches.
  • User docs update if the provider is user-configurable.

Validation expectations and documentation sync policy are defined in Testing and Validation.

Contributor contract

Append or modify only relevant documentation sections. Do not rewrite unrelated architecture pages when adding a provider.

Integration anchors

  • src/providers/Provider.ts
  • src/providers/ProviderRegistry.ts
  • src/ui/settings/SettingsTab.tsx