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

# 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

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

docker compose up -d  # builds and runs on port 3001

Data persists in autoking_data volume. For Unraid, map to /mnt/user/appdata/autoking/.