AgriSmart Full-Stack Platform
AgriSmart is a production-oriented agricultural platform for farmers, buyers, sellers, and administrators. It combines a native Expo mobile application with a secure Express and PostgreSQL API to support farm management, crop monitoring, AI-assisted disease scanning, AMIS market intelligence, marketplace ordering, subscriptions, notifications, and administrative operations.
Project Structure
agrismart/ ├── mobile/ # Expo React Native application ├── backend/ # Express and PostgreSQL REST API └── README.md
mobile/
Android and iOS application written in JavaScript and JSX using:
Expo and React Native
Expo Router
TanStack Query
Expo SQLite
Expo SecureStore
Zustand
Native camera, image, location, notification, and sharing APIs
backend/
Centralized REST API built with:
Node.js and Express
PostgreSQL
JWT authentication
Zod validation
Protected file uploads
AMIS price synchronization
Subscription and payment-proof workflows
Role- and permission-based administration
PostgreSQL is the authoritative source of business data. Mobile SQLite is used only for cached records, preferences, drafts, and offline synchronization.
Core Capabilities
Farmer and Buyer Application
Account registration, login, verification, and recovery
Farmer- and buyer-specific navigation
Farm and crop management
Crop-health monitoring and disease scanning
Weather conditions and agricultural risk indicators
AMIS prices, comparisons, trends, and exports
Marketplace browsing, listings, sellers, and protected images
Transactional order placement and inventory reservation
Buyer and seller order tracking
Notifications, profiles, avatars, and preferences
Subscription plans and entitlement-aware features
Offline cached data and queued operations
Administrator Console
Platform dashboard and operational metrics
User, farmer, and buyer management
Farm and crop review
Marketplace moderation
Order review and status management
AMIS imports, synchronization, prices, and logs
Subscription plans and payment-proof review
Notifications, support tickets, audits, and settings
Permission-gated administrative modules
The backend is the final authorization authority for every protected and administrative request.
Prerequisites
Node.js 18 or newer
npm
PostgreSQL or a compatible hosted PostgreSQL service
Expo Go or an Expo development build
Android Studio for Android emulation, when required
Xcode for iOS simulation on macOS, when required
Quick Start
- Backend Setup
cd backend npm install
Create backend/.env and configure the required values:
NODE_ENV=development PORT=5000 DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DATABASE JWT_SECRET=replace-with-a-secure-secret-at-least-32-characters JWT_EXPIRES_IN=7d CLIENT_URL=*
SEED_ADMIN_EMAIL=231980079@gift.edu.pk SEED_ADMIN_PASSWORD=replace-with-a-private-password-at-least-12-characters
Optional integrations may require Redis, SMTP, AI-provider, weather-provider, or storage settings. All service credentials must remain on the backend.
Initialize the database and start the API:
npm run db:migrate npm run db:seed npm run dev
Default development URLs:
API: http://localhost:5000 Health: http://localhost:5000/health Swagger UI: http://localhost:5000/api-docs OpenAPI JSON: http://localhost:5000/openapi.json
- Mobile Setup
Open a second terminal:
cd mobile npm install cp .env.example .env npx expo start
Configure the mobile API base URL so it is reachable from the selected device:
Android emulator: use the emulator-accessible host address instead of localhost.
iOS simulator: localhost may work when the API runs on the same Mac.
Physical device: use the development computer's local network IP address.
Administrator Setup
The seed script creates or updates the administrator configured in backend/.env:
SEED_ADMIN_EMAIL=231980079@gift.edu.pk SEED_ADMIN_PASSWORD=your-private-admin-password
The seed password must contain at least 12 characters. Seeding is disabled in production and administrator credentials must never be committed.
Run the seed script after configuring the database:
cd backend npm run db:seed
Main API Areas
The API is versioned under /api/v1.
API area
Responsibility
/api/v1/auth
Registration, login, verification, recovery, and sessions
/api/v1/users/me
Authenticated profile management
/api/v1/users/me/avatar
Protected avatar update
/api/v1/farms
Farm management
/api/v1/crops
Crop management
/api/v1/marketplace
Listings, sellers, reports, similar listings, and images
/api/v1/orders
Ordering, inventory reservation, status transitions, and timelines
/api/v1/market-prices
AMIS prices, comparisons, trends, dashboards, and exports
/api/v1/subscriptions
Plans, quotes, payment proofs, history, and entitlements
/api/v1/notifications
Notification delivery and read-state operations
/api/v1/admin
Moderation, imports, payments, plans, audits, and settings
Backend Commands
Run these commands inside backend/:
Command
Description
npm run dev
Start the API with Nodemon
npm start
Start the API with Node.js
npm run db:migrate
Apply database schema and migrations
npm run db:seed
Seed or update development data
npm test
Run the backend test suite
Security Requirements
Never commit .env files.
Never place database, JWT, SMTP, AI, weather, Redis, or storage credentials in the mobile app.
Store mobile session tokens only in Expo SecureStore.
Do not store authentication tokens in AsyncStorage or plain SQLite.
Use HTTPS in staging and production.
Enforce authentication, authorization, ownership, and permissions on the backend.
Validate upload type, size, ownership, and access.
Redact passwords, OTP values, tokens, and private user information from logs.
Revoke and rotate any credential included in a shared archive or committed to version control.
Offline Data Model
Previously synchronized records remain readable from SQLite.
Supported offline mutations are stored in an outbox.
Queued operations remain visibly marked until confirmed by the backend.
Temporary failures may be retried automatically.
Validation and conflict failures require explicit user action.
A queued mutation must never be shown as successfully synchronized.
Development Principles
Keep Expo Router files focused on routes, layouts, and screen composition.
Keep reusable UI, feature logic, API access, and validation outside the route tree.
Use TanStack Query for remote server state.
Use Zustand only for small client-side state that does not duplicate server records.
Treat backend validation and business rules as authoritative.
Paginate marketplace and administrator lists.
Resize and compress images before upload.
Test authentication, permissions, uploads, offline states, order transitions, and admin actions.
Important Release Checks
Before production release:
Remove all committed or shared environment files.
Rotate exposed credentials and secrets.
Complete Android and iOS device testing.
Verify English and Urdu RTL behavior.
Test accessibility, deep links, notifications, and offline synchronization.
Configure database backups and production observability.
Produce signed Android and iOS builds.