Skip to main content

Domain Model

Introduction to the Roll Claw Domain Model​

The domain model is the heart of the Roll Claw application, representing the core concepts and relationships within a feral cat colony management system. This model captures the essential elements of colony care, cat tracking, volunteer coordination, and resource management.

What is a Domain Model?​

A domain model is a conceptual representation of the entities, relationships, and behaviors that exist within a specific problem domain. For Roll Claw, our domain model reflects the real-world concepts and activities involved in managing feral cat colonies, drawing heavily from the insights gained from studying the Lime Factory Colony data.

Event-Driven Architecture​

Roll Claw uses an event-driven architecture approach, where all changes to the system state are captured as events. This provides several benefits:

  1. Complete Historical Record: Every cat sighting, health observation, and task completion is recorded, allowing caretakers to trace patterns and changes over time.
  2. Offline Functionality: Events can be recorded locally when offline and synchronized when connectivity is restored.
  3. Rich Analysis: The complete event history enables deeper insights into colony dynamics and trends.

Core Domain Concepts​

Our domain model revolves around these primary concepts:

  • Cats: Individual feral cats with identities, health status, and relationship networks
  • Locations: The physical spaces where cats are observed and care activities occur
  • Sightings: Observations of cats at specific times and places
  • Health Events: Medical procedures, conditions, and observations
  • Tasks: Care activities that need to be performed by volunteers
  • Resources: Supplies and equipment needed for colony care

Domain Structure​

The Roll Claw domain model is organized into several key components:

Entities​

Entities are objects with a distinct identity that persists over time. In Roll Claw, the primary entities include:

  • Cats
  • Locations
  • Volunteers
  • Equipment

Browse the Entities documentation →

Value Objects​

Value objects are immutable objects that describe characteristics of entities. They include:

  • Cat descriptions (coat pattern, size, etc.)
  • Location coordinates
  • Time periods
  • Measurements

Aggregates​

Aggregates are clusters of entities and value objects that are treated as a single unit for data changes. Key aggregates in Roll Claw include:

  • Cat profiles (including health history and sightings)
  • Colonies (collection of cats, locations, and care routines)
  • Task assignments

Events​

Events record all changes to the system state. Roll Claw's core events include:

  • Cat sightings
  • Health observations
  • Task completions
  • Resource consumption

Commands​

Commands represent user intentions that change the system state. Roll Claw implements commands such as:

  • Record cat sighting
  • Update health status
  • Assign task to volunteer
  • Mark task complete

Repositories and Services​

These components provide access to persistent storage and implement business logic:

  • Repositories: Provide access to aggregates from the database
  • Services: Implement complex domain logic that spans multiple aggregates

How This Documentation Is Structured​

The domain model documentation is organized into directories that correspond to the different types of domain components:

  • /entities - Core domain objects with identity (Cat, Location, Equipment, etc.)
  • /value_objects - Immutable objects that describe characteristics
  • /aggregates - Clusters of entities that form consistency boundaries
  • /events - Event definitions that record system state changes
  • /repositories - Data access components
  • /services - Business logic spanning multiple aggregates

Each component is documented with:

  1. A pseudocode file (.pseudo) that shows its structure and behavior
  2. An MDX documentation file (.mdx) that explains its purpose and relationships

Adding New Domain Components​

To add new documentation for a domain component:

  1. Create a .pseudo file in the appropriate directory
  2. Create an accompanying .mdx file with explanation
  3. Update the sidebar configuration in sidebars.js to include your new file

See the README for detailed instructions and templates.

Example: Equipment Entity​

The Equipment Entity serves as an example of how domain components are documented. It includes:

  • Pseudocode implementation showing structure and methods
  • Explanation of core properties and behaviors
  • Related components and their relationships

Domain Model Insights from Lime Factory Colony​

Our domain model is informed by real-world colony management data from the Lime Factory Colony. Key insights include:

  1. Complex Relationships - Cats form intricate social and family networks that need to be tracked
  2. Territory Patterns - Location tracking is essential for understanding movement and territory
  3. Health Monitoring - Consistent health observation is critical for early intervention
  4. Resource Management - Equipment and supplies require regular maintenance and replenishment
  5. Volunteer Coordination - Multiple caretakers need clear task assignment and verification

These insights guided our domain modeling decisions and event-driven architecture approach.