Data Model

Design principles

• Timeline-first: most activity is captured as Events on an Animal timeline.
• Many contacts per animal: connect via an AnimalContact (Relationship) join table.
• History, not overwrites: relationships and placements have start/end dates.
• Privacy by classification: events/fields can be Public, Internal, or Sensitive.

Core entities

Animal

Represents a dog or cat.

• Identity: name, species, breed (primary/secondary if mixed), sex, age/DOB estimate, primary/secondary coat colors, special markings/characteristics
• Status: monitoring / in custody / outcome; plus adoption listing status
• Tags/custom fields: intake type, behavior flags, special needs
• Media: photos, documents

Contact

Represents a person or organization (foster, adopter, applicant, owner, reporter, feeder, vet, volunteer).

• Basic: name, type (person/org), phone(s), email(s)
• Address (optional), preferred contact method
• Consent flags (for communications)

AnimalContact (Relationship)

Join table between Animal and Contact. This is the backbone of “more than one contact per animal”.

• animal_id, contact_id
• role (examples): foster, backup_foster, adopter, applicant, previous_owner, reporter, feeder, veterinarian, transporter, volunteer
• start_date, end_date
• is_primary (per role, optional)
• visibility (internal-only relationship notes, if needed)

CustodyEpisode

Tracks whether the rescue has custody.

• type: monitoring (no custody) | in_custody
• start_at, end_at
• source: found stray, transfer, owner surrender, etc.
• sensitive_case: default true for monitoring strays

Placement (Foster/Boarding)

Tracks where an animal stays while in custody.

• placement_type: foster | boarding | temp_holding
• contact_id (for foster/boarding contact/org)
• start_at, end_at
• agreement_document_id (optional)

Location

Reusable location object for events and route stops.

• lat, lng (required for stray monitoring events; optional otherwise)
• alias_name (optional): volunteer-known place name (e.g., “Location A”)
• Address fields (optional)
• Optional area_polygon for territory/zone
• precision (exact vs rounded) and visibility (public/internal/sensitive)

Optional extension: support multiple aliases per location (e.g., different teams/routes use different names).

Event (AnimalTimelineEvent)

Everything that happens to an animal, timestamped.

• Examples: sighting, trap_set, route_checkin; medical_note, vaccine, vet_visit; behavior_note; placement_start/end; decision; outcome_recorded
• Fields: type, occurred_at, created_by, optional location_id
• visibility: public | internal | sensitive
• payload (structured fields depending on type) + attachments

MedicalRecord

• Sub-entities: Vaccine, Medication, Condition, VetVisit, LabResult
• Reminders/due dates + attachments

Application / FormDefinition / Workflow

• Applications: adoption | foster; contact(s); optional animal link; stage/status; attachments
• FormDefinition: conditional questions, required fields, consents, file uploads
• Workflow: stages + required tasks + approver roles; decisions store reason codes + audit metadata

Task / TaskType

• Custom tasks tied to an animal and/or contact, assigned to users, due dates, comments, attachments
• Supports post-placement tasks (post-adoption spay/neuter, microchip registry updates, booster vaccines, check-ins)

Route / RouteStop / CheckIn

• Route schedule + assigned feeders
• Stops use Locations (GPS) + notes/photos
• Check-ins can optionally create a Sighting Event

Volunteer management (recommended)

• Model volunteers as Contacts with an attached VolunteerProfile (onboarding status, waiver status, optional emergency contact).
• VolunteerSkill: skill tags (feeder, transporter, events, admin, photographer, etc.) and optional training completion.
• VolunteerAvailability (optional): days/times, regions, max assignments.
• VolunteerShift (optional): route/event shifts with start/end, assignments, attendance.
• VolunteerHoursLog (optional): time entries for recognition/grants.

MicrochipRegistryRecord (optional)

Tracks microchip registration and lookup status.

• animal_id, microchip_id
• registry_name (if known) + status (unknown/verified/needs_update)
• last_verified_at, notes + attachments (scan photo, registry confirmation)

IntegrationSync (Listing registries) (Phase 2)

• One-way publish jobs with payload snapshots, timestamps, errors, and retry metadata (Petfinder, Adopt-a-Pet, etc.)

Clinic + partner coordination (recommended)

• ClinicAppointment: links animal + clinic contact + confirmed datetime, transport assignments, outcome (completed/canceled/no-show), notes, attachments/invoice.
• PartnerOrganization: partner rescues/clinics/shelters/vendors (stored as org Contacts), with partner type and handoff notes.
• TransferCase (optional): formal record of a handoff to a partner rescue/shelter with required documents and outcome.

Lost dog recovery / field trapping (recommended)

• LostDogRecoveryCase: public recovery request + field plan; requester contact (owner/reporter), optional animal link until confirmed, last-known Location (with alias), status (intake/planning/active/recovered/closed), and outcome (reunited/in_custody/transferred/not_found).
• FeedingStation (optional): recovery feeding station at a Location (with alias), schedule/notes/photos.
• EquipmentItem (optional): traps/trail cameras/crates with checkout/deploy/return history (who/when/where).

Community aid / outreach (recommended)

• OutreachVisit: time + Location (alias) + linked Contacts (owners/volunteers) + notes + follow-up tasks.
• AidDistribution (optional): what was delivered (food/supplies/meds) and quantities, tied to an OutreachVisit.

Relationship map (high level)

• Animal 1—* Event
• Animal *—* Contact via AnimalContact
• Animal 1—* CustodyEpisode
• Animal 1—* Placement
• Event *—1 Location (optional)
• RouteStop 1—1 Location
• Application *—1 FormDefinition; Application *—1 Workflow
• Workflow 1—* Stage 1—* Decision