MkulimaForum — Agricultural Super App for East Africa
Multivendor marketplace, farmers forum, AI plant disease scanner, wallet/escrow payments, weather advisories, and admin operations — built for Tanzanian (and later EAC) smallholder farmers.
Start here: REDESIGN.md — full platform audit, redesign decisions, and phased roadmap.
Target architecture and requirements live in MkulimaForum_ Modern Agri Hub/.
Monorepo Layout
| Path | What it is | Stack |
|---|
/ (root) | Backend API | Laravel 13, Sanctum, Spatie Permission, PostgreSQL only |
mkulima_app/ | Farmer mobile app | Flutter ≥3.5, Provider, drift (offline-first), dio |
admin-dashboard/ | Legacy React admin (not served). Live staff panel is Filament at /admin | React 18, Vite, Tailwind |
MkulimaForum_ Modern Agri Hub/ | Architecture & requirements docs | — |
Backend (Laravel API)
PostgreSQL is the only supported database. Create a role and two databases
(the second is what php artisan test migrates; it must not be the application
database):
sudo -u postgres psql -c "CREATE USER mkulima WITH PASSWORD 'secret' CREATEDB;"
sudo -u postgres psql -c "CREATE DATABASE mkulima_forum OWNER mkulima;"
sudo -u postgres psql -c "CREATE DATABASE mkulima_test OWNER mkulima;"
composer install
cp .env.example .env && php artisan key:generate
# .env.example is already DB_CONNECTION=pgsql. Set DB_PASSWORD, then:
php artisan migrate --seed
php artisan serve # http://localhost:8000
php artisan test # uses mkulima_test, from phpunit.xml
Production is the Ubuntu VPS in DEPLOYMENT_RUNBOOK.md.
Before a deploy: php artisan mkulima:preflight. To count users and content
without changing them: php artisan mkulima:census.
Required .env keys for full functionality (all currently empty — features degrade honestly without them):
GEMINI_API_KEY — plant disease scanner (returns 503 without it)OPENWEATHER_API_KEY — weather (serves stale cache / unavailable without it; never fabricates data)MPESA_CONSUMER_KEY/SECRET/PASSKEY, TIGOPESA_API_KEY/SECRET — payments (sandbox mode)
Route files: routes/api.php (core), api_kyc.php, api_notifications.php, api_seller.php. Health check: GET /api/health.
Flutter App
cd mkulima_app
flutter pub get
flutter run --dart-define=API_URL=http://10.0.2.2:8000/api # Android emulator → local API
flutter build apk --dart-define=API_URL=https://mkulimaforum.com/api
The API base URL is injected via --dart-define=API_URL (defaults to production). No hardcoded hosts.
Admin
Staff sign in at /admin (Filament). Publish assets after install:
php artisan filament:assets
admin-dashboard/ is the previous React app. It is not deployed, and its
build must not be written to public/admin.
Canonical API Host
All clients target https://mkulimaforum.com/api in production. Change it in one place per client: --dart-define=API_URL (Flutter), .env.production (admin), APP_URL in .env (backend).
Status
Phase 0 (make it run) is in progress — see REDESIGN.md §4 for the roadmap and §6 for the fix list.
Production configuration
Most operational settings are managed from Admin → System → Configuration rather than
by editing .env on the server: SMTP credentials, SMS and IVR provider settings, webhook
secrets, short-link allowed hosts, and application URLs.
Settings resolve database → .env → default, and are overlaid onto Laravel's runtime
config on every request, so they work correctly under php artisan config:cache and take
effect with no cache clear and no deploy.
Secrets are encrypted at rest, never returned to the client, restricted to superadmins,
and audit-logged as a rotation rather than a value.
Verify any environment with:
php artisan mkulima:preflight
Full detail — including which settings must stay in .env and why, the security model,
and queue worker setup — is in docs/CONFIGURATION.md.
