shop-manager/CLAUDE.md

# Shop Manager (autoking)

Auto mechanic shop management tool for Tony Moon. Specializes in sublet work from other shops, direct customer jobs, and internal flip car work.

## Quick Start

```bash
# Terminal 1 — Server
cd server && npm run dev

# Terminal 2 — Client
cd client && npm run dev
```

App runs at http://localhost:5173 (Vite proxies API to :3001).
First run requires account creation — no default credentials.

## Tech Stack
- **Frontend**: React 19 + TypeScript + Vite + Tailwind CSS v4
- **State**: Zustand (auth/UI only), TanStack React Query (server data)
- **Icons**: Lucide React
- **Backend**: Node.js + Express 4 + TypeScript (via tsx)
- **Database**: SQLite (better-sqlite3) at `data/autoking.db`
- **PDF**: pdfkit for invoice generation
- **File uploads**: multer, stored in `data/uploads/`
- **Auth**: JWT + bcryptjs, token in localStorage as `autoking_token`
- **Deploy**: Docker + Docker Compose, ready for Unraid

## Project Structure
```
server/src/
  index.ts          — Express entry, route registration
  database.ts       — SQLite schema (all CREATE TABLE statements)
  middleware/auth.ts — JWT auth middleware (supports header + query param for PDF)
  routes/
    auth.ts           — login, register (first-run only), me, setup-required
    shops.ts          — referring shops CRUD + their jobs/invoices
    owners.ts         — vehicle owners CRUD
    vehicles.ts       — vehicles CRUD (supports inventory vehicles)
    jobs.ts           — work orders + labor/parts/notes sub-routes
    invoices.ts       — invoice CRUD + PDF generation + payments (shop + owner)
    estimates.ts      — estimates/quotes CRUD + items + convert-to-job
    canned-services.ts — saved service templates CRUD
    technicians.ts    — technician CRUD + clock in/out + time entries
    inspections.ts    — DVI templates + inspections + items + complete
    messages.ts       — internal messaging + templates + email settings
    appointments.ts   — scheduling + deferred services
    inventory.ts      — parts/supplies/tools inventory + purchase orders
    reports.ts        — 8 report endpoints (revenue, profitability, aging, etc.)
    fleets.ts         — fleet management + vehicle assignments
    dashboard.ts      — aggregated stats
    settings.ts       — business info for invoice headers
    tags.ts           — tag CRUD + job-tag associations
    files.ts          — file upload/download/delete (multer)
  services/pdf.ts   — PDF invoice generation with pdfkit
  types.ts          — all server-side TypeScript interfaces

client/src/
  App.tsx           — React Router setup, AuthGuard, QueryClient
  api/client.ts     — fetch wrapper with JWT, all API methods
  store/index.ts    — Zustand store (token, user, sidebar)
  types/index.ts    — all client-side TypeScript interfaces
  components/
    Layout.tsx      — sidebar + mobile nav
    KanbanBoard.tsx — drag-and-drop job kanban
    TagPicker.tsx   — tag management on jobs
    FileUpload.tsx  — file upload/display component
    ui/             — Button, Card, Badge, Input, Modal, EmptyState
  pages/
    Login.tsx, Dashboard.tsx, Shops.tsx, ShopDetail.tsx,
    Owners.tsx, OwnerDetail.tsx, Vehicles.tsx, VehicleDetail.tsx,
    Jobs.tsx, JobDetail.tsx, Estimates.tsx, EstimateDetail.tsx,
    Invoices.tsx, InvoiceDetail.tsx, Technicians.tsx,
    Appointments.tsx, Inventory.tsx, Reports.tsx, Settings.tsx
```

## Database Schema (key tables)
- `shops` — referring shops with per-shop labor rate + parts markup
- `owners` — vehicle owners (nullable on jobs for internal work)
- `vehicles` — customer cars + inventory/flip cars (is_inventory flag, purchase_price, inventory_status)
- `jobs` — work orders with customer_type (owner/shop/internal), technician_id, estimate_id; status: received → in_progress → completed → invoiced → closed
- `labor_items` — hourly OR flat_rate billing
- `parts_items` — quantity × unit_cost × (1 + markup)
- `job_notes` — activity log per job
- `tags` / `job_tags` — freeform color-coded tags on jobs, ships with presets
- `invoices` / `invoice_jobs` / `payments` — invoice bundling + partial payments (shop OR owner)
- `estimates` / `estimate_items` — quotes with approval workflow + convert to job
- `canned_services` / `canned_service_items` — reusable service templates
- `technicians` — shop techs with rates + specialties
- `time_entries` — clock in/out per technician per job
- `inspection_templates` / `inspection_template_items` — DVI templates
- `inspections` / `inspection_items` — per-job inspections with condition ratings
- `messages` / `message_templates` — internal messaging + templates
- `email_settings` — SMTP + Twilio config
- `appointments` — scheduling with status management
- `deferred_services` — declined work tracking
- `inventory_items` — parts, supplies, consumables with stock levels
- `inventory_transactions` — stock movement log
- `purchase_orders` / `purchase_order_items` — PO management
- `tools` — tool inventory with assignment tracking
- `fleets` / `fleet_vehicles` — fleet account management
- `files` — file attachments (entity_type + entity_id pattern, works for jobs/vehicles/invoices/inspection_items)
- `settings` — single row, business info for invoice headers
- `users` — auth (first-run registration only)

## Job Numbers
Format: `TM-{year}-{seq}` (e.g., TM-2026-0001). Auto-generated server-side.

## Invoice Numbers
Format: `INV-{year}-{seq}`. Auto-generated when creating invoice from completed jobs.

## Key Patterns
- Schema changes require deleting the SQLite db file (no migrations yet)
- Vite tsconfig has `verbatimModuleSyntax` — use `import type` for type-only imports
- `noUnusedLocals` / `noUnusedParameters` enforced in client
- LEFT JOIN for shops and owners (both nullable on jobs)
- File upload uses multer with `files` field name, max 10 files, 25MB each
- PDF endpoint accepts `?token=` query param (for opening in new browser tab)

## What's Built
- [x] Dashboard with stats
- [x] Shops (referring shops) CRUD with per-shop rates
- [x] Owners + Vehicles CRUD
- [x] Vehicle inventory tracking (flip cars with purchase price, status)
- [x] Jobs with 3 customer types: Vehicle Owner, Referring Shop, Internal/Flip
- [x] Labor items: hourly + flat rate billing
- [x] Parts items with markup
- [x] Job notes
- [x] Job tags (freeform + presets, color-coded)
- [x] Kanban board (drag-and-drop status changes)
- [x] List ↔ Kanban toggle on Jobs page
- [x] Inline quick-add for owners/vehicles/shops from job creation modal
- [x] Invoices from completed jobs (multi-job bundling)
- [x] PDF invoice generation
- [x] Payment tracking (partial payments, auto-status update)
- [x] File uploads on jobs, vehicles, invoices (local disk storage)
- [x] Settings (business info for invoices)
- [x] Docker + Docker Compose
- [x] Vehicle Detail page + Owner Detail page
- [x] Owner/direct customer invoicing (not just shops)
- [x] Estimates/Quotes system (draft → sent → approved → convert to job)
- [x] Canned/Saved Services (templates for common repairs)
- [x] Technician management (CRUD, assignment, hourly rates)
- [x] Technician time tracking (clock in/out per job)
- [x] Digital Vehicle Inspections (DVI) with templates, color-coded conditions, per-item photos/notes
- [x] Default multi-point inspection template (30 items across 5 sections)
- [x] Internal messaging system (log communications per job/customer)
- [x] Message templates (5 defaults: job started, job complete, estimate sent, invoice sent, appointment reminder)
- [x] Email/SMS settings (SMTP + Twilio config)
- [x] Appointment scheduling with status management
- [x] Deferred services tracking (declined work follow-ups)
- [x] Parts inventory management (stock tracking, low stock alerts, categories)
- [x] Shop supplies + consumables inventory
- [x] Inventory transactions (received, used, adjusted, returned)
- [x] Purchase orders (PO number generation, auto-receive to inventory)
- [x] Tool inventory (serial numbers, assigned technician, condition tracking)
- [x] Fleet management (fleet accounts, vehicle grouping)
- [x] Reports: Revenue summary, Job profitability, Revenue by shop, Receivables aging, Technician productivity, Top customers, Jobs by status, Inventory summary

## What's Next (TODO)
- [ ] Customer portal (customers view status, approve estimates, view inspections, pay online)
- [ ] S3-compatible file storage option (for SaaS)
- [ ] Database migrations (currently requires db delete on schema changes)
- [ ] Multi-location support
- [ ] QuickBooks Online integration
- [ ] Stripe payment processing
- [ ] NHTSA VIN decoder integration
- [ ] Automated email/SMS sending (nodemailer + twilio)
- [ ] Google Business review link integration
- [ ] Embeddable booking widget

## Competitors to Study
AutoLeap, ShopMonkey, ShopView — for feature parity and UX inspiration.

## Docker
```bash
docker compose up -d  # builds and runs on port 3001
```
Data persists in `autoking_data` volume. For Unraid, map to `/mnt/user/appdata/autoking/`.