> ## Documentation Index
> Fetch the complete documentation index at: https://dhanurgo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
graph TB
    subgraph Client["Browser"]
        WebApp["HostMetrics Web App<br/>(Next.js 15)"]
        Ext["Chrome Extension"]
    end

    subgraph Vercel["Vercel"]
        SSR["Next.js Server<br/>(App Router + API Routes)"]
    end

    subgraph Supabase["Supabase"]
        Auth["Auth (JWT)"]
        DB["PostgreSQL"]
        Storage["Storage Buckets"]
        Realtime["Realtime"]
    end

    subgraph AWS["AWS"]
        Lambda["Lambda Functions"]
        EventBridge["EventBridge<br/>(Cron Scheduler)"]
    end

    subgraph External["External Services"]
        Turo["Turo.com"]
        Stripe["Stripe"]
        TollPortals["Toll Portals<br/>(NTTA, EZPass, SunPass)"]
    end

    WebApp --> SSR
    Ext --> Turo
    Ext -->|"POST /api/turo/sync"| SSR
    SSR --> Auth
    SSR --> DB
    SSR --> Storage
    SSR --> Stripe
    SSR -->|"Invoke"| Lambda
    EventBridge -->|"Scheduled"| Lambda
    Lambda --> TollPortals
    Lambda --> DB
    Realtime -.->|"Live updates"| WebApp
```

## 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).