Skip to main content

Event-Driven Architecture

Roll Claw is built on an event-driven architecture using event sourcing principles. This architectural approach is particularly well-suited for colony management, as it provides:

  1. A complete, immutable history of all activities
  2. Powerful historical analysis capabilities
  3. Reliable offline operation with eventual consistency
  4. Clear separation between commands (actions) and read models (views)

Core Architectural Concepts​

Events as the Source of Truth​

In Roll Claw, events are the primary source of truth. Every change to the system state is recorded as an event:

  • CatSightingRecorded - When a cat is observed
  • HealthStatusUpdated - When a health condition is noted
  • TaskCompletedEvent - When a volunteer finishes a task

These events are stored permanently and form the basis for all state in the system.

Command-Event Flow​

User interactions follow a clear flow:

  1. User issues a Command (e.g., RecordCatSighting)
  2. System validates the command
  3. Command handler generates appropriate Events (e.g., CatSightingRecorded)
  4. Events update the system state
  5. Read models are updated based on events

Projections and Read Models​

To make the event data useful, Roll Claw creates various projections, such as:

  • CatProfile - Current information about each cat
  • HealthStatus - Current health conditions and history
  • TaskSchedule - Upcoming and completed tasks

These projections are derived from events and optimized for specific query patterns.

Offline-First Approach​

The event-driven architecture enables Roll Claw's offline-first approach:

Local Event Recording​

When offline:

  1. Commands are validated locally
  2. Events are stored in the local device database
  3. Local projections are updated immediately

Synchronization​

When connectivity is restored:

  1. Local events are synchronized with the server
  2. Server-side events are pulled to the device
  3. Conflict resolution handles any inconsistencies
  4. Local projections are updated with the latest events

This approach ensures that colony caretakers can continue working effectively in the field, even without consistent internet connectivity.