Local Development

1. Install

npm install     # from the repo root — installs every workspace

2. Database & Prisma

The single Prisma schema lives at prisma/schema.prisma (40 models, 26 enums, 47 migrations). All Prisma commands take --schema=prisma/schema.prisma.

# Generate the typed client
npx prisma generate --schema=prisma/schema.prisma

# Apply all migrations to your database (creates tables)
npx prisma migrate dev --schema=prisma/schema.prisma

# Open Prisma Studio to inspect data
npx prisma studio --schema=prisma/schema.prisma

Supabase pooler + migrations

Some migrations were applied with prisma db execute + prisma migrate resolve --applied rather than the standard migrate dev flow, because the Supabase pooler closes the shadow-DB connection mid-migration. If migrate dev stalls against a pooled URL, use a direct (non-pooled) connection string for migrations.

3. Seed

npm run seed:lookups          # states, districts, makhana varieties, crops, group affiliations
npx prisma db seed            # taxonomy tree (4 L1 / 12 L2 / 42 L3) + lookups

Maintenance / QA seeds (run from the repo root or the API workspace):

# One-shot taxonomy wipe & reseed
npm run db:wipe-taxonomy

# QA sandbox accounts (fixed-OTP phones)
npm --workspace=apps/api run qa:seed-accounts
npm --workspace=apps/api run qa:teardown-accounts

# Load-test users
npm --workspace=apps/api run loadtest:seed

The seeded dev admin is phone +919900000098, password admin@cropto2026 (change before staging/prod). Note +919900000099 is the QA Test Sandbox farmer, not the admin.

4. Run the API

npm run dev --workspace=apps/api

This runs tsx watch src/index.ts. On boot the API:

1. Imports ./instrumentation first (Sentry + OpenTelemetry auto-instrumentation).
2. Warms the Prisma connection pool.
3. Starts the BullMQ SMS + scheduled workers (if Redis is configured).
4. Mounts all routes and listens on PORT (default 3000).

Verify: GET http://localhost:3000/api/v1/health returns { success: true, data: { status: "healthy", services: { database: "ok", … } } }.

Explore the API interactively at http://localhost:3000/api/docs (Swagger UI).

5. Run the frontends

npm run dev --workspace=apps/web     # http://localhost:5173
npm run dev --workspace=apps/admin   # http://localhost:5174

Both are Vite dev servers with HMR. They read VITE_API_URL from their own .env.

6. Marketing site (optional)

npm run dev --workspace=apps/marketing   # http://localhost:3002 — Next.js + Payload CMS
npm --workspace=apps/marketing run seed   # seed CMS content

The marketing site is fully isolated from the trading app and uses its own content database.

7. Mobile (optional)

cd apps/mobile
npm run android          # runs adb reverse then expo run:android
# or
npm start                # Metro bundler + Expo dev

adb reverse maps the device's localhost:3000 back to your machine so the app can reach the local API.

Typical daily loop

# Terminal 1 — API
npm run dev --workspace=apps/api

# Terminal 2 — Web
npm run dev --workspace=apps/web

# Terminal 3 — tests in watch mode for the workspace you're editing
npm --workspace=apps/api run test:watch