livestock-tracker

# 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

```bash
# 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.