FarmLink — Kenya Agritech Marketplace

FarmLink connects investors with verified agricultural spaces (crops, poultry, aquaculture) across Kenya. An AI discovery engine matches listings from natural-language intent and generates KES venture reports.

Requirements

• Python 3.11+ (3.11 recommended)
• Git
• Optional: Supabase PostgreSQL (SQLite works for local dev without DB credentials)

Clone & run (new machine)

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/farmlink.git
cd farmlink

Replace YOUR_USERNAME/farmlink with your actual GitHub repo URL.

2. Create a virtual environment

Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Configure environment variables

# Windows
copy .env.example .env

# macOS / Linux
cp .env.example .env

Edit .env and set at minimum:

Variable	Required	Notes
SECRET_KEY	Yes (production)	Any long random string for production
DEBUG	No	True for local dev
FEATHERLESS_API_KEY	For AI features	Discover reports & chat assistant
DB_HOST, DB_PASSWORD, …	No	Omit to use SQLite locally

Without DB_HOST, the app uses SQLite (db.sqlite3) automatically.

4. Initialize the database

python manage.py migrate
python manage.py seed_agrios

Optional — create a superuser for Django admin:

python manage.py createsuperuser

5. Run the development server

python manage.py runserver

Open http://127.0.0.1:8000/

Demo accounts (after seed)

Username	Role	Password
demo_investor	Investor	demo1234
demo_landowner_central	Landowner	demo1234
demo_landowner_nairobi	Landowner	demo1234
demo_landowner_rift	Landowner	demo1234
demo_landowner_lakeside	Landowner	demo1234

Reseed demo data:

python manage.py seed_agrios --fresh

Supabase PostgreSQL (optional)

From Supabase → Settings → Database, add to .env:

DB_HOST=db.<project-ref>.supabase.co
DB_NAME=postgres
DB_USER=postgres
DB_PASSWORD=<your-password>
DB_PORT=5432
DB_SSLMODE=require

Then run python manage.py migrate again.

Stack

• Backend: Django 5.x, Django Channels (WebSocket chat)
• Database: Supabase PostgreSQL or SQLite
• Frontend: Django templates, Tailwind CSS (CDN), Alpine.js
• AI: Featherless API (DeepSeek-V3.2)
• Integrations: Smile ID KYC, M-Pesa (sandbox/simulation)

Project structure

agrios/          Django project settings (internal package name)
accounts/        Custom user model, KYC, auth
core/            Models, views, discovery engine, verification
services/        AI reports, M-Pesa helpers
templates/       HTML templates
static/          CSS, images
media/           User uploads (not in git — created locally)

Main URLs

URL	Description
/	Landing page
/browse/	Verified listing catalog
/discover/	AI discovery wizard
/assistant/	AI chat assistant
/accounts/login/	Login
/admin/	Django admin

Push to GitHub (first time)

From your development machine, after creating an empty repo on GitHub:

git init
git add .
git commit -m "Initial FarmLink commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/farmlink.git
git push -u origin main

Never commit .env — it is listed in .gitignore. Share secrets with teammates separately (password manager, secure chat).

Troubleshooting

Issue	Fix
ModuleNotFoundError	Activate .venv and run pip install -r requirements.txt
AI report/chat empty	Set FEATHERLESS_API_KEY in .env
No listings	Run python manage.py seed_agrios
PowerShell blocks venv activate	Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once
Port 8000 in use	python manage.py runserver 8001