README.md

---
title: PotholeIQ
emoji: 🛣️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# PotholeIQ — Pothole Management on the Box Platform

One workflow from citizen intake to verified repair: AI photo classification
(YOLOv8), severity scoring, GIS mapping, supervisor review, crew dispatch,
digital closeout, and an auditable **before/after report** — with **Box** as the
content system of record and **Supabase** as the data mirror.

## Pages

| Page | Purpose |
|---|---|
| `/index.html` | Citizen submission portal (photo + GPS, AI classification) |
| `/command-center.html` | Supervisor Command Center (KPIs, map, approve/dispatch/resolve) |
| `/crew-closeout.html?case=ID` | Standalone crew closeout form (locked to one case) |
| `/case-report.html?case=ID` | Printable before/after report |
| `/track.html` | Citizen case tracking |

## Configuration (Space secrets → env vars)

**Box (required)**

| Secret | Example / note |
|---|---|
| `BOX_AUTH_MODE` | `client_credentials` |
| `BOX_CLIENT_ID` | Box app client id |
| `BOX_CLIENT_SECRET` | Box app client secret |
| `BOX_SUBJECT_TYPE` | `enterprise` |
| `BOX_SUBJECT_ID` | Box enterprise id |
| `BOX_INTAKE_FOLDER_ID` | Intake folder id |
| `BOX_CASE_ROOT_FOLDER_ID` | Case root folder id (often same as intake) |
| `BOX_METADATA_SCOPE` | `enterprise` |
| `BOX_METADATA_TEMPLATE_KEY` | `potholeCase` |

**Supabase (recommended — data mirror + supervisor login)**

| Secret | Note |
|---|---|
| `SUPABASE_URL` | `https://<ref>.supabase.co` |
| `SUPABASE_SECRET_KEY` | service-role key (server-side only) |
| `DASHBOARD_AUTH` | `true` to require supervisor login on dashboard APIs |

**Optional**

| Secret | Note |
|---|---|
| `CLOSEOUT_NOTIFY_RECIPIENTS` | Comma-separated default recipients for before/after reports |
| `BOX_AUTOMATE_SECRET` | Shared secret for Box Automate → `/api/box/automate-update` |
| `DATA_DIR` | Set to `/data/potholeiq` if HF persistent storage is enabled |
| `BOX_CASES_TTL_MS` | Box case-list cache TTL (default 45000) |

## Architecture notes

- **Box = source of truth for content**: photos, sidecars, generated documents,
  before/after PDFs (in `Closeout Reports`), metadata (`potholeCase` template).
- **Supabase = data mirror** (`db/schema.sql`, run once in the Supabase SQL editor).
- The local `data/` store is a working cache only — safe to lose on restarts.
- First AI classification after a cold start takes ~30–60 s (model load).