A modern, mobile-first agricultural marketplace bridging smallholder farmers and commercial agricultural producers with individual buyers and bulk institutions.
- Overview
- Key Features & Capabilities
- Tech Stack
- Project Architecture & Directory Structure
- Environment Configuration (.env)
- Getting Started & Local Development
- M-Pesa STK Push Setup & Testing
- WebSocket Protocol & Event Reference
- REST API Endpoints Reference
- Production Deployment
- License
AgroMarket solves the traditional friction in agricultural commodity trading by establishing a direct, transparent pipeline between farmers and buyers. It eliminates exploitative intermediaries, provides real-time fair pricing, guarantees quality through admin product moderation, and provides instant mobile checkout with Safaricom M-Pesa STK push and real-time payment reconciliation.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ BUYER │ │ AGROMARKET │ │FARMER/SELLER │
│ ──────────── │ │ ──────────── │ │ ──────────── │
│ Browse Crops │ ──────> │ Marketplace │ <────── │ List Produce │
│ STK Checkout │ ──────> │ Escrow/Order │ ──────> │ Bulk Orders │
│ Live Tracking│ <────── │ /ws Realtime │ <────── │ Chat / Payout│
└──────────────┘ └──────────────┘ └──────────────┘
- Small Purchases (Retail / Household): Buy in standard retail units (e.g., kg, bunches, bags) with instant cart calculation and full settlement.
- Bulk Purchases (B2B / Commercial / Institutional): Buy at discounted wholesale rates with minimum quantity thresholds.
- Split Payment Workflow (Deposit & Balance):
- Buyers can place bulk orders by paying a 50% commitment deposit upfront via M-Pesa STK Push.
- The remaining 50% balance is settled upon delivery and physical inspection.
Modeled after enterprise fintech standards:
- OAuth 2.0 In-Memory Token Caching: Tokens are cached for ~55 minutes, preventing Daraja rate-limiting and optimizing latency.
- Support for Paybill & Till Numbers:
CustomerPayBillOnlinefor Paybill business shortcodes.CustomerBuyGoodsOnlinefor Till Numbers / Buy Goods.
- Smart Phone Number Sanitization: Automatically normalizes standard Kenyan phone formats (
07...,01...,+254...,254...). - Complete Audit Trail (
stk_push_responses): Logs every initiated STK prompt withCheckoutRequestID,MerchantRequestID, amounts, raw callbacks, and result statuses. - Built-in Mock Simulation Mode: Automatic local fallback for offline development or testing without live Daraja credentials.
Mounted on /ws with bi-directional JSON messaging:
- Instant Payment Confirmation (
payment.status): Immediately updates the buyer's checkout screen and order tracking timeline the exact millisecond Safaricom processes the M-Pesa PIN. - Live Order Status Broadcasting (
order.status): Real-time notifications when orders transition betweenplaced,approved,packed,shipped, anddelivered. - Direct Peer-to-Peer Messaging: Real-time chat between buyers and farmers regarding crop conditions, custom bulk agreements, and delivery logistics.
- Multi-Device Session Sync: Intelligently routes messages across multiple active browser tabs or mobile sessions for the same user.
- Automated Payout Splitting: When an order contains items from multiple farmers, the system splits and calculates each supplier's payout ledger automatically.
- Payout Preferences: Farmers can configure preferred disbursement channels:
- M-Pesa Mobile Money (Phone Number)
- Bank Transfer (Bank Name & Account Number)
- PayPal (Email Address)
- Admin Clearance Portal: Dedicated administrator view to review, approve, and disburse pending supplier payouts.
- Buyer: Marketplace exploration, advanced filters, cart management, checkout with M-Pesa STK/Stripe, live order tracking, chat with sellers.
- Seller (Farmer): Product listing creation, harvest date scheduling, bulk pricing tiers, earnings analytics, order fulfillment, payout settings.
- Admin: Quality control & product verification, user role governance, platform metrics, supplier payout approvals.
- Framework: React 18 + TypeScript + Vite
- Routing: Wouter (Ultra-lightweight client-side router)
- Server State & Caching: TanStack React Query v5
- Client State: Zustand (Persistent authentication store)
- UI & Component System: shadcn/ui + Radix UI primitives
- Styling: Tailwind CSS +
tailwindcss-animate - Icons & Visuals: Lucide React + React Icons
- Runtime: Node.js 20+ (ES Modules)
- Framework: Express.js with TypeScript
- Database & ORM: PostgreSQL + Drizzle ORM
- Real-Time Engine: ws (Native WebSocket Server)
- Authentication: JWT (JSON Web Tokens) with OTP email verification
- File Uploads: Multer with static disk storage
- Mobile Payments: Safaricom Daraja API (Lipa Na M-Pesa Online STK Push, Query, Callbacks)
- Card Payments: Stripe API (Checkout Sessions & Webhooks)
- SMS & Alerts: Twilio & Africa's Talking
AgroMarket/
├── client/ # Frontend React SPA
│ ├── public/ # Static assets, logos, and uploads
│ └── src/
│ ├── components/ # Reusable UI components & dialogs
│ │ ├── ui/ # shadcn/ui base primitives (button, card, dialog, etc.)
│ │ ├── Header.tsx # Navigation header with cart badge
│ │ ├── MobileNav.tsx # Mobile responsive bottom navbar
│ │ └── OrderTrackingTimeline.tsx # Visual stepper for order stages
│ ├── hooks/ # Custom React hooks
│ │ ├── useAuth.ts # Authentication convenience hook
│ │ ├── usePaymentSocket.ts # Real-time M-Pesa & order WebSocket subscriber
│ │ └── use-toast.ts # Interactive notification toast hook
│ ├── lib/ # API client, axios interceptors, query client
│ ├── pages/ # Application views / routes
│ │ ├── auth/ # Login, Register, VerifyOtp
│ │ ├── AdminDashboard.tsx # Product approvals & payout clearance
│ │ ├── SellerDashboard.tsx # Farmer inventory, earnings, and listings
│ │ ├── Cart.tsx # Shopping cart & STK push checkout modal
│ │ ├── OrderTracking.tsx # Live order progress & receipt verification
│ │ ├── ProductDetail.tsx # Single product with bulk pricing options
│ │ └── Chat.tsx # Real-time WebSocket messaging interface
│ ├── store/ # Zustand global state (authStore)
│ └── App.tsx # Root router & layout wrapper
│
├── server/ # Backend Express API & WebSocket Server
│ ├── services/
│ │ └── mpesa.ts # Enterprise MpesaService (Daraja STK push & callbacks)
│ ├── db.ts # PostgreSQL Drizzle database connection
│ ├── index.ts # HTTP and WebSocket server entry point
│ ├── routes.ts # REST API endpoints & webhook controllers
│ ├── socket.ts # WebSocket connection registry & event broadcasting
│ ├── storage.ts # Database repository / access layer
│ └── vite.ts # Development Vite SSR / proxy integration
│
├── shared/
│ └── schema.ts # Drizzle database tables, relations, and Zod schemas
│
├── scripts/
│ └── seed_admin.ts # Admin user database seeder
│
├── drizzle.config.ts # Drizzle Kit migration configuration
├── package.json # Dependencies and project scripts
├── tailwind.config.ts # Tailwind CSS design system tokens
└── tsconfig.json # TypeScript compiler configuration
Create a .env file in the root directory:
# ==============================================================================
# DATABASE CONFIGURATION
# ==============================================================================
DATABASE_URL=postgres://appuser:apppassword@localhost:5432/agromarket?sslmode=disable
# ==============================================================================
# SERVER & SECURITY
# ==============================================================================
PORT=8010
JWT_SECRET=agro-market-super-secret-key-1234
NODE_ENV=development
STANDALONE_API=true
# ==============================================================================
# SAFARICOM DARAJA M-PESA CONFIGURATION
# ==============================================================================
MPESA_ENV=sandbox # 'sandbox' or 'production'
MPESA_ACCOUNT_TYPE=till # 'till' (Buy Goods) or 'paybill'
MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_SHORTCODE=174379 # Business Shortcode (or 174379 for Sandbox)
MPESA_TILL_NUMBER=174379 # Online Till Number (used when ACCOUNT_TYPE=till)
MPESA_PASSKEY=bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
MPESA_CALLBACK_URL=https://your-domain.ngrok-free.app/api/payments/mpesa/callback
MPESA_MOCK_MODE=false # Set to 'true' to force mock mode in dev
# ==============================================================================
# STRIPE PAYMENTS (CARD CHECKOUT)
# ==============================================================================
STRIPE_PUBLISHABLE_KEY=pk_test_placeholder
STRIPE_SECRET_KEY=sk_test_placeholder
STRIPE_WEBHOOK_SECRET=whsec_placeholder
# ==============================================================================
# SMS & NOTIFICATIONS (OPTIONAL)
# ==============================================================================
TWILIO_ACCOUNT_SID=placeholder_sid
TWILIO_AUTH_TOKEN=placeholder_token
TWILIO_PHONE_NUMBER=placeholder_phone
AFRICAS_TALKING_USERNAME=sandbox
AFRICAS_TALKING_API_KEY=placeholder_api_key- Node.js: v20.x or higher installed (Download Node.js)
- PostgreSQL: v14+ running locally or a hosted instance (Neon, Supabase, AWS RDS)
- Git
Clone the repository and install all dependencies:
git clone https://github.com/Timothy970/AgroMarket.git
cd AgroMarket
npm installEnsure PostgreSQL is running and your DATABASE_URL is set in .env.
To push schema changes directly to your PostgreSQL database:
npm run db:pushOr generate and execute formal migration files:
npm run db:migrateSeed default admin and test records into the database:
npm run db:seed-adminStart both the Express Backend API (Port 8010) and Vite Frontend Dev Server (Port 5173) concurrently:
npm run devOpen your browser and navigate to:
👉 http://localhost:5173
- Register for an account on the Safaricom Developer Portal (Daraja).
- Create a new Sandbox App and enable Lipa Na M-Pesa Online.
- Copy your
Consumer KeyandConsumer Secretto.env. - The default sandbox shortcode is
174379with the official sandbox passkey:bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
Because Safaricom Daraja needs a publicly reachable HTTPS endpoint to deliver callback webhooks:
- Start an ngrok tunnel pointing to your backend port:
ngrok http 8010
- Copy the generated forwarding HTTPS URL and update
.env:MPESA_CALLBACK_URL=https://abc123.ngrok-free.app/api/payments/mpesa/callback
If you do not have live Daraja credentials configured (or leave placeholders in .env), the system automatically activates Mock Mode:
- You can enter any Safaricom phone number in checkout.
- The server will acknowledge the request with simulated IDs.
- After 3 seconds, a realistic Safaricom callback will execute automatically, triggering database reconciliation and broadcasting real-time WebSocket confirmation.
AgroMarket exposes a unified WebSocket server at ws://localhost:8010/ws (or wss://<domain>/ws).
Upon connecting, clients send an auth frame:
{
"type": "auth",
"token": "<JWT_ACCESS_TOKEN>"
}To subscribe to a specific order's live updates:
{
"type": "subscribe_order",
"orderId": "3b29c0b1-1234-4567-8901-abcdef012345"
}Emitted as soon as an M-Pesa STK callback arrives or is simulated:
{
"type": "payment.status",
"event": "payment.status",
"channel": "payments.user-uuid",
"data": {
"orderId": "order-uuid",
"checkoutRequestId": "ws_CO_123456789",
"status": "success",
"message": "Payment received successfully via M-Pesa",
"amount": 2500,
"receipt": "NL29X8YZ01",
"phoneNumber": "254712345678",
"timestamp": "2026-09-11T12:00:00.000Z"
}
}Emitted when an order stage updates:
{
"type": "order.status",
"event": "order.status",
"orderId": "order-uuid",
"data": {
"orderId": "order-uuid",
"status": "approved",
"message": "Order payment confirmed",
"timestamp": "2026-09-11T12:00:00.000Z"
}
}{
"type": "message",
"message": {
"id": "msg-uuid",
"senderId": "user-1",
"receiverId": "user-2",
"productId": "product-uuid",
"content": "Hello, is the harvest ready for pickup?",
"createdAt": "2026-09-11T12:00:00.000Z"
}
}POST /api/auth/register— Request OTP for user registration.POST /api/auth/login— Request OTP for login.POST /api/auth/verify— Verify OTP and receive JWT access token.GET /api/auth/me— Retrieve current authenticated user profile.PUT /api/auth/profile— Update user profile & payout preferences.
GET /api/categories— List all active product categories.POST /api/categories— Create category (Admin).GET /api/products— Browse approved products with filters (category,search,minPrice,maxPrice,location).GET /api/products/:id— Get product detail with bulk tiers.POST /api/products— Create new product listing (Seller).PUT /api/products/:id— Update listing (Seller).DELETE /api/products/:id— Remove listing (Seller).GET /api/products/seller/mine— Get seller's own products.PATCH /api/products/:id/approval— Moderate/Approve product (Admin).
GET /api/cart— Get user's cart items with pricing & totals breakdown.POST /api/cart— Add product to cart with purchase mode (smallorbulk).PUT /api/cart/:id— Update cart item quantity.DELETE /api/cart/:id— Remove single item from cart.DELETE /api/cart— Clear entire cart.
POST /api/orders— Create new order with item snapshots.GET /api/orders— List user's order history.GET /api/orders/:id— Get detailed order summary & tracking timeline.PATCH /api/orders/:id/status— Update status (approved,shipped,delivered).PATCH /api/orders/:id/payment— Update payment flags (depositPaid,balancePaid).
POST /api/payments/mpesa/stkpush— Initiate Lipa Na M-Pesa STK Push.POST /api/payments/mpesa/callback— Daraja STK webhook receiver.GET /api/payments/mpesa/query/:checkoutRequestId— Query Daraja STK transaction status.POST /api/payments/stripe/create-checkout-session— Create Stripe card checkout session.POST /api/payments/stripe/webhook— Stripe webhook receiver.
GET /api/supplier-payouts— View supplier payout ledger (Admin / Seller).PATCH /api/supplier-payouts/:id/approve— Approve payout amount (Admin).POST /api/supplier-payouts/:id/pay— Mark payout as disbursed (Admin).
GET /api/chat/conversations— List active user chat conversations.GET /api/chat/messages/:receiverId— Fetch chat history with specific user.
npm run buildThis compiles the Vite frontend into dist/public and bundles the Express server into dist/index.js.
npm run db:migratenpm startThe server will bind to process.env.PORT (default 8010) and serve both the REST API and the static React production client.
This project is licensed under the MIT License — see the LICENSE file for details.