Architecture Overview
HostMetrics is a monolithic Next.js 15 application deployed on Vercel, with Supabase as the backend-as-a-service and AWS Lambda for background toll scraping jobs.System Diagram
Service Responsibilities
| Service | Role |
|---|---|
| Next.js (Vercel) | SSR pages, API routes, static assets. All business logic runs here or in the browser. |
| Supabase Auth | Email/password auth, JWT tokens, session management. Every DB query filters by user_id. |
| Supabase PostgreSQL | 25+ tables. All data storage. RLS enforces multi-tenant isolation. |
| Supabase Storage | Vehicle photos (vehicle-photos bucket) and fleet documents (documents bucket). |
| Stripe | Subscription billing. Webhooks notify the app of payment events. |
| AWS Lambda | Background toll scraping. Triggered by EventBridge cron or manual API call. |
| Chrome Extension | Scrapes Turo earnings pages and sends CSV data to /api/turo/sync. |
Key Design Decisions
- No global state library — React hooks + Context API are sufficient. Custom hooks in
src/hooks/encapsulate all data fetching. - All DB queries filter by user_id — Multi-tenant isolation at the query level, backed by Supabase RLS.
- CSV as primary data format — Turo exports CSVs; toll agencies export CSVs. The import pipeline handles both.
- Client-side Supabase — Most DB calls happen directly from the browser using the Supabase JS client (with anon key + RLS). API routes are used only for server-side operations (webhooks, toll sync, extension auth).