Skip to content

ADR 001: Dedicated Calendar Service for Layered Availability

Date: 2026-02-05 Status: Accepted

Context

The previous "one calendar per service" availability model was inefficient and prone to errors. Partners with multiple services (e.g., 20 Jeep Tours) had to manage 20 separate calendars. A change in schedule required 20 manual updates.

We needed a system that supports: 1. Templates: Define availability once (e.g., "Summer Season") and apply it to many services. 2. Layering: Combine templates with service-specific overrides and global exceptions. 3. High-Volume Queries: Availability checks are frequent and complex.

Decision

We decided to extract calendar logic into a dedicated Calendar Service (calendar-service).

Key Architectural Choices:

  1. Microservice Architecture: Decouples complex recurrence calculation (rrule) from the core partner-service.
  2. Layered Engine: Availability is calculated at runtime by merging three layers:
    • Layer 1 (Template): The base pattern (e.g., Mon-Fri 9-5).
    • Layer 2 (Binding): Service-specific rules (currently just linking, future overrides).
    • Layer 3 (Exceptions): Blackouts (e.g., "Closed for Maintenance") or custom openings.
  3. Simulation API: Exposed a stateless /simulation endpoint to allow Agents and UI to test "what-if" scenarios without persisting data.
  4. Database: Dedicated PostgreSQL database calendar with a schema optimized for time-range queries.

Consequences

Positive

  • Scalability: Availability calculation load is isolated.
  • Maintainability: Recurrence logic is centralized.
  • User Experience: Partners save time using templates.

Negative

  • Complexity: Introduced a new distributed service and synchronization requirement (Service IDs).
  • Latency: Use of rrule expansion can be CPU intensive, requiring optimization (caching) for long date ranges.