Diagnostics Reader

An ASE-technician auto diagnostic app. A Next.js API + web client, powered by Claude, that runs a real mechanic-style diagnosis one test at a time and keeps each user's vehicles and history.

The diagnostic prompt and the Claude API key live on the server — never exposed to the browser.

The edge: it does what the big diagnostic subscriptions do — guided testing, don't-replace-yet warnings, fault isolation, repair confirmation — at a per-diagnosis API cost of pennies instead of a $20–200/month subscription.

---

What's in the box

• The API — POST /api/diagnose (start / advance a diagnosis) and GET /api/history (a user's saved jobs). The Claude key and the diagnostic prompt stay server-side.
• The web client — the macOS-styled Diagnostics Reader console (opens in any browser).
• Per-user data — every browser gets its own user, vehicles, and diagnosis history, stored in a database via Prisma.
• Cost guards — per-user rate limiting, input length caps, and a per-diagnosis turn cap so the Claude bill stays bounded (src/lib/limits.js).

src/
  lib/
    systemPrompt.js   <- the diagnostic prompt (server-only)
    anthropic.js      <- calls Claude, parses the JSON turn
    prisma.js         <- db client
    user.js           <- per-user identity (swap for real auth later)
    limits.js         <- input caps + rate limiter
  app/
    api/diagnose/route.js   <- start + advance a diagnosis
    api/history/route.js    <- saved jobs ("Garage")
    page.js                 <- the web UI
    globals.css
prisma/schema.prisma        <- User / Vehicle / Diagnosis

---

Run it locally (about 5 minutes)

You need Node.js 18+ installed.

# 1. install
npm install

# 2. set your secrets
cp .env.example .env
#    then open .env and paste your Claude API key from console.anthropic.com

# 3. create the database (SQLite file — zero setup)
npm run db:push

# 4. start it
npm run dev

Open http://localhost:3000.

---

Moving to Postgres (when you have real users)

Two edits, no rewrites:

1. In prisma/schema.prisma, change provider = "sqlite" to provider = "postgresql".
2. In .env, point DATABASE_URL at your Postgres instance.

Then npm run db:push again.

---

Real accounts (when you're ready)

The starter gives each browser its own guest user via an httpOnly cookie (src/lib/user.js). To add real login, replace getCurrentUser() with NextAuth / Clerk / Supabase Auth and return the authenticated user. Nothing else changes.

---

Before real production traffic

• Replace the in-memory rate limiter with a durable store (Upstash/Redis) if you run more than one instance.
• Set a spend cap on your Anthropic console so a runaway loop can't bill unbounded.
• Add real auth (above) — guest cookies are per-browser, not accounts.
• Add a privacy policy + terms if you take real users' data.

---

Deploying

• Web + API: Vercel is the fast path for Next.js. Add ANTHROPIC_API_KEY and DATABASE_URL as environment variables in the host — never commit .env.
• Database: any hosted Postgres (Neon, Supabase, RDS) once you outgrow SQLite.

---

Notes

• FORGE_MODEL in .env picks the Claude model (default claude-sonnet-5).
• Diagnostics Reader gives diagnostic guidance, not a guarantee — it tells users when a job is a stop-driving or go-to-a-shop situation, but a human still makes the call.