GoFarm Developer Documentation — Build, Configure & Ship

01Introduction

GoFarm is a production-ready agricultural e-commerce platform that connects farmers and consumers directly. It ships with a full storefront, an admin dashboard, vendor onboarding, an employee portal, multi-currency support, Stripe + SSLCommerz checkout, and a Sanity-powered CMS.

The codebase is built around three principles: a single source of truth per concern (Firebase Auth for identity, Sanity for domain data, GA4 for analytics), server-by-default React components, and strictly enforced coding standards via Biome, lefthook, and Conventional Commits.

Who this guide is for

• New contributors setting up a local environment for the first time.
• Maintainers looking for a complete reference to the routes, APIs, and schemas.
• DevOps engineers deploying GoFarm to Vercel or another host.
• Store operators configuring services (Sanity, Stripe, email) before going live.

02Tech Stack

GoFarm uses a modern, battle-tested set of libraries. Every package is on a current major version with security patches applied.

03Core Features

Out of the box, GoFarm includes everything an agricultural marketplace needs. The full feature set is available to anyone using or purchasing the project — there are no locked tiers.

04Prerequisites

Before you clone the repo, make sure your machine has the following installed.

Required accounts

You will need free-tier accounts for the following SaaS services. All can be created in under 10 minutes.

• Sanity CMS — sanity.io (catalog, pages, blog)
• Firebase — console.firebase.google.com (auth + analytics)
• Stripe — stripe.com (card payments)
• Google Cloud — console.cloud.google.com (Gmail OAuth2 for outbound email)
• SSLCommerz (optional, BD payments) — sslcommerz.com

05Quick Start

These five steps take you from a blank machine to a running local dev server. Detailed configuration is covered in §7.

git clone https://github.com/noorjsdivs/gofarm.git
cd gofarm

pnpm install

cp .env.example .env.local

pnpm dev          # webpack (default)
pnpm dev:turbo    # turbopack (faster HMR)

06Environment Variables

Every variable the app reads is grouped by concern. Server-only variables have no NEXT_PUBLIC_ prefix and never ship to the browser.

Base & admin

NEXT_PUBLIC_BASE_URL=http://localhost:3000
ADMIN_EMAILS=you@example.com,team@example.com

Sanity CMS

NEXT_PUBLIC_SANITY_PROJECT_ID=xxxxxxxx
NEXT_PUBLIC_SANITY_DATASET=production
SANITY_API_TOKEN=sk_write_token_here
SANITY_API_READ_TOKEN=sk_read_token_here

Firebase client (public)

NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSy...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123:web:abc
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX

Firebase Admin (server only)

FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-...@your-project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Stripe

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

SSLCommerz (optional, BD)

SSLCOMMERZ_STORE_ID=...
SSLCOMMERZ_STORE_PASSWORD=...
SSLCOMMERZ_IS_LIVE=false

Email (Gmail OAuth2)

GOOGLE_CLIENT_ID=123456789-xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
GOOGLE_REFRESH_TOKEN=1/04...
SENDER_EMAIL_ADDRESS=noreply@yourdomain.com

Analytics (GA4 Measurement Protocol)

GA4_MEASUREMENT_ID=G-XXXXXXXXXX
GA4_API_SECRET=abc123...

07Service Setup

Detailed walkthrough for each external service GoFarm depends on. Complete these before running pnpm dev.

7.1 Sanity CMS

1. Sign in at sanity.io/manage and create a new project.
2. Note the Project ID and use production as the dataset name.
3. Under API → Tokens, generate two tokens: Editor (write) and Viewer (read).
4. Add the CORS origin http://localhost:3000 (and later your production domain) with credentials enabled.
5. Paste IDs and tokens into .env.local (see §6).
6. Visit /studio to start authoring categories, brands, and products.

7.2 Firebase Authentication & Analytics

1. Create a project at Firebase Console.
2. In Authentication → Sign-in methods, enable Email/Password and Google.
3. In Project settings → General, register a Web app and copy the SDK config into the NEXT_PUBLIC_FIREBASE_* variables.
4. Under Service accounts → Generate new private key, download the JSON and extract project_id, client_email, and private_key into the server-only FIREBASE_* variables.
5. Enable Analytics and link the GA4 property — required for the GA4 Measurement Protocol.

7.3 Stripe

1. Get test API keys from Developers → API Keys.
2. Local development webhook:

   stripe login
   stripe listen --forward-to localhost:3000/api/webhook

   Copy the whsec_ secret into STRIPE_WEBHOOK_SECRET.
3. For production, register an endpoint at https://yourdomain.com/api/webhook and subscribe to:
   • checkout.session.completed
   • payment_intent.succeeded
   • charge.refunded

7.4 Gmail OAuth2 for email

1. At Google Cloud Console enable the Gmail API for your project.
2. Create an OAuth client ID (Web application).
3. Authorize redirect URI https://developers.google.com/oauthplayground.
4. Use the OAuth Playground with your own credentials to obtain a refresh token for the scope https://mail.google.com/.
5. Paste the credentials into GOOGLE_* env vars.

7.5 GA4 Measurement Protocol

1. In GA4 console open Admin → Data Streams → Web.
2. Click Measurement Protocol API secrets → Create and copy the secret to GA4_API_SECRET.
3. The same property's Measurement ID becomes GA4_MEASUREMENT_ID.
4. Mark purchase, sign_up, and begin_checkout as conversion events for Monetisation reports.

08Running the App

Available scripts

Local URLs

• http://localhost:3000 — Storefront
• http://localhost:3000/studio — Sanity Studio
• http://localhost:3000/admin — Admin Dashboard
• http://localhost:3000/employee — Employee Portal
• http://localhost:3000/vendor — Vendor Portal
• http://localhost:3000/docs — This documentation

09Project Structure

GoFarm uses the Next.js App Router with route groups for isolation. Server actions live in actions/, shared helpers in lib/, schemas in sanity/.

gofarm/
├── app/                          # Next.js App Router
│   ├── (client)/                 # Public storefront route group
│   │   ├── (public)/             # About, FAQ, contact, etc.
│   │   ├── (user)/               # Cart, checkout, dashboard
│   │   ├── blog/  brands/  category/  collection/
│   │   ├── compare/ deal/ product/ products/ shop/
│   │   ├── orders/  vendor-info/  vendor-registration/
│   │   ├── home-2/  home-3/  home-4/
│   │   └── page.tsx              # Homepage
│   │
│   ├── (admin)/admin/            # Admin dashboard
│   ├── (auth)/                   # Sign-in / Sign-up
│   ├── (employee)/employee/      # Fulfilment portal
│   │
│   ├── api/                      # API routes
│   │   ├── auth/      checkout/   payment/   webhook/
│   │   ├── admin/     user/       vendor/    employee/
│   │   ├── orders/    coupons/    categories/
│   │   ├── menus/     newsletter/ contact/
│   │   ├── analytics/ addresses/  store-settings/
│   │   └── ...
│   │
│   ├── studio/                   # Embedded Sanity Studio
│   ├── docs/                     # This documentation page
│   ├── layout.tsx                # Root layout (Jost, providers)
│   ├── globals.css
│   ├── robots.ts
│   └── sitemap.ts
│
├── actions/                      # "use server" actions
├── components/                   # Shared UI components
│   ├── ui/                       # shadcn primitives
│   ├── admin/  vendor/  employee/
│   ├── cart/  checkout/  product/
│   └── AuthInitializer.tsx  AnalyticsProvider.tsx
│
├── hooks/                        # Client-side hooks
├── lib/                          # Framework-agnostic helpers
│   ├── firebase/admin.ts
│   ├── auth/server.ts
│   ├── analytics/server.ts
│   └── logger.ts
│
├── sanity/                       # CMS configuration
│   ├── schemaTypes/              # 25+ content schemas
│   ├── queries/                  # Centralised GROQ
│   └── helpers/  lib/  env.ts
│
├── stores/                       # Zustand state
├── store.ts                      # Legacy cart store
├── types/   config/   constants/
├── public/                       # Static assets (logo.svg, etc.)
├── scripts/                      # CLI scripts
├── biome.json                    # Format + lint config
├── lefthook.yml                  # Git hooks
├── commitlint.config.mjs
├── next.config.ts
├── sanity.config.ts
└── tsconfig.json

10Routing

The App Router uses parenthesised route groups to isolate layouts without changing URLs. Each group has its own layout.tsx and error.tsx.

Edge middleware

proxy.ts runs at the Edge for every request. It checks the __session cookie and redirects unauthenticated users away from /admin, /employee, /cart, /checkout, and /user. Role checks happen in the Node-runtime layout because firebase-admin is not available at the Edge.

11Authentication

Identity is owned entirely by Firebase Authentication. Sanity stores only the things Firebase does not — addresses, wallet, wishlist — keyed by the Firebase UID.

Session lifecycle

Browser                       /api/auth/session              Firebase Admin
   │                                  │                          │
   │ signInWithEmail / Google         │                          │
   │ ─────────────────────────────▶   │                          │
   │  idToken (1h TTL)                │ verifyIdToken            │
   │                                  │ ───────────────────────▶ │
   │                                  │ createSessionCookie(14d) │
   │ ◀───────────────────────────────                            │
   │  Set-Cookie: __session;          │                          │
   │  HttpOnly; Secure; SameSite=Lax  │                          │
   │                                  │ ensureSanityUser(uid)    │
   │                                  │ ◀─── idempotent ──────── │

Key files

• lib/firebase/admin.ts — single Admin SDK init.
• lib/auth/server.ts — canonical server auth helpers: requireUser(), requireRole(), currentUserIsAdmin().
• app/api/auth/session/route.ts — POST creates session cookie, DELETE revokes refresh tokens.
• stores/authStore.ts — Zustand store mirroring Firebase auth state to React.
• components/AuthInitializer.tsx — subscribes toonIdTokenChanged and pushes ID tokens to /api/auth/session.

Server-side usage

// app/(client)/(user)/user/page.tsx
import { requireUser } from "@/lib/auth/server";

export default async function UserDashboard() {
  const user = await requireUser();
  return <Dashboard user={user} />;
}

12Authorization & Roles

Roles live in Firebase custom claims so they are present in the JWT and require no database round-trip on every request.

Granting a role

# Preview (no changes)
pnpm tsx scripts/sync-claims.ts

# Commit
pnpm tsx scripts/sync-claims.ts --apply

13Sanity CMS

Sanity is the system of record for catalog, marketing pages, blog, and per-user domain data (orders, addresses, wallet). Schemas live in sanity/schemaTypes/.

Queries

GROQ queries are never inlined in components. They live in sanity/queries/*.ts as typed functions.

// sanity/queries/userQueries.ts
export const ordersByUser = `
  *[_type == "order" && firebaseUid == $uid]
    | order(orderDate desc) {
      _id, status, totalPrice, currency,
      products[]{ quantity, product->{title, slug, image} }
    }
`;

Whenever a schema changes, run pnpm typegen to rebuild sanity.types.ts.

14API Reference

All routes live under app/api/**. Most mutations now prefer Server Actions in actions/; the API routes remain for webhooks and AJAX endpoints used by the dashboards.

Server Actions

Mutations preferred over API routes — typed end-to-end. All actions return a discriminated union and never throw across the network boundary.

type ActionResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: string };

"use server";
export async function createReview(
  input: ReviewInput
): Promise<ActionResult<Review>> {
  const user = await requireUser();
  // … validate with zod, write to Sanity, revalidate tags …
}

15State Management

Zustand is the only client store. Each concern has its own slice; stores subscribe to authStore when they need to react to sign-in / sign-out.

16Payments & Orders

Checkout flow

Cart ──▶ /checkout ──▶ /api/checkout/stripe ──▶ Stripe Checkout
                              │
                              ▼
                       Sanity order doc (status: pending)
                              │
                              ▼
                Stripe ──▶ /api/webhook (signature verified)
                              │
            ┌─────────────────┼──────────────────────┐
            ▼                 ▼                      ▼
    update order        send confirmation     GA4 purchase
    status: paid            email             (Measurement Protocol)

Order status machine

1. pending — created, awaiting payment.
2. paid — Stripe / SSLCommerz confirmed.
3. processing — assigned to employee.
4. shipped — courier tracking attached.
5. delivered — final.
6. cancelled — refund issued if paid.

17Analytics (GA4)

GoFarm emits the full GA4 e-commerce funnel so Firebase Console → Analytics → Realtime, Monetisation, and Retention reports auto-populate.

components/AnalyticsProvider.tsx calls setUserId(uid) and setUserProperties() whenever auth state changes, enabling cross-device cohort reports. Append ?debug=1 to any page to fire events with debug_mode: true so they appear in GA4 DebugView.

18Admin Dashboard

The admin dashboard lives at /admin behind the admin custom claim.

19Vendor & Employee Portals

Vendor Portal — /vendor

• Sign-up at /vendor-registration, awaits admin approval.
• Once approved, the vendor custom claim is set and the vendor sees their dashboard.
• Manage own products, view orders, request payouts via walletWithdrawal.

Employee Portal — /employee

• Granted manually by an admin via the user management UI.
• Order queue, status transitions, delivery confirmations, warehouse stock movements.
• Activity is logged to the order's history array for audit.

20Coding Standards

Standards are enforced by tooling rather than convention. Biome formats and lints on every commit; commitlint validates every commit message; TypeScript strict mode catches type errors before they ship.

Naming conventions

21Git Workflow

Conventional Commits

<type>(<scope>): <subject>

# Allowed types
feat, fix, docs, style, refactor, perf,
test, build, ci, chore, revert

# Examples
feat(cart): add coupon stacking
fix(checkout): correct VAT rounding
chore(deps): bump biome to 2.4.16

Pre-commit hooks (lefthook)

22Deployment

Deploy to Vercel (recommended)

1. Push your branch to GitHub.
2. At vercel.com, import the repository.
3. Framework Preset: Next.js. Build command: pnpm build.
4. Add every variable from .env.local in Project Settings → Environment Variables.
5. After the first deploy, update NEXT_PUBLIC_BASE_URL to your domain.
6. In Sanity → API → CORS origins, add the production URL with credentials enabled.
7. In Stripe, create a production webhook pointing to /api/webhook and paste the new whsec_ into Vercel env.
8. In Firebase → Authentication → Authorized domains, add the production domain.

Post-deploy checklist

• Sign in with the email listed in ADMIN_EMAILS — the admin custom claim is set automatically on first login.
• Run the claims backfill: pnpm tsx scripts/sync-claims.ts --apply.
• In GA4, mark purchase, sign_up, begin_checkout as conversion events.
• Place a test order with Stripe's test card 4242 4242 4242 4242.
• Confirm the GA4 Realtime view shows your purchase event within 30 seconds.

23Pricing & Hire Me

Want me to set up GoFarm for you instead of doing it yourself? Every package starts from the same installation base of $100 — the additional tiers simply layer add-ons on top. Honest, freelance-market rates from Bangladesh, all in USD. Each package is a fixed scope, fixed price. Hourly is available for ad-hoc changes after handover.

Hourly & ongoing work

What's not included

• Third-party service costs (Vercel Pro, Sanity paid plan, Google Workspace, etc.) — you pay these directly to the providers.
• Stripe / SSLCommerz business verification — done by you on their dashboards.
• Domain & SSL purchase — you buy from your preferred registrar; I configure the DNS.
• Content creation (product photos, descriptions, blog posts).

24Troubleshooting

25Support

• Email — reactjsbd@gmail.com
• YouTube tutorials — @reactjsbd
• Website — reactbd.com

License. GoFarm is MIT-licensed. Everything in the repository is included — there are no locked features. Buyers of any pricing package get the same codebase, the same docs, and the same support channels.