Build map
What runs where
High-level map of the Next.js app, the desk, listings, contracts, telemetry, and the money rail. Read this before adding a page.
GigRentals is a Next.js 16 App Router monolith. proxy.ts (not middleware.ts) is the edge gate. Demo state is a cookie delta plus `.data/` blobs for photos and device snapshots. Production swaps adapters: Postgres, Redis, Stripe, Supabase Auth/Storage.
Technologies
| Layer | What | Where |
|---|---|---|
| Web | Next.js 16 App Router + React 19 | app/, components/ |
| Auth | Demo cookie or Supabase OAuth (Google/Apple) | actions/auth.ts, app/auth/callback |
| Desk RBAC | Staff roles, no in-app wallet | lib/security/desk.ts |
| Listings | Host CRUD + JPEG store | actions/listings.ts, .data/listings |
| Money | Integer-cent ledger + Stripe Connect + program books | backend/payments, lib/stripe.ts, lib/reporting/books.ts |
| Resend or .data/mail.json | lib/mail/send.ts, /admin/mail | |
| Telematics | Vendor catalog + webhook | lib/telematics/, /admin/telematics |
| Match | H3 lookup + Hungarian | backend/dispatch |
| Forms | Floating labels + Zod | components/ui/floating-field.tsx, lib/validations.ts |
| Telemetry | Common browser APIs | components/telemetry/beacon.tsx |
| Docs | This site, generated from TypeScript | lib/docs/pages.ts |
Pages and who they are for
| Path | Persona | Job |
|---|---|---|
| / | Public | Two doors: idle car vs $25/day driver |
| /join, /drivers/start | Ad click | OAuth Google/Apple then apply |
| /owners/apply → /owners/agreement | Host applicant | Quote then UETA signature |
| /owners/garage | Approved host | Upload car, photos, money metrics, checkout status |
| /cars/[slug] | Lessee | Full booking page: story, specs, icons, book |
| /drivers/apply | Driver applicant | Job application, then program + signature |
| /rankings | Public | Host occupancy / driver care — no dollars |
| /admin | Desk | Queues, devices, ranks. Stripe link, not balances |
| /admin/income | Desk finance/ops | Program books that match owner + driver |
| /admin/telematics | Desk ops | Tracker vendor catalog + hook status |
| /admin/mail | Desk | Demo transactional outbox |
| /owners/earnings | Host | Host net from the same books file |
| /drivers/earnings | Lessee | What they paid — same identity |
| /owners/monitor | Host | Neighborhood pings, vendor-agnostic |
| /forgot-password, /verify-email | Public | Recovery + confirm |
| /docs | Engineers / investors | Live server documentation |
Critical systems
- Auth — demo cookie or Supabase. Google/Apple OAuth. Lockout, HIBP, IP throttle in lib/security/guard.ts.
- Desk — editor/reviewer/ops/finance/support/superadmin. finance gets desk:stripe (a URL), never amounts.
- Listings — ownerId, miles, VIN last 6, photos on disk. Delete photo / delete car. Public only if available.
- Contracts — booking, owner-program, listing, driver-lease. Typed name + initials + checkbox = UETA.
- Telemetry — UA hints, language, cores, deviceMemory, connection, screen, timezone, storage.estimate. No GPS prompt.
- Rankings — occupancy, inspection, care, on-time. Public. Desk can sort people by the same scores.
- Money — Stripe Connect is the wallet. Admin accounting is a deep-link. Program books (owner/driver/admin) live in lib/reporting/books.ts and must balance.
- Mail — hashed verify/reset tokens, welcome + reset transactional mail, Resend when keyed.
- Telematics — one adapter, 19 vendors with public APIs, webhook at /api/v1/fleet/telematics.
How files are annotated
Critical modules start with an @docs comment naming the system (listings, telemetry, desk, money, forms, storage). If you add a loop, add a row here and a @docs block on the file.