# Tesla Roadtrip — Grok-Powered Planner (UK & Europe First)

Beautiful split-pane Tesla trip planner.

**Left side**: Natural language chat with Grok Drive (powered by the real xAI Grok API)  
**Right side**: Interactive Leaflet map + live itinerary that updates as you talk

## First Release Focus

- United Kingdom
- Europe (France, Germany, Benelux, Switzerland, Spain)

## Key Features

- Real Grok intelligence via the xAI API
- Excellent Supercharger coverage awareness across the UK & Europe
- Metric units (km, Wh/km)
- Proactive route planning — just say where you want to go
- Safe, restricted tool use

## Tech Stack

- Vite + React + Tailwind + Leaflet (client)
- Express + Prisma + pino (server)
- Real xAI Grok API (with local `grok` CLI as optional path)
- Heavy structured logging for fast debugging

## Local Development

### 1. Install dependencies

```bash
npm install
cd client && npm install && cd ..
```

### 2. Set up environment variables

```bash
cp .env.example .env
```

Then edit `.env` and add your xAI API key:

```env
XAI_API_KEY=xai-YourKeyHere
```

You can get a key from: https://console.x.ai

### 3. Start the development environment

You have two options:

**Option A (Recommended)** – Better developer experience:

```bash
./scripts/dev.sh
```

**Option B** – Using npm:

```bash
npm run dev
```

Both commands will start:
- **Backend**: http://localhost:3000 (with detailed logging)
- **Frontend**: http://localhost:5173

### 4. Open the app

Visit: **http://localhost:5173**

---

## Useful Commands

| Command                | Description                              |
|------------------------|------------------------------------------|
| `npm run dev`          | Start both frontend and backend          |
| `./scripts/dev.sh`     | Recommended way to start (better output) |
| `npm run dev:server`   | Start only the backend                   |
| `npm run dev:client`   | Start only the frontend                  |

---

## Security & Philosophy

This project follows a strict security policy:
- No packages with known active critical or high vulnerabilities
- `react-markdown` / remark ecosystem avoided (LLM output sanitization via DOMPurify)
- All AI tool use is heavily restricted
- Maximum logging so we can debug the "chat → route → stops" flow easily

## Deployment Target

Will be deployed via Dokku on Hetzner with Gitea CI.

First launch target: United Kingdom & Europe.

---

## Need Help?

- Make sure your `XAI_API_KEY` is set (otherwise you'll get very basic responses)
- Check the backend terminal — it has extremely detailed logs
- The app is designed so you can iterate quickly by watching the logs

---

## Development & Iteration Workflow (Autonomous Loop)

This project is designed for fast, autonomous iteration using Playwright.

### One-Command Iteration Loop

The recommended way to test and iterate is:

```bash
./scripts/iterate.sh
```

This script will:
1. Ensure both backend and frontend are running (via `./scripts/dev.sh`)
2. Run the fast backend diagnostic test (`smoke test`)
3. Run the full E2E Playwright test in headed mode
4. Open the Playwright HTML report
5. Show the latest screenshots and video
6. Print the most relevant backend log lines from the test window

After the script finishes, review the artifacts and tell me what to fix. Then just run `./scripts/iterate.sh` again.

### Fast Smoke Test (Backend Only)

When you only want to quickly test if Grok is responding (without waiting for the full UI flow):

```bash
./scripts/smoke.sh
```

This runs in ~30–90 seconds and is perfect for prompt tuning or backend debugging.

### Manual Commands

| Command                    | Description                              |
|---------------------------|------------------------------------------|
| `./scripts/dev.sh`        | Start both servers (recommended)         |
| `npm run dev`             | Start both servers (via npm)             |
| `./scripts/iterate.sh`    | Full autonomous test + report loop       |
| `./scripts/smoke.sh`      | Fast backend-only Grok test              |
| `npx playwright test`     | Run all Playwright tests manually        |

### Test Reports & Artifacts

- Playwright HTML report: `npx playwright show-report`
- Screenshots & videos: `test-results/`
- Backend logs: Look in your terminal or `/tmp/tesla-roadtrip-backend.log` (if you enabled logging to file)

### Workflow Summary

1. Make a code or prompt change
2. Run `./scripts/iterate.sh`
3. Review the report + screenshots + backend logs
4. Tell me what to fix
5. Repeat

This loop lets me drive most of the testing and debugging with minimal manual work from you.