Flockwise

Flockwise helps sheep and goat farmers manage livestock records from one responsive workspace. It combines individual animal histories with farm-level health, reproduction, growth, medicine, nutrition, task, and reporting workflows. The web interface is installable as a Progressive Web App (PWA).

• Farms, team memberships, role-based access, flocks, and animal profiles
• Health observations, treatments, attachments, and complete animal timelines
• Breeding records, expected birth dates, and birth outcomes
• Weight history, average daily gain, and growth reporting
• Medicine products, batches, treatment courses, doses, and withdrawal periods
• Feed products, diet plans, husbandry tasks, reminders, and notifications
• CSV reports and imports, audit history, and private farm documents
• Signup, session authentication, password recovery, and installable PWA support

The backend is a modular monolith. Domain modules live in backend/apps/, while the frontend is organised under frontend/app/. Architecture decisions and MVP boundaries are documented in docs/adr/ and docs/mvp.md.

• Docker Desktop with Docker Compose
• Git

git clone <repository-url>
cd livestock-tracker-platform
cp .env.example .env
docker compose up --build

Open the following services:

• Web application: http://localhost:3000
• API: http://localhost:8000/api/v1/
• OpenAPI documentation: http://localhost:8000/api/docs/
• Django Admin: http://localhost:8000/admin/

Create an account from /signup, or create an admin user with:

docker compose exec api python manage.py createsuperuser

To load a dashboard-ready demonstration farm, run:

docker compose exec api python manage.py seed_demo_data

Sign in with demo / demo-password. The command is safe to rerun and accepts --username and --password when different local credentials are preferred.

Stop the stack with docker compose down. Avoid docker compose down -v unless you intentionally want to delete local database and attachment volumes.

Copy .env.example and replace the development defaults. Important settings include:

The console email backend is suitable for local development; reset and invitation links appear in API or worker logs. Never commit .env or production credentials.

Run checks through the active Compose stack:

docker compose exec api ruff check .
docker compose exec api ruff format --check .
docker compose exec api pytest -q
docker compose exec web npm run typecheck
docker compose exec web npm run build

Backend tests cover permissions, farm isolation, validation, and API workflows. New domain behavior should include focused test_*.py coverage.

Service workers are disabled during development to prevent stale caches. Test the production PWA locally with:

docker compose stop web
docker compose run --rm web npm run build
docker compose run --rm --service-ports web npm run preview -- --host=0.0.0.0

Open http://localhost:3000 and use the account menu or browser installation control. Farm API responses and private media are deliberately excluded from offline caching.

• Production deployment, CI/CD, backups, monitoring, and transactional email
• Optional OAuth providers
• Location tracking when compatible livestock tags are available
• Native mobile applications if PWA usage demonstrates a clear need
• Livestock knowledge assistant after the core operational product is mature

Read AGENTS.md for repository structure, coding standards, testing expectations, and pull-request guidance. Keep changes focused, include tests for new backend behavior, and include screenshots for visible UI changes.

Do not report sensitive vulnerabilities through a public issue. Share them privately with the repository owner. This project is still preparing for production deployment and should not be exposed publicly without secure settings, HTTPS, backups, and reviewed infrastructure.

No open-source license has been selected. Unless a license is added, all rights are reserved by the repository owner.