🌾 GoldLeaf Farm Management Platform

1. Platform Overview

GoldLeaf is a complete farm management platform with two interfaces that share the same data:

2. Admin Portal Guide

Access at https://api.goldleaflabs.co.ke/. The admin portal has 16 sections accessible from the left sidebar.

2.1 Login & Demo Mode

Normal Login: Enter your email and password, then click Sign In. If 2FA is enabled, enter the OTP sent to your registered phone.

Demo Mode: Add ?demo=jonathan to the URL to bypass login and explore the portal with sample data. Example: https://api.goldleaflabs.co.ke/?demo=jonathan. A yellow banner at the top confirms Demo Mode is active.

2.2 Dashboard

The first page you see after login. It shows a wallet card for Ethereum blockchain integration:

• Ethereum Account — Network, RPC URL, Wallet Address, ETH Balance, and Status indicator
• The wallet is used for blockchain record-keeping (batch tracking, certification)

Below the wallet, the dashboard used to display stats cards (Total Farmers, Total Farms, etc.) — these have been moved to the Statistics page.

2.3 Farmers

Manage all registered farmers. This is the main tool for reviewing and approving farmer accounts.

What you see:

• Search bar — Type a name, email, or phone to filter the list
• Farmers table — Columns: Name, Email, Phone, Region, Farm, Status, Action
• Status badges — Color-coded: Active (green), Verified (blue), Registered (yellow), Rejected (red)
• Pagination — Browse through pages of farmers

Review Button (Action column): Click to open the farmer review modal:

• Farmer Info — Name, Email, Phone, ID Number, Region, District, number of Farms and Crops
• Current Status — Shown as a color badge
• Change Status dropdown — Select: Registered, Verified, Active, or Rejected
• Review Notes — Optional text field for admin comments
• Save Status — Click to update the farmer's status. The list refreshes automatically

2.4 Farms

View all registered farms across all farmers.

What you see:

• Search bar — Search by farm name or farmer
• Farms table — Farm Name, Farmer, Land Size (ha), Status, Actions
• View button (eye icon) — Opens the Farm Details modal

Farm Details Modal (comprehensive view):

• Farm Info card — Name, Location (village/district/region from GPS), Size, Type (e.g. Mixed, Horticulture), Soil Type, Status
• Farmer card — Farmer Name, Phone, Email, Region
• Tasks summary — First 5 tasks with title, status, due date
• Crops Planted table — Crop name, variety, category, planting/harvest dates, area, status
  • Growth Stages toggle (+) — Expand to see growth stage history with dates
  • Activities toggle (+) — Expand to see activities (irrigation, fertilizing, etc.)
• Farm Boundaries map — Leaflet map showing the farm fence polygon with calculated area
• All Tasks table — Complete task list with search/filter

2.5 Map View

Geographic visualization of all farms on an interactive Leaflet map.

• Each green marker represents a farm's GPS location
• Click a marker — Opens a popup showing: Farm Name, Address (village/district/region), Farmer Name, Number of Crops
• Use the map controls to zoom in/out and pan

2.6 Crop Master

The central catalog of all crop types that farmers can plant.

• Add Crop button — Opens a modal to add a new crop type: Name, Scientific Name, Category, Growing Period (days), Water Requirement, Image URL
• Search bar — Filter crops by name
• Crops table — Name, Scientific Name, Category, Growing Period, Water, Actions (Edit/Delete)
• Edit (pencil icon) — Opens the crop modal pre-filled with that crop's data
• Delete (trash icon) — Removes the crop type from the catalog

2.7 Field Officers

Manage field officers who oversee farms and verify data on the ground.

• Add Officer button — Opens modal: Name, Phone, Region, County (Kenyan counties dropdown), Status (Active/Inactive)
• Officers table — Name, Phone, Region, County, Status, Actions
• Edit and delete officers as needed

2.8 Lab Results & Batches

Two tabs under this section: Lab Tests and Batches.

Lab Tests Tab

• New Lab Test button — Opens modal: Farm (select from dropdown), Batch (optional), Test Type (Soil/Water/Product/Pesticide/Nutritional/Other), Test Date, Lab Name, Results/Notes, Status (Sample Collected / In Progress / Analysis Done / Reviewed / Completed / Failed)
• Lab Tests table — Farm Name, Batch Code, Test Type, Lab Name, Test Date, Status, Actions
• Edit and delete lab tests as needed

Batches Tab

• Batches table — Batch Code, Farm Name, Quantity, Harvest Date, Status (Confirmed/Pending), Quality (Premium/Standard), Actions
• Lab button (flask icon) — Opens modal showing all lab tests linked to that batch with quality parameters

2.9 Pipeline Stages

Configure the crop growth pipeline stages. These define the stages a crop passes through from planning to harvest.

• Add Stage button — Opens modal: Name, Stage Key (unique identifier like SEED_PREPARATION, PLANTING), Sort Order (numeric), Color (hex), Description
• Checkboxes:
  • Harvest stage — When checked, crops at this stage can have batches created
  • Terminal stage — When checked, no further advancement is possible (Completed/Failed)
• Pipeline table — Order, Stage Key, Name, Color preview, Harvest flag, Terminal flag, Actions

2.10 Growth Pipeline (Kanban)

Visual kanban board showing all crops organized by their current pipeline stage. Drag-and-drop is not supported — click the Advance button to move a crop forward.

• Search bar — Filter crops by name
• Stage columns — Each pipeline stage is a column (e.g., Seed Preparation, Planting, Germination, etc.) with crop cards inside
• Crop cards — Show crop name, variety, planted date, days in stage
• Advance button — Moves the crop to the next stage. The stage-to-status mapping is: Seed Preparation→Planned, Planting→Planted, Germination/Vegetative/Flowering/Fruiting/Maturation→Growing, Harvest→Harvested, Completed→Completed, Failed→Failed
• Harvest info button — For crops at the Harvest stage, shows a modal with batch creation options

2.11 Blockchain Records

Track each batch's lifecycle through four blockchain-recorded stages:

• HARVEST — Harvest date, quantity, crop type, farm location
• QUALITY_CHECK — Lab test results, quality parameters, grade
• SHIPMENT — Dispatch date, destination, transporter
• CERTIFICATION — Organic cert, compliance docs, audit trail
• Status: PENDING → SYNCING → CONFIRMED or FAILED
• Search bar — Search by batch code, farm, or farmer
• Blocks table — Batch Code, Farm/Farmer, Qty, Harvest date, Quality status, Shipment status, Certification status

2.12 Seasonal Plans

View all seasonal plans created by farmers across all farms. Farmers create these from the Android app.

Filter card: Narrow down by:

• Farmer — Select from dropdown (loaded from database)
• Farm — Cascading dropdown (only shows farms belonging to selected farmer)
• Season — Spring, Summer, Fall, Winter, All Year
• Event Type — Planting, Fertilizing, Harvesting, Irrigation, Pest Control, Pruning, Soil Prep, Other
• Status — Pending or Completed
• Date From / Date To — Filter by start date range
• Search — Keyword search in title and description
• Filter button — Apply filters

Table: Title, Farmer, Farm, Event Type, Season, Start Date, Status (color badge), Last Synced

2.13 Compliance Checklist

View all compliance checklist items created by farmers. Tracks regulatory and certification requirements.

Filter card:

• Farmer / Farm — Cascading dropdowns
• Category — Certification, Safety, Environmental, Quality, Labor, Other
• Status — Compliant, Non-Compliant, Pending, N/A
• Date From / Date To — Filter by creation date
• Search — Keyword search in item name and description

Table: Item, Farmer, Farm, Category (badge), Status (color badge), Evidence (link button if URL provided), Due Date, Last Synced

2.14 Soil Tests

View all soil test records synced from farmers' Android apps.

Filter card:

• Farmer / Farm — Cascading dropdowns
• Soil Type — Clay, Sandy, Loam, Clay Loam, Sandy Loam, Silt Loam
• Date From / Date To — Filter by test date
• Search — Keyword search in lab name and soil type

Table: Date, Farmer, Farm, Soil Type, pH, N (Nitrogen ppm), P (Phosphorus ppm), K (Potassium ppm), Lab Name

2.15 Farm Plots & Rotation

View farm subdivisions (plots/sections) created by farmers and their crop rotation history.

Filter card: Farmer, Farm, Search (plot name)

Table:

• Plot Name — With color dot indicator
• Farmer, Farm, Size, Soil Type
• Crops History button — Click to open rotation history modal showing last 10 crops planted with rotation group color coding
• Rotation column — Shows auto-calculated recommendation:
  • Green badge "Next: LEGUME" — Good rotation recommended
  • Red badge "⚠️ Same group" — Same crop family planted consecutively (warning)

Rotation History Modal:

• Lists last 10 crops planted in the plot with dates and rotation groups
• Groups color-coded: green = good rotation, red = repeated group (warning)
• Shows recommended next group from the rotation cycle

2.16 Statistics

Aggregated statistics for the entire system:

• Total Farmers — Number of registered farmers
• Total Farms — Number of farms across all farmers
• Total Crops — Number of crops planted
• Total Land Area — Sum of all farm sizes
• Total Tasks — Number of tasks created
• Active Tasks — Tasks that are not yet completed

2.17 Harvest Deliveries

Track crop deliveries from farmers. The admin confirms what was actually received versus what the farmer declared.

Flow:

1. Farmer declares harvest — Records quantity harvested in the Android app
2. Admin confirms delivery — Click "Confirm Delivery" and enter:
   • Farmer — Select from dropdown
   • Declared Qty (kg) — What the farmer reported
   • Confirmed Qty (kg) — What the admin actually received
   • Grade — Premium, Standard, or Reject
   • Date — Delivery date
   • Notes — Optional
3. System calculates: Reject = Declared − Confirmed. Shown in the table as a badge (green if 0, warning if > 0)
4. Farmer notified — A notification is created for the farmer: "Your harvest delivery of X kg has been confirmed"

Table columns: Date, Farmer, Declared, Confirmed, Reject (badge), Grade, Batch Code, Notes

Filters: Farmer dropdown

2.18 Batch Sales

Record sales of product batches to buyers. This is how trade income is tracked for calculating farmer payments.

Record Sale:

1. Click "Record Sale" button
2. Select the Batch being sold
3. Enter Buyer Name
4. Enter Quantity (kg) sold
5. Enter Unit Price (KSh/kg) — total is auto-calculated
6. Enter Date and optional Notes
7. Click Save

Table columns: Date, Batch Code, Buyer, Qty Sold, Unit Price, Total, Notes

Rate calculation: When paying farmers, the system calculates: Rate = Total Sale Amount ÷ Total Declared Kg (across all farmers for that batch). Each farmer's gross pay = Their declared Kg × Rate.

2.19 Payments & M-PESA

Initiate M-PESA payments to farmers. The system calculates the payment based on declared harvest, sale rate, and deductions.

Payment Flow:

1. Select Farmer — The system auto-loads their total declared harvest and previously paid amounts
2. Enter Rate (KSh/kg) — Automatically calculated from batch sales, but can be overridden
3. Enter Deductions — Transport costs, commission fees, sorting charges, etc.
4. Review Breakdown:
   • Gross = Declared Kg × Rate
   • Deductions = Total of all deductions
   • Net = Gross − Deductions (this is what the farmer receives)
5. Confirm M-PESA Phone — The farmer's registered M-PESA number is pre-filled
6. Click "Send via M-PESA" — The system calls the Safaricom Daraja API

Payment Statuses:

• 🟡 PENDING — Payment initiated, awaiting M-PESA confirmation
• 🟢 SUCCESS — Money sent successfully. M-PESA transaction ID recorded
• 🔴 FAILED — M-PESA rejected. Check the result description and retry

Table columns: Date, Farmer, Gross, Deductions, Net, M-PESA Phone, Status (badge), Transaction ID

Filters: Farmer dropdown, Status dropdown (All / Pending / Success / Failed)

2.20 Dashboard & Badge Counts

The admin dashboard now shows actionable alerts and summary statistics at a glance.

Dashboard Alerts:

• Pending Farmer Reviews — Yellow alert with count and "Review Now" link
• Crops Ready for Harvest — Blue alert showing crops at HARVEST stage
• Overdue Tasks — Red alert with count
• Pending Blockchain Records — Gray alert

Stat Cards:

• Pending Reviews, Ready to Harvest, Overdue Tasks, Total Paid (KSh)

Sidebar Badge Counts:

Red badges appear next to sidebar links showing counts that need attention:

• Farmers — Shows count of farmers with "registered" status (pending review)
• Payments — Shows count of pending M-PESA payments

Badges auto-refresh every 60 seconds.

3. Android App Guide

The mobile app is installed on the farmer's Android device. It works offline-first — all data is saved locally and syncs to the server.

3.1 Login & Registration

First time — Register:

1. Step 1: Enter Name, Email, Phone, and Password
2. Step 2: Enter your farm name and details
3. Step 3: Location — The app fetches your GPS coordinates automatically. You can also search for your location
4. Step 4: OTP Verification — An OTP is sent to your phone. Enter it to verify
5. Done! You are logged in and on the dashboard

Returning user — Login:

1. Enter your Email and Password
2. If your account status is Rejected, you will see "Account rejected. Contact admin."
3. If your account status is Registered, you can log in but cannot create farms or sync data until an admin approves your account
4. If your account status is Active or Verified, you have full access

Forgot Password:

1. Tap "Forgot Password" on the login screen
2. Enter your email or phone
3. Enter the OTP sent to your phone
4. Set a new password

3.2 Dashboard

The main screen after login. Contains:

• Greeting card — "Welcome, [Name]" with your farm name and role (Farmer / Verified Farmer)
• Stats overview — Quick stats: number of Farms, Crops, Tasks
• Weather summary — Current temperature and conditions. Tap to go to the full Weather screen
• Quick Action Cards (8 rows) — Tap any card to navigate:
  1. Add Farm — Register a new farm
  2. Add Crop — Add a new crop to your farm
  3. My Crops — View all your crops
  4. Crop Monitoring — Monitor growth progress
  5. Certifications — Product batch certification
  6. Quality — Quality control dashboard
  7. Farm Fencing — Draw your farm boundaries on a map (Verified Farmers only)
  8. Pest/Disease — AI-powered pest and disease detection (Verified Farmers only)
  9. Training — Agricultural training videos
  10. Seasonal Plan — Plan your farming season
  11. Compliance — Track compliance checklist items
  12. Soil Profile — View and add soil test data
  13. Farm Plots — Manage farm sections/subdivisions
  14. My Revenue — View total earnings, M-PESA payout info, and payment history
• Recent Activity — Scrollable list of recent activities and tasks
• Bottom Navigation — Switch between: Home, My Crops, Weather, Advisory (or Certification for Verified Farmers)

3.3 Farm Management

Add Farm:

1. Tap Add Farm on the dashboard
2. Enter: Farm Name, Size (acres/hectares), Soil Type
3. Get GPS Location — The app uses your phone's GPS or searches for a location by name
4. The address is automatically resolved from GPS coordinates (village, district, region, country)
5. Tap Save — The farm is created locally and synced to the server

Farm Fencing:

1. Tap Farm Fencing on the dashboard (Verified Farmers only)
2. The map shows your farm's current boundaries
3. Tap points on the map to draw or adjust the farm fence polygon
4. The area is calculated automatically
5. Save to update the boundaries

Edit Farm:

Farm details (name, GPS location, soil type) can be edited from the farm details screen. Changes are synced to the server.

3.4 Crop Management

Add Crop:

1. Tap Add Crop on the dashboard
2. Select a crop type from the Crop Master catalog
3. A plot selection dialog appears:
   • Select the Plot (section of your farm) where this crop will be planted. If you haven't created plots, you can skip this
   • A rotation recommendation may appear based on what was planted in that plot previously
4. The crop is saved and appears in your farm's crop list
5. Enter variety and field details in the crop detail screen

My Crops:

• List of all crops you have planted, grouped by farm
• Each crop shows: Name, Stage, Days since planting, Status badge
• Tap a crop to see details

Crop Details:

• Growth Pipeline slider — Shows the current stage and allows advancing to the next stage. No going backwards
• Crop info — Variety, planted date, expected harvest, area, soil type
• Rotation group — Shows which crop family this belongs to (for rotation planning)
• Log Activity button — Add a task/activity (irrigation, fertilizing, pest control, etc.)
• Track Input button — Record inputs used (seeds, fertilizer, pesticides)
• Growth Stages — Expandable history of all growth stages with dates
• Monitoring Records — Past monitoring data (soil moisture, height, etc.)

3.5 Growth Pipeline Slider

Inside Crop Details, a horizontal slider shows all pipeline stages with the current stage highlighted:

• Stages are read from the server (configured in the Admin Portal under Pipeline)
• Swipe or tap to see all stages
• The current stage has a filled dot
• Completed stages show a checkmark
• Future stages are grayed out
• Advance button — Moves the crop to the next stage (server validates forward-only)
• At the Harvest stage, you can create product batches
• Completed and Failed are terminal stages — no further advancement

3.6 Seasonal Planning

Plan your farming activities across seasons.

• Season filter tabs — All, Spring, Summer, Fall, Winter, All Year
• Month grouping — Plans are organized by month for easy viewing
• Color-coded cards — Each event type has a color: Planting=green, Fertilizing=blue, Harvesting=orange, Irrigation=cyan, Pest Control=red, Pruning=purple, Soil Prep=brown, Other=gray
• FAB (floating action button) — Add a new plan:
  • Title, Description, Event Type, Season
  • Date picker for start date
  • Optional: assign to a specific Plot
• Toggle complete — Tap the checkbox on a plan to mark it done
• Swipe to delete — Remove a plan
• All changes sync to the server automatically

3.7 Compliance Tracking

Track checklist items related to farm certifications, safety, environmental, and quality standards.

• Category filter tabs — All, Certification, Safety, Environmental, Quality, Labor, Other
• Expandable cards — Each item shows: name, description, status, due date, evidence, notes
• Status toggle chips — Tap to change status: Compliant (green), Non-Compliant (red), Pending (yellow), N/A (gray)
• Evidence dialog — Enter a URL link to supporting evidence (photo, document)
• Notes dialog — Add notes about this compliance item
• FAB — Add new compliance item: name, category, description, due date
• Changes sync to the server after each save

3.8 Soil Profile

Record and view soil test history for your farm.

• Test history list — Shows all past soil tests as cards with:
  • Date, Soil Type, Lab Name
  • pH, Nitrogen (N), Phosphorus (P), Potassium (K)
  • Organic Matter %, Moisture %
  • Notes
  • Delete button to remove old tests
• FAB or "Add Soil Test" button — Opens the add test dialog:
  • Soil Type dropdown (Clay/Sandy/Loam/Clay Loam/Sandy Loam/Silt Loam)
  • pH, N (ppm), P (ppm), K (ppm)
  • Organic Matter %, Moisture % (optional)
  • EC (dS/m) — Electrical Conductivity (optional)
  • Lab Name, Notes
• Empty state — If no tests recorded yet, shows a prompt to add the first test

3.9 Farm Plots & Rotation

Divide your farm into named sections (plots) to track what's planted where and manage crop rotation.

• Plots list — Color-coded cards showing: Plot Name, Size, Soil Type, Notes
• FAB — Add a new plot: Name, Size, Soil Type, Notes
• Delete — Remove a plot
• When adding a crop, you can assign it to a specific plot
• The rotation system tracks what was planted in each plot and warns if the same crop family is repeated

3.10 Input Tracking

Track farming inputs (seeds, fertilizer, pesticides) used for each crop.

• Access from the Track Input button on the Crop Details screen
• Input list — Shows all recorded inputs: type, quantity, date, notes
• Add Input dialog — Input name, type (Seed/Fertilizer/Pesticide/Other), quantity, unit, date, cost, notes
• Delete — Remove an input record

3.11 Advisory Services

AI-powered advisory dashboard with multiple tools.

Advisory Dashboard:

• AI Recommendations — Personalized farming recommendations generated by AI based on your farm data
• Category tabs — Disease, Pest, Soil, Weather, General
• AI Chat — Ask questions about your farm (requires API keys configured)

Pest Detection:

• Take a photo of a pest on your crop
• The app sends the image to the AI service for identification
• Receives analysis: pest name, severity, recommended treatment
• Available for Verified Farmers only

Disease Detection:

• Same as Pest Detection but for crop diseases
• Take a photo of affected leaves/fruit
• AI identifies the disease and suggests treatments

Soil Analysis:

• Enter soil parameters: soil type, pH, N, P, K, crop type
• Click "Analyze Soil" — AI generates recommendations for soil amendments, fertilization strategy, and best practices

Weather Screen:

• Current weather with temperature, humidity, wind speed
• 7-day forecast
• Weather alerts and warnings
• Data from OpenWeatherMap API

3.12 Certification & Quality

Batch Management:

• Create product batches from harvested crops
• Each batch gets a unique batch code
• Link lab test results to batches
• Request certification for batches

Batch Details:

• View batch info: quantity, harvest date, status
• View associated lab tests and quality parameters
• Print certificate for the batch

Quality Dashboard:

• Overview of quality control status
• Link to lab test records

Consumer Verification:

• Enter a batch code or scan a QR code
• View the complete verification result: batch info, harvest details, quality check, shipment, certification
• Blockchain-verified authenticity

3.13 Training & Videos

• Training Catalog — Browse agricultural training content by category
• Search and filter training materials
• Training Details — View training module description and play video
• Video Player — Full-screen video player for training content

3.14 Profile & Settings

• View your profile: name, email, phone, location
• Change Password — Update your login password
• View your user role (Farmer / Verified Farmer)
• Account status is displayed (Active / Registered / Verified / Rejected)

4. Data Flow & Sync

How data moves between the Android app and the server:

1. Farmer creates/edits data on Android — The app saves to local Room database immediately (works offline)
2. Sync upload — When internet is available, the app sends all changes to the server via POST /v1/sync/upload
3. Server processes — The PHP backend inserts/updates records in the MySQL database
4. Admin views data — The admin portal fetches data from the same MySQL database via API endpoints
5. Sync download — The Android app periodically downloads updates from the server via GET /v1/sync/download

What data is synced:

5. User Roles & Permissions

Account Status Flow:

Or if rejected by admin: 🔴 Rejected (cannot log in)

6. Troubleshooting

Android App Issues

Admin Portal Issues

Server Errors (PHP)