livestock-tracker

name: livestock-tracker description: Track individual animals, record health events, vaccinations, weights, and breeding events. Use when asked to add an animal to the herd, log a vaccination, record body weight, track a treatment, set up a breeding event, check overdue vaccinations, or view the animal timeline. Triggers include "add animal", "record vaccination", "log weight", "track treatment", "breeding event", "overdue vaccines", "animal health history", "herd overview", or any task involving individual animal management.

livestock-tracker

Manage your herd's health records, vaccination schedules, weight trends, and breeding events from one self-hosted app.

When to Use

• Registering a new animal to the herd
• Recording a vaccination and setting the next due date
• Logging body weights for one or multiple animals at once
• Adding a health event (treatment, vet visit, injury, observation)
• Recording a breeding event and tracking expected birth dates
• Checking which vaccinations are overdue or due within the next 7 days
• Viewing the full health timeline for a specific animal

Key Concepts

Animals

Each animal has a name, tag number, species, breed, sex, date of birth, and status. Status values are:

Health Events

Health events capture any veterinary activity: vaccinations, treatments, vet visits, injuries, or routine observations. Each event can have a follow-up date, which generates a reminder notification.

Vaccinations are stored in a separate vaccinations table with a due_date field for the next booster. The daily cron job uses this field to generate notifications.

Weight Records

Weight records are stored per animal with a date. The animal detail page shows a Chart.js line chart of all weight records. Average daily gain (ADG) is calculated from the first and latest records.

Breeding Events

A breeding event links a dam (mother) to a sire (father, either from the herd or external). Expected birth date is auto-calculated from the species gestation period if not provided manually:

Notifications

The daily cron job at 06:00 writes notifications for:

• Vaccinations due within the reminder window (default 7 days)
• Overdue vaccinations (past due date)
• Upcoming births (expected within 14 days, configurable)
• Health event follow-up dates

Notifications accumulate in the database until dismissed. They do not send email.

API Quick Reference

# List all animals (with herd stats)
curl http://localhost:3002/api/animals

# Add an animal
curl -X POST http://localhost:3002/api/animals \
  -H "Content-Type: application/json" \
  -d '{"name":"Hazel","tag_number":"A149","species":"cattle","breed":"Hereford","sex":"female","date_of_birth":"2023-03-15"}'

# Get animal with latest weight and next vaccination
curl http://localhost:3002/api/animals/{id}

# Get animal's full event timeline
curl http://localhost:3002/api/animals/{id}/timeline

# Record a vaccination
curl -X POST http://localhost:3002/api/vaccinations \
  -H "Content-Type: application/json" \
  -d '{"animal_id":"...","vaccine_name":"IBR/BVD Combo","administered_date":"2025-04-18","due_date":"2026-04-18","batch_number":"IBR-2025-04"}'

# List overdue vaccinations
curl "http://localhost:3002/api/vaccinations?overdue=1"

# List upcoming vaccinations (within reminder window)
curl http://localhost:3002/api/vaccinations/upcoming

# Record a weight
curl -X POST http://localhost:3002/api/weights \
  -H "Content-Type: application/json" \
  -d '{"animal_id":"...","weight_kg":285,"recorded_date":"2025-04-18"}'

# Add a health event
curl -X POST http://localhost:3002/api/health-events \
  -H "Content-Type: application/json" \
  -d '{"animal_id":"...","event_type":"treatment","event_date":"2025-04-18","title":"Foot bath treatment","cost_usd":24.00,"follow_up_date":"2025-04-25"}'

# Record a breeding event
curl -X POST http://localhost:3002/api/breeding \
  -H "Content-Type: application/json" \
  -d '{"dam_id":"...","sire_id":"...","bred_date":"2024-10-15"}'

# List active notifications
curl http://localhost:3002/api/notifications

# Dismiss a notification
curl -X PUT http://localhost:3002/api/notifications/{id}/dismiss

Environment Variables

Troubleshooting

Overdue vaccinations not appearing in notifications

1. Verify the cron job is running: check server logs for vaccination-check output at 06:00
2. Confirm the vaccination has a due_date set: GET /api/vaccinations/{id}
3. Check dismissed is 0 on the notification: dismissed notifications do not appear in active list
4. Run a manual check by triggering the job endpoint if available in development mode

Expected birth date not calculating

The auto-calculation requires species to be set on the dam's animal record. If bred_date is set but expected_birth_date is null, check the species value with GET /api/animals/{dam_id}.

Weight chart not showing

Flow: weight records must be present for the animal. Check GET /api/weights?animal_id={id} returns records sorted by recorded_date asc.