A full-stack ERP platform for poultry farm operations, sales, inventory, HR, assets and double-ledger finance.
AMAS FARM Management System replaces scattered paper and spreadsheet records with one connected platform. Farm activity, sales, purchasing, stock, payroll, assets and accounting all share one database and one ledger. A payment recorded in one module shows up in the finance reports without any manual re-entry.
The system has a role-based React dashboard and an asynchronous FastAPI backend on PostgreSQL. It is organised as seven subsystems, and each one has its own models, repositories, services and routers.
- Houses and flocks lifecycle management
- Daily feed, production (eggs), mortality, vaccination and medication records
- Consolidated farm performance report
- Customers and suppliers
- Sales and purchases with partial-payment tracking
- Operating expenses with payment history
- Product catalogue and categories
- Stock movements (in, out, adjustments) with a live inventory status view
- Unified ledger of financial accounts (cash, bank, mobile money) and transactions
- Receivables and payables (debts) tracking
- Trial balance, profit and loss, cash flow and balance sheet
- Finance dashboard with key indicators
- Employee records
- Payroll generation and payroll payments
- Asset register with purchase and payment tracking
- User and role management
- Operations report that combines data across all subsystems
- English and Swahili interface (i18n)
+--------------------+ REST / JSON +----------------------------+
| React 18 (Vite) | <---------------------> | FastAPI (async) |
| Role-based UI | JWT Bearer auth | Router > Service > Repo |
| i18n (EN / SW) | +-------------+--------------+
+--------------------+ |
SQLAlchemy 2 (asyncpg)
|
+------------v-------------+
| PostgreSQL 15 |
| Alembic migrations |
+--------------------------+
The backend follows a layered design:
| Layer | Responsibility |
|---|---|
| Router | HTTP endpoints, request validation, role checks |
| Schemas | Pydantic models for input and output contracts |
| Service | Business rules and transaction orchestration |
| Repository | Database access through SQLAlchemy |
| Models | ORM entities |
Every payment (expense, payroll, asset purchase) runs inside one atomic database transaction:
- Validate the amount against the remaining balance, and check the account exists and has sufficient funds.
- Insert the domain payment record, such as
PayrollPayment,ExpensePaymentorAssetPayment. - Update the parent record's
amount_paidand recalculate its status (UNPAID,PARTIAL,PAID). - Insert the matching
FinancialTransactioninto the ledger. - Commit, or roll everything back on any failure.
This keeps the ledger consistent even when a request fails halfway through.
Authentication uses JWT with Argon2 password hashing. The ten roles are admin, finance_manager, Farm Manager, Farm Worker, hr_manager, hr_officer, inventory_admin, sell_manager, sell_officer and asset_manager. Access is enforced on the API, and the frontend only shows the routes and menu items each role may use.
| Area | Technologies |
|---|---|
| Backend | Python 3.11, FastAPI, SQLAlchemy 2 (async), asyncpg, Pydantic, Alembic |
| Security | JWT (PyJWT), Argon2 (pwdlib), CORS configuration |
| Database | PostgreSQL 15 |
| Frontend | React 18, Vite, React Router, Axios, Bootstrap 5 (Volt dashboard theme), Recharts, Chartist |
| UX | i18next (English / Swahili), SweetAlert2, printable reports |
| DevOps | Docker, Docker Compose |
AMAS-FARM-Management-System/
|-- backend/
| |-- app/
| | |-- api/v1/
| | | |-- farm/ # houses, flocks, feed, production, mortality, health
| | | |-- pos/ # customers, suppliers, sales, purchases, expenses
| | | |-- inventory/ # products, categories, stock movements
| | | |-- finance/ # accounts, transactions, statements, dashboard
| | | |-- hr/ # employees, payroll
| | | |-- assets/ # assets and asset payments
| | | |-- reports/ # cross-module operations report
| | | `-- user/ # users and roles
| | |-- auth/ # login, JWT, role guards
| | `-- core/ # config, database, security, role seeding
| |-- migrations/ # Alembic
| `-- dockerfile
|-- frontend/
| `-- src/
| |-- pages/ # farm, pos, inventory, finance, hr, admin, reports
| |-- components/ # navbar, sidebar, layout
| |-- context/ # authentication context
| `-- api/ # Axios client and API helpers
|-- docs/ # database, API and module documentation
`-- docker-compose.yml
- Docker and Docker Compose
- Node.js 18 or later (for the frontend)
git clone https://github.com/<your-username>/AMAS-FARM-Management-System.git
cd AMAS-FARM-Management-SystemCreate a .env file in the project root:
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change_me
POSTGRES_DB=amas_farm
SECRET_KEY=replace_with_a_long_random_string
ALGORITHM=HS256
CORS_ORIGINS=http://localhost:5173docker compose up --build- API: http://localhost:8000
- Interactive API docs (Swagger UI): http://localhost:8000/docs
Apply the database migrations:
docker compose exec backend alembic upgrade headcd frontend
npm install
npm run devThe app is served at http://localhost:3000.
Detailed documentation lives in the docs folder:
- Database architecture and the ER diagrams
- API reference
- Frontend notes
- Finance subsystem flow
- Development setup
- Designing a large relational schema (farm, commerce, HR, assets and accounting) and evolving it with migrations
- Building a layered, fully asynchronous REST API in FastAPI
- Maintaining ledger integrity with atomic transactions and payment-status state tracking
- Implementing authentication and fine-grained role-based authorization on both API and UI
- Producing financial statements (trial balance, P&L, cash flow, balance sheet) from transactional data
- Delivering a localised, role-aware React interface
- Containerising the stack for reproducible local setup
Released under the MIT License. See LICENSE for details. The frontend is based on the open source Volt React Dashboard template by Themesberg (MIT).
More detailed documentation will be added as the project develops.
===THIS README WAS DURING DEVELOPMENT WERE GOING TO CHANGE IY SOON ===