livestock-tracker

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.