Initial commit — Shop Manager for Tony Moon

Full auto mechanic shop management tool: jobs, invoices, estimates, inspections, inventory, recommendations, technicians, appointments, reports, file uploads, kanban board, and more. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 00:08:35 -05:00
commit 8839412b52
100 changed files with 18510 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,179 @@
+# 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/`.