TruckLaneAnalyzerWebPrompt

gistfile1.txt

**ROLE**  
You are a senior JavaScript/TypeScript engineer designing an open‑source **Next JS 14 (App Router)** project named **“Truck Lane Analyzer.”**  
It will be deployed on Firebase Hosting + Functions + Firestore. The app must:

1. Accept lane‑data CSV uploads.  
2. Let users ask Gemini questions in natural language.  
3. Render dashboards & charts inline (React) and store them for later review.  

---

**CSV FORMAT (strict)**  
Same columns & validation rules as defined below:  
Origin, Destination, Distance_Miles (float), Cost_Per_Mile_Dollars (float), Average_Load_Weight_lbs (int), Rate_per_Load_Dollars (float), Deadhead_Percent (float).

---

**PROJECT STRUCTURE**  
/truck-lane-analyzer/
├─ src/
│ ├─ app/ # Next app router
│ │ ├─ page.tsx # Landing/upload
│ │ ├─ dashboard/ # /dashboard/[uploadId]
│ │ └─ api/ # Route handlers
│ ├─ components/
│ │ ├─ UploadDropzone.tsx
│ │ ├─ ChatPanel.tsx # Gemini Q&A
│ │ └─ ChartCard.tsx
│ ├─ lib/
│ │ ├─ firebase.ts # SDK init
│ │ ├─ parseCsv.ts # Papa Parse + zod validation
│ │ └─ geminiClient.ts # fetch wrapper + exponential back‑off
│ ├─ types/
│ │ └─ lane.ts # TypeScript types + zod schema
│ └─ styles/
├─ public/
├─ functions/ # Firebase Functions (TypeScript)
│ └─ geminiHandler.ts # secure Gemini calls
├─ .github/workflows/ci.yml # pnpm install, jest, eslint
├─ package.json (pnpm)
└─ README.md

markdown
Copy
Edit

---

**CORE REQUIREMENTS**

* **Type‑safe everywhere:**  
  * Use **zod** for runtime schema validation.  
  * Enable `"strictNullChecks": true` in `tsconfig.json`.

* **State management:**  
  * Rely on **React Server Components** where possible, use **use client** components only for interactivity.  
  * Store UI state with **zustand** (lightweight).

* **AI integration flow:**  
  1. Route handler `/api/query` sends `{question, laneStats}` to Firebase Function `geminiHandler`.  
  2. Function returns `{answerText, chartData}` (chart spec in Vega‑Lite JSON).  
  3. Frontend renders chart via **react‑vega**; answer text appears beside it.

* **Firebase usage:**  
  * **Cloud Storage**: raw CSV + generated PNG charts.  
  * **Firestore**: `{users/{uid}/uploads/{uploadId}}` doc contains parsed rows, summary stats, queries.  
  * Secure with Firebase Auth; use client SDK on the browser, Admin SDK in functions.

* **Modularity & future‑proofing:**  
  * Each domain (upload, chat, analytics) lives in its own folder with index barrel.  
  * All UI components documented with **Storybook**.  
  * Prop‑drilling avoided; hooks reside in `src/hooks/*`.

* **Testing & CI:**  
  * **Jest** + **React Testing Library** for components; **Vitest** in functions.  
  * GitHub Actions: push → lint, test, build, deploy preview to Firebase Hosting (preview channel).

* **Docs & OSS readiness:**  
  * Auto‑generate **API reference** with `typedoc`.  
  * Provide MIT LICENSE, CODE_OF_CONDUCT.md, and *rubric‑crosswalk.md* mapping to course criteria (A‑G).  

Return the full repository tree zipped, plus a step‑by‑step setup in the README (Node 20, pnpm, Firebase Tools).