Smart Agro AI

Smart Agro AI is an MVP agriculture decision-support platform in active development. It combines a React frontend, a FastAPI backend, a local SQLite development database, and an XGBoost crop recommendation model artifact.

The current repository is suitable as a public open-source baseline, but it is not production-ready. Some screens are real MVP flows, while others are static demo views intended to show the planned platform direction.

Current Status

Area	Status
Frontend app	Implemented MVP with React, Vite, Tailwind CSS, Recharts, and React Leaflet.
Backend API	Implemented MVP with FastAPI, SQLAlchemy, SQLite, and model inference.
Crop recommendation	Implemented with local XGBoost and LabelEncoder artifacts.
Weather lookup	Implemented through Open-Meteo archive API with fallback values.
Authentication	JWT-based MVP registration, login, current-user lookup, and frontend session restore. Not production auth.
Virtual Agronom	Mocked frontend assistant. Gemini is not currently integrated.
Agro Market	Static/demo product catalog with local cart state only.
IoT/sensors	Simulated through frontend sliders. No real IoT ingestion yet.
Support tickets	Static/demo form only.
Admin dashboard	Static/demo metrics with frontend-only role display.
PDF report	Client-side report export for completed analysis.

Tech Stack

Frontend:

• React
• Vite
• Tailwind CSS
• Axios
• Recharts
• React Leaflet
• Lucide React
• Playwright for browser smoke testing

Backend:

• FastAPI
• SQLAlchemy
• SQLite for local development
• Pydantic
• XGBoost
• scikit-learn
• Joblib
• NumPy
• python-jose

Repository Structure

smart-agro/
  .github/
    workflows/
    ISSUE_TEMPLATE/
  backend/
    main.py
    app/
      main.py
      config.py
      database.py
      models.py
      schemas.py
      security.py
      ml.py
      routers/
      services/
    requirements.txt
    tests/
    .env.example
    xgboost_model.joblib
    encoder.joblib
  docs/
    ARCHITECTURE.md
    DEVELOPMENT.md
    SECURITY_NOTES.md
    audits/
  frontend/
    src/
    public/
    package.json
    .env.example
  dataset/
    README.md
  README.md
  LICENSE
  SECURITY.md
  CONTRIBUTING.md
  ROADMAP.md
  CHANGELOG.md

Documentation

• Architecture
• Development guide
• Deployment readiness
• Public demo checklist
• Security notes
• Contributing
• Roadmap
• Changelog
• Historical repository audit

Security Notice

Never commit:

• .env files
• API keys
• access tokens
• local SQLite database files
• password hashes
• real user records
• production credentials

If a secret was ever committed, rotate it immediately. Local database files are ignored by git and should be recreated by each developer.

Backend Setup

From the repository root:

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

Optional local configuration:

copy .env.example .env

The current backend reads configuration from environment variables. It does not automatically load .env; use your shell, IDE, or process manager to export variables if needed.

Backend environment variables:

Variable	Default	Purpose
DATABASE_URL	sqlite:///backend/smartagro_local.db	Database connection URL.
ALLOWED_CORS_ORIGINS	http://localhost:5173,http://127.0.0.1:5173	Comma-separated frontend origins.
ADMIN_EMAILS	empty	Optional comma-separated demo admin emails. Leave empty for public use.
JWT_SECRET_KEY	development-only fallback	Secret used to sign JWT access tokens. Set a strong value for any shared or deployed environment.
JWT_ALGORITHM	HS256	JWT signing algorithm.
ACCESS_TOKEN_EXPIRE_MINUTES	60	Access token lifetime in minutes.
GEMINI_API_KEY	empty	Reserved for future Gemini integration. Not used by the current MVP.
DEMO_SEED_PASSWORD	demo-password-123	Optional local-only password for demo seed users. Never use real credentials.
DEMO_FARMER_EMAIL	demo.farmer@example.com	Optional local-only demo farmer email.
DEMO_FARMER_NAME	Demo Farmer	Optional local-only demo farmer display name.
DEMO_ADMIN_EMAIL	empty	Optional local-only demo admin email. Created only when also listed in ADMIN_EMAILS.

Run database migrations from the repository root:

python -m alembic -c backend/alembic.ini upgrade head

On Windows with the project virtual environment:

.\backend\venv\Scripts\python.exe -m alembic -c backend\alembic.ini upgrade head

Seed local demo data only after migrations:

python -m backend.scripts.seed_demo

The seed script is idempotent, hashes demo passwords, does not print passwords or hashes, and never creates an admin user unless DEMO_ADMIN_EMAIL is also allowed through ADMIN_EMAILS.

Run the backend:

uvicorn main:app --reload

The backend application lives in backend/app/. backend/main.py remains a compatibility entrypoint so uvicorn main:app --reload still works from the backend/ directory.

Frontend Setup

From the repository root:

cd frontend
npm install

Optional local configuration:

copy .env.example .env

Frontend environment variables:

Variable	Default	Purpose
VITE_API_BASE_URL	http://127.0.0.1:8000	Backend API base URL.

Frontend auth behavior:

• Login stores the backend access token in localStorage.
• App startup checks for a stored token and calls /api/me to restore the current user.
• Invalid or expired tokens are cleared and the user is returned to the login view.
• Protected app views require a restored or freshly logged-in user in frontend state.
• Core app errors are shown as bounded inline messages instead of browser alerts.
• Dashboard analysis supports GPS, manual latitude/longitude entry, or explicitly selected demo coordinates.
• Static marketplace, support, profile, history, IoT, and admin actions are labeled as demo/MVP where they are not persisted.
• Shared frontend helpers provide accessible notices, demo badges, and readable loading states.

Run the frontend:

npm run dev

Build the frontend:

npm run build

Lint the frontend:

npm run lint

Test the frontend:

npm test

Run browser smoke tests:

npx playwright install chromium
npm run test:e2e

The Playwright suite starts the Vite dev server automatically and mocks backend API calls. It does not require a real backend, database, weather API, model inference, browser geolocation permission, API keys, or secrets.

Deployment Planning

Deployment guidance is documented in docs/DEPLOYMENT.md, and the public demo readiness checklist is in docs/PUBLIC_DEMO_CHECKLIST.md.

Recommended MVP demo topology:

• static frontend host such as Vercel, Netlify, or Cloudflare Pages,
• hosted FastAPI backend such as Render, Railway, Fly.io, or DigitalOcean App Platform,
• hosted PostgreSQL for shared demo auth state,
• Alembic migrations before public demo use.

No deployment has been performed by this repository phase. Do not add real secrets to the repo.

Backend Tests

From the repository root:

python -m pytest backend/tests

Backend tests use temporary SQLite databases and do not require real API keys.

Backend migrations use Alembic under backend/alembic/. The current app still keeps a local/test create_all fallback for MVP developer ergonomics, but shared and production-like databases should be initialized with Alembic migrations.

Browser QA

Phase 3D adds a focused Playwright smoke baseline under frontend/e2e/.

Covered flows:

• public landing page rendering and primary navigation
• login/logout with mocked /api/login
• stored-token session restore with mocked /api/me
• stale-token handling and friendly auth notice
• dashboard analysis with mocked /api/analyze
• manual/demo location fallback without real geolocation
• mobile compact navigation
• lightweight keyboard, form-label, alert, and status-role checks

Generated Playwright reports, traces, screenshots, videos, and test results are ignored by git.

Frontend Quality Notes

The frontend dependency audit is expected to be clean after removing an unused React Router dependency. Run npm audit and npm audit --omit=dev from frontend/ when changing packages.

The app uses small lazy-loaded chunks for heavier authenticated sections such as maps, charts, market, support, admin, and PDF export helpers. This keeps the landing/auth path smaller while preserving the current app-state navigation model.

API Overview

Current endpoints:

Method	Path	Description
POST	/api/register	Demo user registration.
POST	/api/login	User login. Returns a bearer access token and safe user metadata.
GET	/api/me	Returns the current authenticated user from a bearer token.
POST	/api/analyze	Crop recommendation and irrigation estimate.
GET	/health	Basic service health.
GET	/ready	Database and model readiness check.

FastAPI also exposes generated docs when the backend is running:

• http://127.0.0.1:8000/docs
• http://127.0.0.1:8000/openapi.json

Backend validation rules and the current /api/analyze response contract are documented in docs/DEVELOPMENT.md.

The frontend stores the MVP access token in localStorage, restores sessions with /api/me, and sends API calls with an Authorization: Bearer ... header. This keeps the current demo flow simple, but it is not the recommended storage strategy for high-security production systems.

AI/ML Notes

The model artifacts are included in backend/:

• xgboost_model.joblib
• encoder.joblib

Known limitations:

• A deterministic candidate training workflow exists under backend/ml/, but generated candidate artifacts do not automatically replace the production MVP artifacts.
• Baseline metrics, candidate metadata, and production-vs-candidate comparison reports are documented under docs/ml/metrics/ and docs/ml/artifacts/; these are reproducibility/release-gate records, not field validation.
• Phase 4C reviewed the candidate artifacts and did not promote them because dataset provenance/license remains unresolved.
• Dataset provenance and licensing are unknown and must be confirmed before assuming open redistribution rights.
• Phase 4D found no repository-local source/license evidence for dataset/Crop_recommendation.csv; the project MIT license must not be assumed to cover upstream dataset redistribution rights.
• Phase 4F moved dataset/Crop_recommendation.csv to download-only/user-provided handling. No confirmed source/license match exists, and dataset redistribution rights are not claimed.
• Common English and Uzbek crop labels are normalized for backend irrigation lookup, but full model-label provenance still belongs in the future ML reliability phase.
• The model is for MVP demonstration and should not be treated as agronomic advice.
• Weather API failures, malformed provider responses, and model fallback paths are returned with explicit fallback indicators and warning messages.

See:

• Model audit
• Dataset card
• Model card
• Training plan
• Label mapping contract
• Promotion checklist
• Model release notes
• Data policy
• Dataset fingerprint
• Source match report

What Is Demo-Only

The following areas are currently static or simulated:

• Virtual Agronom mocked chat
• Agro Market checkout
• IoT device integration
• Sensor ingestion
• Support ticket submission
• Admin analytics
• Irrigation history persistence
• Subscription/payment flows

Open-Source Baseline

This repository now includes:

• MIT LICENSE
• SECURITY.md
• CONTRIBUTING.md
• ROADMAP.md
• CHANGELOG.md
• GitHub issue templates and pull request template
• GitHub Actions CI for frontend and backend checks

Planned next steps are listed in ROADMAP.md.

Release Preparation

The v0.1.0 release-candidate package is documented in:

• v0.1.0 release notes
• Release checklist
• GitHub issue and label plan
• Repository presentation recommendations
• Codex for OSS application draft

Do not create release tags, deploy public infrastructure, or publish production-readiness claims until the checklist has been reviewed by the maintainer.

License

Smart Agro AI is released under the MIT License. See LICENSE.

Dataset note: the project license does not resolve the source/license status of dataset/Crop_recommendation.csv. The CSV is download-only/user-provided and intentionally ignored by Git.