Architecture Overview

High-level system architecture and service boundaries

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

1. No global state library — React hooks + Context API are sufficient. Custom hooks in src/hooks/ encapsulate all data fetching.
2. All DB queries filter by user_id — Multi-tenant isolation at the query level, backed by Supabase RLS.
3. CSV as primary data format — Turo exports CSVs; toll agencies export CSVs. The import pipeline handles both.
4. 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).