A single-tenant vehicle service shop platform. One deployment per shop — no tenant glue, no shared customer data, no multi-tenant compromises in the schema.
All 12 build modules are complete. The codebase is ~71 Prisma models, ~133 API routes, and ~57 smoke test suites on Next.js 14 + Postgres. See plans/00-master-plan.md for the full module map and SESSION-LOG.md for the chronological build log.
This is a clean-room rebuild — every model, function, component, and line of prose is original work. See CLEAN-ROOM.md before contributing.
Front of house (sales + service writing) Lead capture, opportunity pipeline (drag-reorder kanban), quoting with line-item builder + PDF export, activity timeline, sales goals, and a real sales-performance report.
Shop floor (service ops) Work orders with typed line items, technician assignment, bay scheduling, arrival + PDI inspections, QC lane, change orders, and live time tracking with submit → approve → lock.
Parts Inventory with reorder points, vendor records, part transactions (issue / receive / adjust / transfer), reservations against work-order lines, and a parts-inventory report (low-stock, turn, dead-stock, vendor responsiveness).
Accounting Ready-to-bill queue, approved-estimate and change-order totals MTD, warranty recovery tracking, and a dedicated financial closeout report with CSV + PDF export.
Customer portal Tokenized customer access to their work orders, estimates, uploads, and two-way messaging. Portal magic links go through a templated email pipeline.
Knowledge base + training In-app markdown articles with versioning, categories, and per-user training assignments with completion tracking.
Ripple video Internal walkaround-video platform tied to work orders and vehicles. Upload, playback, and shareable links.
Bolts AI assistant Local-first AI assistant with a retrieval layer over the full DB, read-only tools, and a confirmed-write flow for mutating actions. Provider-adapter design — swap mock / Ollama / hosted without touching tool code.
Admin + reports Role-aware home dashboard across 12 roles, a reports hub with per-user drag-reorder and show/hide persistence, detailed service / sales / parts / closeout report screens, CSV on everything and PDF on the two screens where print is a real workflow, admin surfaces for users, audit log, data exceptions, feature flags, and owner support impersonation.
Integrations
Templated emails (Resend) with persisted EmailSend rows per attempt. Outbound webhooks with HMAC-SHA256 signing, per-endpoint secrets, exponential-backoff retries (1m → 24h, capped at 6 attempts), and an owner-only configuration UI. A public read API under /api/public/v1/* behind hashed, scoped API keys with a 60 requests-per-minute rate limit.
Billing Stripe-driven license gate. Webhook signature verification, subscription mirror with out-of-order event handling, and a non-destructive owner-only banner when billing needs attention. Feature access stays intact when a subscription lapses — the banner prompts, it doesn't lock.
Background jobs
Vercel Cron fires /api/cron/process-webhooks every five minutes to drive the webhook delivery queue and sweep stale rate-limit rows. Authenticated with a shared CRON_SECRET so only Vercel's cron scheduler can invoke it.
Next.js 14 (App Router) · TypeScript strict · Tailwind CSS · Prisma 7 on PostgreSQL via Supabase pooler · cookie-based sessions + CSRF double-submit (not JWT) · pdf-lib · @dnd-kit · Resend · Stripe · AWS S3 · Vercel + Vercel Cron.
Auth and CSRF are load-bearing — read lib/auth.ts and lib/csrf.ts before touching anything that talks to sessions.
git clone https://github.com/fruitmob/home-base.git
cd home-base
npm install
cp .env.example .env # fill in local Supabase URLs + SESSION_SECRET
npx prisma migrate deploy
npx prisma db seed # owner + dev demo data
npm run dev # http://localhost:3000AGENTS.md covers the fuller local-dev path and the clean-room expectations for anyone writing code here. CLAUDE.md is the onboarding doc for AI agents working in this repo.
Tests run with tsx against a live Postgres:
npm run test # all 57 smoke suites, end to end
npm run seed:demo # Cedar Ridge Service demo tenant (idempotent)Home Base ships one deployment per shop. Provisioning a fresh stack is a one-hour runbook:
- DEPLOYMENT.md — 12-section playbook: Supabase project, Vercel project, env matrix, migrations, Cedar Ridge demo seed, Stripe wiring, API-key issuance, post-deploy smoke, role walkthrough, DNS cutover, cron verification, uptime monitoring.
- RECOVERY.md — Supabase PITR restore to a new project, verification on a preview, cutover, and post-incident hygiene.
- scripts/seed-demo.ts — the Cedar Ridge Service demo tenant. Six staff across the major roles, three customers, six vehicles, ~40 parts, 12 work orders in mixed statuses, a KB article, a training assignment, and a Ripple video. Safe to run twice.
- scripts/deploy-smoke.ts — post-deploy harness. Walks
/api/healthand all four public read endpoints against any reachable URL. Read-only.
- plans/ — one file per module.
00-master-plan.mdis the index. Each module's plan has its charter, hard requirements, step-level tasks, and completion notes. - SESSION-LOG.md — append-only, newest first. Pick up any cold session by reading the top entry.
- prisma/schema.prisma — the full schema. prisma/migrations/ holds hand-reviewed SQL.
- app/ — Next.js App Router. UI under
app/(app)/andapp/(auth)/. API routes underapp/api/, includingapp/api/public/v1/*for the public read surface. - lib/ — shared server logic, grouped by domain:
auth,audit,csrf,core,reports,email,webhooks,api-keys,billing,cron,bolts,shop,sales,admin. - components/ — React components (server and client). Client components are marked with
"use client". - tests/ — smoke tests. One file per module surface; every suite is runnable on its own with
npx tsx tests/<name>-smoke.test.ts. - scripts/ — operational utilities (demo seeder, deploy smoke).
Proprietary clean-room rebuild. CLEAN-ROOM.md covers the hard rules every contributor agrees to before editing this repo.
