garage-erp/FEATURE_GAP_PLAN.md

# Garage ERP — Feature Gap Plan vs. Industry Leaders

> Comparison of the current Reparee Garage ERP against established automotive
> workshop management platforms (GarageBox, Tekmetric, Shopmonkey, AutoLeap,
> Garage Hive, Mitchell 1 Manager SE, MaxxTraxx, Workshop Software).
>
> Goal: list what does **not** yet exist in this codebase, group it by impact,
> and give each gap an implementation hint so it can be picked up later.

---

## 1. What Reparee already has (baseline)

Captured from the current backend (`reparee_backend/`) controllers/models and
dashboard navigation (`apps/dashboard/config/navGroups.tsx`):

**Sales & service workflow**
- Customers (with notes, types, referral sources, import/export)
- Vehicles (owners, makes/models, body types, fuel, transmission, colors,
  documents, mileage history, import/export)
- Inspections + Inspection Templates (categories, checkpoints, labels)
- Public share link for inspections (token-based, rate-limited)
- Estimates → Job Cards → Invoices (services, parts, expense items, internal
  notes, labels, document attachments)
- Credit Notes
- Payments Received
- Appointments (calendar)

**Purchases**
- Vendors (addresses, status, credits)
- Expenses & Expense Items
- Purchase Orders (with internal notes, labels)
- Bills
- Payments Made
- Vendor Credits

**Items / inventory**
- Services and Service Groups (with includes/pricing/parts)
- Parts (with categories, unit types)
- Inventory Adjustments
- Labor Rates, Taxes

**HR / productivity**
- Employees (with documents, certifications, avatar, performance, permissions)
- Departments, Roles (with `permission.check` middleware on every route)
- Leave Requests + Leave Balance
- Payroll Runs + Entries + Slips
- Tasks, Task Sections, Task Types, TimeSheet
- Shop Calendar, Shop Timing, Holidays

**Platform**
- PDF generation via `DocumentPrintController` + Blade templates
- Document share tokens
- Settings (company, including logo + Terms & Conditions in `privacy_policy`)
- i18n EN/AR with RTL
- OpenAPI client (`packages/api/`) regenerated from backend spec

**Sidebar shows planned-but-disabled groups** (commented out in
`navGroups.tsx`): CRM (leads/calls/tasks), Marketing (service reminders,
ratings/reviews, Google reviews), Accountants (manual journals, chart of
accounts), Reports, Payroll, Integrations, Templates.

---

## 2. Priority matrix

| Tier | Meaning |
|------|---------|
| **P0** | Table-stakes for a modern garage SaaS — competitors all ship it, customers ask first |
| **P1** | Significant value-add, expected by mid-market shops |
| **P2** | Differentiators / nice-to-haves |
| **P3** | Long-tail integrations and advanced workflows |

---

## 3. P0 — Table-stakes gaps

### 3.1 Reporting & Analytics dashboard
**Status:** No `/reports` route exists; sidebar entry is commented out. A
`/` dashboard page exists but is not analytics-rich.

**What competitors ship:**
- Revenue by day/week/month, by service category, by technician
- Open jobs / WIP value, ARO (Average Repair Order), gross profit %
- Aging receivables (already implicit in invoices, no view)
- Parts margin, labor margin
- Technician productivity (billed hours vs. clocked hours)
- Inventory turnover, stock-outs
- Customer retention / first-visit vs. repeat

**Plan:**
- New backend controllers: `ReportController` exposing aggregations
  (revenue, AR aging, technician utilization, inventory turnover).
- New dashboard area: `apps/dashboard/app/(authenticated)/reports/`
  with sub-routes per report.
- Re-use TanStack Query + a chart lib already approved (or ask before adding
  recharts / visx). KPIs on home page should pull from the same endpoints.

### 3.2 Service Reminders (mileage- and time-based)
**Status:** `Vehicle` has mileage logs (`VehicleMileAndKm`) and documents
have expiry dates, but no reminder engine. Sidebar Marketing group is
commented out.

**What competitors ship:**
- "Next service in 5,000 km" rules per vehicle/service
- Insurance / registration / inspection expiry reminders
- Auto-send via email/SMS X days before due
- Customer can click to book

**Plan:**
- New model: `ServiceReminderRule` (per vehicle or template per make/model:
  due_at_date, due_at_mileage, service_group_id, channel).
- Scheduled job (Laravel scheduler) that scans daily and queues notifications.
- Channel adapters wired to the notification stack from §3.3.
- UI under `productivity` or new `marketing/` area.

### 3.3 Customer notifications (Email / SMS / WhatsApp)
**Status:** No notification channels found beyond document share links. No
`Notification` or messaging tables in models.

**What competitors ship:**
- Twilio/Vonage SMS, WhatsApp Business API
- Two-way SMS thread per customer/job (Tekmetric, Shopmonkey)
- Templated estimate-ready / job-ready / pickup-ready messages
- Inbox view of all customer conversations

**Plan:**
- Add `notification_channels` config + adapter interface
  (`App\Services\Notifications\Channel`).
- Provider drivers behind feature flags (SMS via Twilio/MessageBird, email
  via existing Laravel mail, WhatsApp via Meta Cloud API).
- Tables: `customer_messages` (inbound + outbound), `notification_templates`
  (subject/body, locale, type).
- Dashboard inbox under `/sales/customers/[id]/messages` + global `/inbox`.

### 3.4 Customer-facing portal (estimate approval, history)
**Status:** Only `PublicInspectionController` exists for public viewing.
Estimates and invoices have no customer-side approval flow.

**What competitors ship:**
- Customer logs in (or magic-link) and sees: vehicles, history, estimates,
  invoices, upcoming appointments.
- One-click approve / decline / partial-approve on estimate line items
  (digital authorization with audit trail).
- Pay invoice via portal.

**Plan:**
- Reuse `DocumentShare` token pattern, broaden into a `customer_portal_token`.
- New `PublicEstimateController` mirroring `PublicInspectionController`,
  with POST endpoints for approve/decline per line item.
- Persist signature/IP/timestamp on `EstimateAuthorisationHistory` (model
  already exists — confirm fields cover approvals from portal).
- Frontend: new public route group `app/portal/` (no auth, token-scoped).

### 3.5 Online payments
**Status:** `PaymentMode` table exists, payments are recorded manually. No
gateway integration.

**What competitors ship:**
- Stripe / Square / regional gateway integration
- "Pay invoice" link inside email/SMS
- Saved cards, partial payments, tips
- Reconciliation back to `PaymentRecieved`

**Plan:**
- Pluggable gateway driver under `App\Services\Payments\`.
- New endpoint `POST /api/invoices/{id}/payment-link` returns hosted URL.
- Webhook handler that creates `PaymentRecieved` rows on capture.
- Frontend `pay/[token]` page bundled with the portal in §3.4.

### 3.6 Audit log
**Status:** No audit/activity table found.

**What competitors ship:** Who changed what, when, on every business
record. Required for shops with multiple staff.

**Plan:**
- Adopt `spatie/laravel-activitylog` (request before adding the dep) or
  hand-roll a polymorphic `activity_log` table.
- Log on estimate/job-card/invoice state transitions, permission changes,
  payment events.
- Read-only view at `/settings/activity-log`.

### 3.7 Workflow / Kanban board for Job Cards
**Status:** Job Cards live in a list view. No status pipeline UI.

**What competitors ship:** Drag-and-drop columns ("Checked-in", "Awaiting
Parts", "In Progress", "QC", "Ready for Pickup"). Drives the shop's day.

**Plan:**
- Add `job_card_status` (enum or FK to `job_card_statuses` table editable
  in settings).
- Backend: status transition endpoint with allowed-transition guard.
- Frontend: new `/sales/job-cards/board` route using dnd-kit (already in
  the React ecosystem; confirm dep). Cards link to existing detail page.

### 3.8 Vehicle service history (per VIN, cross-customer)
**Status:** History is currently scoped via the vehicle's job cards, but
there is no consolidated "vehicle history" tab summarizing services,
inspections, mileage, and recommendations together.

**Plan:**
- New endpoint `GET /api/vehicles/{id}/timeline` merging job cards,
  inspections, recommendations, document expiries, mileage events into a
  single chronological feed.
- Tab on the vehicle detail page rendering the timeline.

### 3.9 Recommended / deferred work tracking
**Status:** `FastShopRecommendation` and `ShopRecommendation` models exist
but there is no "deferred services" view that follows the vehicle across
visits.

**Plan:**
- Extend recommendations with `status` (open/accepted/declined/expired) and
  `next_followup_at`.
- Surface on vehicle detail, estimate creation ("pull deferred items"), and
  in service-reminder logic (§3.2).

---

## 4. P1 — Significant value-add

### 4.1 Technician time tracking on job cards (clock in/out per labor line)
**Status:** Generic `TimeSheet` exists but is not bound to job-card lines.
The sidebar already shows "Time Clocks" — confirm whether implemented or
stubbed.

**Plan:**
- New table `job_card_labor_time` (job_card_service_id, employee_id,
  started_at, stopped_at).
- Mobile-friendly start/stop UI on the job-card page (tap-and-go).
- Feed billed-vs-clocked into the productivity report (§3.1).

### 4.2 Estimate templates / service packages with menus
**Status:** Service Groups exist (`ServiceGroup`, `ServiceGroupService`,
`ServiceGroupPart`, `ServiceGroupPricing`). Gap: no canned "menus" UI
(e.g., "30k-mile service" preset that drops services + parts + labor onto
an estimate in one click).

**Plan:**
- Repurpose Service Groups as menus; add a "Add menu" picker on the
  estimate editor that expands the group into individual lines (so they
  can still be edited).

### 4.3 Customer digital signature on documents
**Status:** Documents print to PDF; no signature capture.

**Plan:**
- Add a signature pad component (svg path → PNG) on the customer portal
  approval screen (§3.4) and in-shop tablet flow.
- Persist as a `document_signatures` row (signer name, type, timestamp,
  IP/UA, image blob in storage).
- Embed signature in printed PDF.

### 4.4 Parts barcode / QR scanning
**Status:** Parts have SKUs but no barcode field or scan UI.

**Plan:**
- Add `barcode` column to `parts`.
- Use the device camera (BarcodeDetector API) on the inventory adjustment
  and job-card "Add part" dialogs.

### 4.5 Tablet / shop-floor UI
**Status:** UI is desktop-first.

**Plan:**
- Audit job-card detail, inspection editor, and time-clock screens for
  touch targets and one-hand portrait use.
- Optional dedicated route `/floor/[job-card]` with a stripped-down layout.

### 4.6 Photos & videos on inspections (with public share)
**Status:** `InspectionCheckPointAttachment` and `InspectionAttachment`
models exist — confirm whether the share link renders attachments.

**Plan:**
- Verify the public inspection view (`PublicInspectionController@show`)
  exposes media URLs with signed access.
- Add front-camera capture in the inspection editor for fast photo-taking.

### 4.7 Multi-location / branch support
**Status:** `Settings` is single-tenant; no `branch_id` scoping on
business records.

**Plan:** This is a bigger lift. Phased:
1. Add `branches` table and `branch_id` FK on the major aggregates
   (job_cards, invoices, vehicles, parts, employees).
2. Default to a single seeded branch for existing deployments.
3. Add branch selector in header and scope queries via global scope.

### 4.8 Custom fields
**Status:** No custom-field infrastructure.

**Plan:**
- New `custom_field_definitions` (entity_type, key, label, type, options)
  and `custom_field_values` (polymorphic).
- Render dynamically on customer/vehicle/job-card forms.

### 4.9 Marketing campaigns
**Status:** Sidebar has the group commented out.

**Plan:**
- Reuse §3.3 channels.
- New `marketing_campaigns` (name, audience filter, template_id, schedule)
  and `marketing_sends` (per-recipient log).
- Audience builder uses the customer/vehicle filters already in the table
  views.

### 4.10 Ratings & reviews capture
**Plan:**
- Post-pickup auto-message asking for a rating (1–5) and free text.
- If 4–5, deep-link to Google review URL (configurable in settings).
- Internal review wall + ability to publish to a public testimonials
  endpoint.

### 4.11 Accounting export (QuickBooks / Xero / Zoho)
**Status:** No GL / chart of accounts (sidebar group is disabled).

**Plan (lightweight first):**
- CSV export of invoices, payments, bills, payments-made tagged with
  configurable account codes.
- Later: OAuth integration with QuickBooks Online / Xero APIs.

### 4.12 Tire & wheel module (heavy in GarageBox, Tekmetric)
**Plan:** Tire size lookup, DOT tracking, storage racks (off-season tire
storage is a common revenue line in cold-climate markets). Skip unless
target market needs it.

### 4.13 Warranty tracking on parts and services
**Plan:**
- Add `warranty_months` / `warranty_km` on parts and services.
- Show "under warranty" badge when re-invoicing the same VIN within the
  window. Block billing or flag for review.

### 4.14 Fleet customer accounts
**Plan:**
- Allow a customer to own many vehicles already supported, but add a
  "fleet" customer type with: bulk PO upload, monthly statement instead of
  per-invoice billing, optional driver/vehicle list.

### 4.15 Online appointment booking widget
**Plan:**
- Public route `/book` that surfaces shop services + free calendar slots
  (derived from `ShopTiming` and existing appointments).
- Creates a draft `Appointment` + customer/vehicle if new.
- Embed snippet for the shop's marketing site.

---

## 5. P2 — Differentiators

### 5.1 VIN decoder integration (NHTSA free API + paid Carfax)
- NHTSA `vpic.nhtsa.dot.gov/api/` is free, no auth — wire it into the
  vehicle create form to auto-fill make/model/year/engine from VIN.
- Carfax/AutoCheck for paid history reports (US/CA).

### 5.2 OEM repair info integration (Mitchell 1, AllData, Identifix, Haynes)
- Big lift, paid feeds. Out of scope for v1; design the parts/services
  data model so labor times can be imported.

### 5.3 Parts catalog integrations (WorldPac, NAPA PROLink, PartsTech)
- Real-time pricing + availability + ordering from inside a job card.
- Phase 1: PartsTech (aggregator) since it covers the most vendors.

### 5.4 Two-way calendar sync (Google / Microsoft)
- iCal feed for read-only first.
- Full two-way sync via Google Calendar API later.

### 5.5 AI-assisted estimate writer
- "Customer says: knocking noise on left front when braking" → suggested
  service lines + parts list from history of similar jobs. Useful and
  novel; defer until enough invoice data exists.

### 5.6 Mobile apps (technician + customer)
- React Native (or PWA first) sharing `@garage/api`.
- Technician: today's jobs, start/stop labor, take photos, mark complete.
- Customer: portal features (§3.4) packaged as an app.

### 5.7 OBD-II / telematics integration
- Long tail. Plan only the data model now (`vehicle_telemetry_events`).

### 5.8 Loyalty / gift cards / membership plans
- "Service plan: 2 oil changes/year + 10% off for $X/mo".
- Recurring billing on top of §3.5.

### 5.9 Discounts and promo codes at line-item or document level
- Currently no promo entity. Add `discounts` (code, type, %/amount, scope,
  expiry, usage cap) with hook in estimate/invoice totals.

### 5.10 Multi-currency
- `Settings` is implicitly single-currency. Add currency on documents and a
  daily rates table if shops need cross-border invoicing.

---

## 6. P3 — Long-tail / future

- Insurance claim workflow (estimator → adjuster handoff, photos packet,
  EMS export).
- Inventory replenishment automation (min/max → auto PO draft).
- Bay / lift management (assign job card to a bay; show bay utilization).
- AI photo damage assessment for inspections.
- Recall lookup (NHTSA recall API by VIN).
- TPMS / tire pressure history per vehicle.
- Public price-list / "instant quote" widget.
- Webhook system for third-party integrators.
- Bring-your-own-domain customer portal branding.
- Backup export of entire tenant data (GDPR-friendly).

---

## 7. Cross-cutting platform work

These aren't a single feature, but unlock many of the above:

1. **Background job runner** — Laravel Horizon + Redis if not already set
   up; required for §3.2, §3.3, §4.9.
2. **Storage policy** — confirm S3-compatible storage so signatures,
   media, and PDFs scale.
3. **Feature flag system** — many of the above are tenant-gated; even a
   simple `tenant_features` table beats hard-coded toggles.
4. **OpenAPI coverage** — every new backend endpoint must add an
   annotation so `packages/api` stays in sync (already a project
   convention).
5. **Permission seeds** — every new route requires a matching permission
   (project rule: routes are gated by `permission.check`).
6. **Lang pairs** — every `lang/en/*.php` key must have a matching
   `lang/ar/*.php` key (project rule).
7. **PDF template** — every new printable type needs an entry in
   `DocumentPrintController::TYPES` plus a Blade template under
   `resources/views/pdf/`.

---

## 8. Suggested phased roadmap

A pragmatic build order that maximizes early customer value and reuses
infrastructure:

**Phase 1 — "Looks competitive"** (P0 core)
- Reporting dashboard (§3.1)
- Workflow board for job cards (§3.7)
- Audit log (§3.6)
- Vehicle timeline (§3.8)
- Recommended / deferred work tracking (§3.9)

**Phase 2 — "Talks to the customer"**
- Notifications channel (§3.3) — SMS + email first
- Customer portal w/ estimate approval (§3.4)
- Online payments (§3.5)
- Service reminders (§3.2)
- Ratings & reviews capture (§4.10)

**Phase 3 — "Runs the shop floor"**
- Technician time tracking on labor (§4.1)
- Estimate menus / service packages UI (§4.2)
- Photos on inspections, end-to-end (§4.6)
- Customer digital signature (§4.3)
- Tablet / shop-floor UI polish (§4.5)

**Phase 4 — "Scales the business"**
- Multi-location (§4.7)
- Custom fields (§4.8)
- Marketing campaigns (§4.9)
- Online booking widget (§4.15)
- Accounting exports (§4.11)

**Phase 5 — "Differentiators"**
- VIN decoder (§5.1)
- Parts catalog integrations (§5.3)
- Calendar sync (§5.4)
- Loyalty / memberships (§5.8)
- Mobile apps (§5.6)

---

## 9. Open questions to confirm before starting

1. Target market geography — drives gateway choice (Stripe vs. local), SMS
   provider, accounting integration (QuickBooks vs. Zoho vs. Tally), and
   whether tire/snow modules matter.
2. Is multi-tenancy single-DB (current) or DB-per-tenant?
3. Are Horizon + Redis available in production today?
4. Is there an approved chart library, or does adding one need a green
   light? (CLAUDE.md says no new deps without approval.)
5. Should the customer portal share auth with the dashboard (Sanctum) or
   use a token-only public route like inspections do today?