# Admin Tool — Dealer Data Rebuild — Design Spec

**Date:** 2026-04-13  
**Project:** Jeep South Africa Dealer Locator (generalises to any brand)  
**File:** `admin.js`

---

## Overview

A single-file Node.js local server (`admin.js`) that provides a browser UI for rebuilding dealer data in `index.html` from the latest CSV. Designed to work per-brand: each brand folder has its own copy of `admin.js`, `build-data.js`, the CSV, and `index.html`. Running `node admin.js` opens a browser at `http://localhost:3000` — one button press rebuilds and embeds the data.

---

## Goals

- Zero npm dependencies (Node.js built-ins only: `http`, `child_process`, `fs`, `path`)
- Single file — copy into any brand folder and it just works
- Combines the two-step process (build data → embed) into one click
- Shows current state (CSV present, last rebuilt time, dealer count in `index.html`)

---

## Architecture

`admin.js` is a small Node.js HTTP server:

| Route | Method | Description |
|---|---|---|
| `/` | GET | Serves the admin HTML UI (inline in the JS file) |
| `/status` | GET | Returns JSON: CSV found, last rebuilt timestamp, current dealer count |
| `/rebuild` | POST | Runs rebuild pipeline, returns JSON result |

All HTML/CSS/JS for the UI is inlined as a template string in `admin.js`. No external files needed.

---

## Rebuild Pipeline (POST /rebuild)

Executed server-side in sequence:

1. **Spawn `node build-data.js`** — generates `dealers-data.js`
2. **Read `dealers-data.js`** — extract the `const DEALERS = [...]` array content
3. **Read `index.html`** — locate embed markers:
   - Start: `  <script>\nconst DEALERS = [`
   - End: `];\n  </script>`
4. **Replace** the section between markers with fresh data
5. **Write** updated `index.html`
6. **Delete** `dealers-data.js` (intermediate file, no longer needed)
7. **Return** `{ ok: true, count: N }` or `{ ok: false, error: "message" }`

---

## UI Components

### Header
- Title: project folder name (`path.basename(__dirname)`)
- Subtitle: "Admin — Dealer Data"

### Status Row
- CSV filename detected in folder (green tick if found, red warning if missing)
- "Last rebuilt" — reads from `index.html` mtime (file modification time)
- "Dealers in index.html" — count parsed from the current embed in `index.html`

### Rebuild Button
- Label: "Rebuild from CSV"
- Disabled and shows spinner while rebuild is in progress
- On success: button re-enables, status row updates

### Output Log
- Scrollable textarea-style area
- Streams lines as the rebuild progresses:
  - `> Running build-data.js...`
  - `> 33 dealers written to dealers-data.js`
  - `> Embedding into index.html...`
  - `> Done — 33 dealers in index.html` (green)
  - Or: `> ERROR: [message]` (red)

---

## Auto-Detection & Startup

On startup:
- Prints `Admin server running at http://localhost:3000` to terminal
- If CSV not found in `__dirname`: status row shows warning in UI (does not prevent server from starting)
- If `index.html` not found: rebuild button disabled with tooltip "index.html not found"

CSV filename is auto-detected: reads `*.csv` from `__dirname`, uses first match. Shown in status row.

---

## Error Handling

| Scenario | Behaviour |
|---|---|
| `build-data.js` exits non-zero | Returns `{ ok: false, error: stderr output }` |
| CSV not found | build-data.js will error; error surfaced in UI log |
| Embed markers not found in index.html | Returns `{ ok: false, error: "Embed markers not found in index.html" }` |
| Port 3000 in use | Server startup fails with clear message: "Port 3000 in use — kill the process or change PORT" |

---

## Port Configuration

Default port: `3000`. Override with env var: `PORT=3001 node admin.js`.

---

## Out of Scope

- No authentication (local tool only)
- No CSV upload (CSV must already be in the project folder)
- No git integration
- No multi-brand dashboard (each brand folder runs its own instance)