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:

Status	Meaning
active	Healthy and in the herd
treatment	Currently receiving medical treatment
quarantine	Isolated, under observation
sold	No longer on the farm
deceased	Died or euthanized

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:

Species	Gestation (days)
Cattle	283
Sheep	147
Goat	150
Pig	114

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

Variable	Description	Default
PORT	HTTP port	3002
DATA_DIR	SQLite directory	./data
AUTH_PASSWORD	Optional login password	(empty)
NODE_ENV	development or production	development
SESSION_SECRET	Required in production	(required)
REMINDER_DAYS_AHEAD	Days before due date to generate reminder	7
DEFAULT_TIMEZONE	Initial timezone for settings	America/Chicago

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.