Poultry FieldOps is a mobile-first field operations platform for broiler production. It connects farm workers and field technicians around the flock lifecycle, replacing scattered paper records and operational messages with structured, auditable data.
The current release deliberately prioritizes the two workflows that are best understood from field experience: the farm worker's routine and the technician's portfolio of farms. The manager area remains limited until reporting and management requirements are validated.
- daily mortality and cull record;
- explicit zero recording, distinct from a missing submission;
- scheduled weight measurements;
- feed delivery registration;
- silo stock update by estimated kilograms or visible silo layer;
- problem reporting with four subjects: birds, feed, equipment, or other;
- optional photo and audio attachments;
- role-specific navigation;
- offline daily-record queue through IndexedDB.
- consolidated portfolio of assigned farms;
- total active flocks and estimated live birds under responsibility;
- cumulative mortality and culls across the portfolio;
- oldest, youngest, and heaviest active flocks;
- priority queue for missing records, open reports, overdue work, feed risk, and mortality changes;
- complete farm and flock history;
- flock registration with origin and placement data;
- scheduled technical work, visits, necropsies, and swab collection;
- feed stock monitoring and formal feed requests;
- occurrence responses and follow-up history.
The flock is the main operational aggregate. Its page includes:
- farm, poultry house, responsible users, sex, genetic line, and placement;
- breeder farm, breeder flock, hatchery, transport, and arrival data;
- daily mortality and culls;
- cumulative mortality count and percentage;
- estimated birds remaining;
- weight history and daily weight gain calculations;
- feed deliveries and stock snapshots;
- occurrences, technical diary, visits, necropsies, swab collections, and schedule;
- withdrawals, closeout, and inter-flock sanitary tasks;
- auditable timeline.
- A daily record contains only mortality and culls.
- Weight measurement, feed, and problem reporting are separate flows.
- Farm workers do not classify the urgency of a problem.
- Technicians monitor worker activities but do not execute routine weighing or daily records.
- Feed stock may be informed by visible silo layer. The resulting weight is explicitly an estimate based on the registered silo capacity and layer count.
- Transport mortality is stored separately from post-placement flock mortality.
- Missing values, recorded zeroes, estimates, and confirmed values are not treated as equivalent.
- The application assists professionals; it does not diagnose or prescribe.
Vue 3 PWA
│
▼
FastAPI modular monolith
│
├── PostgreSQL
├── PostgreSQL transactional outbox worker
├── S3-compatible object storage
└── Meta WhatsApp Business Platform adapter
The repository is a monorepo. The backend remains a modular monolith because the current scale does not justify distributed transactions, independent service deployments, or additional operational infrastructure.
- Python 3.12
- FastAPI
- Pydantic v2
- SQLAlchemy 2
- PostgreSQL and asyncpg
- Alembic
- Pytest
- Ruff
- mypy
- Vue 3
- TypeScript
- Vite
- Pinia
- Vue Router
- PWA
- IndexedDB
- Vitest
- Playwright
- Docker Compose
- MinIO for local object storage
- Nginx
- GitHub Actions
poultry-fieldops/
├── apps/
│ ├── api/
│ └── web/
├── docs/
├── infra/
├── scripts/
├── docker-compose.yml
├── Makefile
└── README.md
Requirements:
- Docker Desktop with Docker Compose;
- ports
5173,8000,5432,9000, and9001available.
Create the local environment file:
Copy-Item .env.example .envBuild and start the stack:
docker compose up --build -dLoad the demonstration data:
docker compose run --rm api poultry-fieldops-seedInspect the services:
docker compose psOpen:
- Web application:
http://localhost:5173 - OpenAPI:
http://localhost:8000/docs - API readiness:
http://localhost:8000/health/ready - MinIO console:
http://localhost:9001
The migration service is expected to finish and exit with status code 0. The worker uses its own heartbeat health check and does not expose an HTTP server.
All local demonstration accounts use:
FieldOpsDemo!2026
| Profile | |
|---|---|
| Farm worker | worker@example.com |
| Field technician | technician@example.com |
| Manager — limited view | manager@example.com |
| Organization administrator | admin@example.com |
Additional seeded workers use worker2@example.com through worker8@example.com.
All demonstration data is fictitious. Demonstration credentials must never be reused in a deployed environment.
- Sign in as
worker@example.com. - Submit today's mortality and cull values, including zero when applicable.
- Register a scheduled weight measurement.
- Open the feed area and update the silo by layer.
- Register a feed arrival.
- Report a problem under one of the four available subjects.
- Sign in as
technician@example.com. - Review total farms, active flocks, estimated birds, mortality, and culls.
- Open a priority farm and inspect the flock timeline.
- Review missing records and worker weighing tasks.
- Open the feed center and create a formal feed request.
- Respond to an occurrence and record the follow-up.
Production integration targets the official Meta WhatsApp Business Platform. The fake provider exists only for local development and automated tests.
Supported deterministic messages include:
mortalidade hoje 10 aves
ontem morreram 7 no galpão 2
refuguei 2 hoje
peso médio hoje 1036 gramas, pesei 100 aves
estoque de ração 4200 kg
o silo está na camada 4
chegou 6 toneladas da ração inicial ontem
preciso de ajuda
Ambiguous messages are not written as confirmed operational data without confirmation.
cd apps/api
uv sync --extra dev --locked
uv run ruff check src tests alembic
uv run ruff format --check src tests alembic
uv run mypy src/poultry_fieldops
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run pytest -p pytest_asyncio.plugincd apps/web
npm ci
npm run lint
npm run typecheck
npm run test
npm run build- The manager workflow is intentionally limited pending domain validation.
- Silo layer conversion is an estimate; calibration by silo model or measured history is a future improvement.
- Feed depletion estimates require sufficient stock history and remain labeled as estimates.
- The Meta adapter requires official credentials and webhook configuration before real messages can be sent or received.
- Necropsy and medication records store professional decisions but do not generate diagnosis or treatment recommendations.
- The current project is a demonstration MVP, not a validated commercial deployment.
This is an independent project inspired by general operational problems in integrated poultry production. It was not developed for a specific company and does not contain real farm, employee, sanitary, or corporate data.
The application does not notify government agencies and does not send operational messages to unregistered third parties.
- Product requirements
- Domain model
- Architecture
- Manual test plan
- Validation report
- First GitHub publication
See LICENSE.