How creamymilk/agrobank works
Project Type and Purpose
• This is a Go-based backend service (“monolith”) that powers Agrobank’s core banking features for farmers and merchants.
• It provides: user registration/login, wallet deposits/payments, escrow for orders, machine listings, product/store browsing, and MPESA integration.
Main Components
a. API Layer (router + server.go)
– Exposes HTTP endpoints:
• /auth (login, registration)
• /store (categories, products, search)
• /wallet (deposit, balance)
• /purchase (order creation → escrow)
• /callback (MPESA STK callbacks)
• /machines (machine listings)
– Routes requests into domain modules.
b. Domain Modules (business logic)
– auth (login.go, registration.go)
– store (category.go, product.go, search.go)
– wallet (wallet.go, deposits.go)
– deposit (deposit.go)
– escrow (buyers.go, settlement.go, getOrder.go)
– machinary (machinay.go)
– mpesa (api.go, mpesa.go, utils.go, models.go)
– firenotifier (notifier.go)
c. Persistence
– Postgres Database
– database/connect.go establishes the DB connection
– database/models/*.go define ORM models for users, wallets, transactions, products, categories, escrow, etc.
– sqlmagic folder holds migration scripts and SQL reference docs.
d. External Services
– MPESA payment gateway (STK push, callbacks)
– Firebase (for push notifications via firenotifier)
e. Utilities
– utils/number_formater.go for formatting
– g.sh for common shell commands
Relationships & Data Flows
• Client → API Layer → Domain Module → Database
• Purchase flow:
1. Client calls /purchase
2. purchaseHandler → escrow.go to lock funds
3. escrow calls mpesa/api.go to initiate STK push
4. MPESA callback arrives at /callback → stkPushCallback.go
5. escrow/settlement.go finalizes transaction and releases funds
6. firenotifier sends a notification
• Deposit flow:
1. Client → /wallet/deposit → deposit.go
2. deposit.go → mpesa/api.go
3. callback → deposit reconciler updates wallet
• Store & Machine catalogue:
– Client reads categories/products via store package (DB reads)
– Machines via machinary package
Architectural Patterns & Principles
• Layered architecture:
– Presentation/API layer (router)
– Business logic (domain modules)
– Data access (database package + models)
• Single-binary deployment: all modules compiled into one Go service
• Separation of concerns: each domain feature lives in its own package
• External integration isolation: mpesa and firenotifier packaged separately
Final Checklist
– Optionally, annotate key sequence flows (purchase, deposit) as numbered steps.