Setup guide

• Node.js 20+ and npm (or compatible package manager)
• A Firebase project with Authentication (email/password), Firestore, Realtime Database, and Storage enabled
• Git to clone the repository

From the project root:

npm install
cp .env.local.example .env.local
# Edit .env.local — see sections below
npm run seed
npm run dev

Open http://localhost:3001 after npm run dev reports Ready.

Copy .env.local.example to .env.local and fill in at least these values before signing in:

# App URL (invite links, QR codes, callbacks)
NEXT_PUBLIC_APP_URL=http://localhost:3001

# Firebase client (Firebase Console → Web app)
NEXT_PUBLIC_FIREBASE_API_KEY=...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=...
NEXT_PUBLIC_FIREBASE_APP_ID=...
NEXT_PUBLIC_FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com

# Server session (generate a random 32+ char secret in production)
SESSION_SECRET=dev-only-change-me-in-production

Full reference: .env.local.example in the repo root. Never commit .env.local — it is gitignored.

1. 1

   Client SDK (browser)

   Firebase Console → Project settings → Your apps → Web app. Copy values into NEXT_PUBLIC_FIREBASE_*.

2. 2

   Admin SDK (server)

   Service accounts → Generate new private key. Use npm run firebase:service-account or place *-firebase-adminsdk-*.json in the project root for auto-discovery.

3. 3

   Deploy rules & indexes

   Deploy firestore.rules, firestore.indexes.json, and storage rules from the repo when you connect a real project.

# From a downloaded service-account JSON file:
npm run firebase:service-account -- "C:\path\to\key.json"

# Or repair a corrupted .env.local:
npm run env:repair

1. 1

   Seed defaults

   npm run seed creates pricing tiers and ad marketplace slots in Firestore.

2. 2

   Sign up

   Visit /sign-up, create an account, and complete onboarding to create your first tenant. You become owner of that workspace.

3. 3

   Invite your team

   Dashboard → Settings → Team — issue invite codes or QR links for dispatchers and finance.

# After sign-up, copy your Firebase Auth UID from the console or session cookie
npm run populate:demo -- --owner-uid YOUR_FIREBASE_UID

# Or attach to an existing demo tenant
node scripts/populate-demo-data.mjs --tenant-slug savannah-haulage-demo --owner-uid YOUR_UID

# Preview without writes
node scripts/populate-demo-data.mjs --dry-run --create-tenant

# Remove demo tenant data (slug savannah-haulage-demo only)
node scripts/populate-demo-data.mjs --wipe --tenant-slug savannah-haulage-demo

The first user in an empty project may be promoted automatically. To grant platform administration manually, set on your user document in Firestore users/{uid}:

{
  "platformRole": "platform_admin"
}

Valid values: platform_admin, platform_support, none. Then open /admin for tenants, pricing, ads, and platform webhooks.

Confirm the server and Firebase Admin credentials:

curl -s http://localhost:3001/api/health | jq

Expect ok: true and a credentialSource field. Firebase client config for sign-in is exposed at /api/config/public (no secrets).

• REST APIBearer keys and v1 resources
• WebhooksSigned event deliveries
• MCP for agentsAI tools over /api/mcp
• API keysCreate keys in the dashboard