Local development

Three services, three ports.

Service	Port	Repo
Backend	3000	marketplace-fleapoai-service
Frontend	8080	fleapo-marketplace
Docs site	3001	marketplace-docs (this site)

(Adjust ports in .env to taste, but the frontend's default CORS allow-list assumes 8080.)

Prerequisites

• Node ≥ 20 (better-auth + posthog-node both rely on global crypto).
• pnpm 9.x.
• Postgres 15+ running locally (or Docker).
• (Optional) Stripe CLI for webhook replay.

Backend

cd marketplace-fleapoai-service
cp .env.example .env
# Set DATABASE_URL, AUTH_SECRET, AUTH_URL=http://localhost:3000

pnpm install
pnpm db:migrate
pnpm seed                          # creates admin@example.com / ChangeMe123!
pnpm start:dev                     # http://localhost:3000

# OpenAPI spec is regenerated on the fly; openapi.json appears in the repo root

For deep DB inspection:

pnpm db:studio                     # https://local.drizzle.studio

Frontend

cd fleapo-marketplace
cp .env.example .env.local
# Set VITE_API_BASE_URL=http://localhost:3000

pnpm install
pnpm dev                           # http://localhost:8080

The Vite dev server auto-reloads on changes. Cookies are issued by the backend (SameSite=Lax in dev).

Docs site (this site)

cd marketplace-docs
pnpm install

# First-time: sync the OpenAPI spec from the backend repo
pnpm sync-spec
pnpm gen-api

pnpm start                         # http://localhost:3000 — but conflicts with backend
# Use a different port:
pnpm start -- --port 3001

Whenever the backend's openapi.json changes, run pnpm refresh-api here to regenerate the MDX pages.

Running all three concurrently

A simple way:

# Terminal 1
cd marketplace-fleapoai-service && pnpm start:dev

# Terminal 2
cd fleapo-marketplace && pnpm dev

# Terminal 3
cd marketplace-docs && pnpm start -- --port 3001

Or wire a root package.json with concurrently if you prefer one command — not currently in repo.

Verifying auth works

1. Open http://localhost:8080/sign-up → register a user → land on /dashboard.
2. Sign in to the backend admin via seed: admin@example.com / ChangeMe123! → land on /admin.
3. curl -b cookies.txt http://localhost:3000/api/auth/get-session returns the session.

Stripe in dev

Use Stripe test keys. For webhooks:

stripe login
stripe listen --forward-to http://localhost:3000/webhooks/stripe

The CLI prints a temporary whsec_* — set it as STRIPE_WEBHOOK_SECRET in the backend .env, then restart. Now you can trigger events:

stripe trigger checkout.session.completed

Frequent local resets

If your DB gets weird:

cd marketplace-fleapoai-service
dropdb fleapo_marketplace && createdb fleapo_marketplace
pnpm db:migrate
pnpm seed

Never run drizzle-kit push to "fix" things. See Migrations.