Module 2
Farmer Registry
Purpose#
Creates and maintains a verified, deduplicated record for every farmer in the organisation. The farmer record is the central entity in SMS — farms, compliance status, program attendance, and survey responses all reference it. It is also the shared data foundation for PMS Phase 2.
Enrollment wizard#
Enrollment is a multi-step wizard available on both web and mobile (offline-capable on mobile). Steps:
- 1.Personal details — name, date of birth, gender, national ID type and number, photo.
- 2.Household — household size, education level, years farming, primary/secondary crops.
- 3.Area assignment — select community from the geographic hierarchy.
- 4.Payment settings — MoMo number, E-zwich ID, or cash preference.
- 5.Review — summary of all entered data before submission.
- 6.Submit — farmer record created, unique farmer code assigned.
Duplicate detection#
| Type | Trigger | Action |
|---|---|---|
| Hard block | Exact national ID match | Registration rejected — farmer already exists in the organisation. |
| Soft warning | Same name + date of birth (fuzzy) | Officer is warned and must confirm it is a different person. |
| Soft warning | Same phone number | Officer is warned. Shared phones are common in field; confirmation required. |
Status lifecycle#
| Status | Description |
|---|---|
| Pending | Registration submitted but not yet reviewed by district manager. |
| Active | Approved and operational. Can be assigned to farms, programs, surveys. |
| Inactive | Temporarily disabled. Can be reactivated. |
| Suspended | Access restricted pending investigation. |
| Blacklisted | Permanently barred. Cannot be reactivated. |
Payment settings#
Payment channels captured at enrollment and used by PMS when processing purchase disbursements:
| Channel | Fields captured |
|---|---|
| Mobile Money (MoMo) | Phone number, network (MTN, Vodafone, AirtelTigo) |
| E-zwich | E-zwich card number |
| Cash | No additional fields — flagged as cash disbursement |
Bulk CSV import#
Organisations can import existing farmer lists via CSV. The import flow: download template → populate → upload → validation report → confirm and apply. Duplicate detection runs against the full existing farmer base during import. Rows that fail hard-block checks are rejected; soft warnings are flagged for review.
Farmer Card#
Each enrolled farmer can have a printable Farmer Card generated — includes name, photo, farmer code, and a QR code that encodes the farmer code for mobile scanner use during purchase transactions in PMS.
Packages#
| Package | Type | Key services / hooks |
|---|---|---|
@repo/feature-farmer-registry | Backend | farmer, farmer-code, farmer-status, duplicate-detection, audit-trail, bulk-import, photo, template-options |
@repo/feature-farmer-registry-web | Frontend | EnrollmentWizard, FarmerTable, FarmerDetail, BulkImport; hooks: useFarmers, useFarmerDetail, useFarmerSearch, useBulkImport, useOperationalAreas |
Audit trail#
Every change to a farmer record (status transition, field edit, deactivation) creates an immutable audit trail entry scoped to the farmer. The audit trail is viewable by District Managers and above.