CarCompass is your end-to-end car buying wingman

Existing alternatives

• Listings marketplaces (Autotrader, Cars.com, CarGurus): strong inventory search, weak personalized guidance and post-purchase ownership.
• Research sites (Edmunds, KBB): good editorial + pricing, limited workflow continuity and user-specific decision modeling.
• Price/negotiation tools (TrueCar-style): pricing focus, often funnels to dealers; limited transparency and ownership support.
• Maintenance apps (Carfax Car Care, OEM apps): post-purchase only; no linkage to purchase decision or negotiation.

Why they are insufficient

• Fragmented journey: users bounce between 5–10 tools, re-entering the same constraints repeatedly.
• Trim/option confusion: model-year-trim packages are inconsistent; users can’t reliably compare “equivalent” vehicles.
• Pricing opacity: “fair price” varies by region, mileage, condition, incentives; users lack a clear band and negotiation plan.
• TCO blind spots: buyers optimize monthly payment but miss insurance, fuel, maintenance, depreciation.
• Post-purchase drop-off: reminders/recalls/resale are disconnected from the purchase context.

Pain points

• First-time buyers don’t know what to prioritize or what questions to ask.
• Experienced buyers still waste time normalizing trims, checking VINs, and estimating ownership costs.
• Negotiation anxiety: uncertainty about what’s reasonable and how to respond to dealer tactics.

Market inefficiencies

• Data exists (pricing, specs, recalls) but is not unified into a user-specific, end-to-end workflow.
• High-intent users are valuable, but current funnels optimize for lead capture rather than decision quality.

Primary persona: First-time / low-confidence buyer

• Age: 22–35
• Needs: guidance, clarity, budget safety, negotiation scripts, avoid bad deals
• Behavior: mobile-first, searches evenings/weekends, wants step-by-step checklists
• Technical maturity: moderate; expects modern UX and clear explanations

Secondary persona: Time-constrained experienced buyer

• Age: 30–55
• Needs: fast shortlist creation, trim decoding, TCO, price banding, VIN checks
• Behavior: desktop + mobile, wants exportable comparisons and actionable negotiation plan
• Technical maturity: moderate-high

Buying behavior (SaaS-like)

• Will pay for high-stakes moments: negotiation pack, VIN report bundle, TCO report, recall monitoring.
• Prefers monthly subscription only if it provides ongoing ownership value (maintenance + resale tracking).

MVP scope (8–12 weeks build)

Focus on a coherent workflow with real utility, using a mix of first-party logic + third-party data.

1) Account + onboarding

• Email/password + OAuth (Google/Apple)
• Onboarding quiz:
  • Budget range, location (ZIP), new/used, body type, seats, commute, annual mileage, must-haves
  • Financing intent (cash/loan/lease) and credit band (optional)

2) Vehicle discovery + shortlist

• Vehicle search by make/model/year + filters (price, mileage, body type)
• “Recommended for you” list based on quiz scoring
• Shortlist (save vehicles) with notes and tags

3) Trim decoder (normalized specs)

• For a selected vehicle (make/model/year/trim):
  • Display key specs (engine, drivetrain, MPG, safety features)
  • “What this trim includes” summary
  • Highlight missing must-haves

4) Side-by-side comparison

• Compare up to 4 vehicles:
  • Price, mileage, MPG, cargo, safety features, warranty (if available)
  • Fit score + explanation (top 3 reasons)

5) Total cost of ownership (TCO) forecast (simplified)

• 3-year and 5-year estimates:
  • Fuel cost (based on MPG + user annual mileage + regional fuel price default)
  • Maintenance baseline (heuristic by segment + mileage)
  • Depreciation proxy (simple curve by age + mileage)
  • Insurance placeholder (user-entered or regional average)

6) Negotiation toolkit (lightweight)

• Fair price band estimate (MVP heuristic):
  • Use market comps from a data provider if available; otherwise compute from user-entered listing price vs typical range by model/year/mileage.
• Dealer playbook:
  • Checklist + scripts (exportable PDF)
  • “Out-the-door price” calculator (tax/fees by state defaults + user overrides)

7) Ownership basics

• Add owned vehicle (manual entry or from shortlist)
• Maintenance reminders (time/mileage-based templates)
• Recall alerts (via NHTSA API by VIN)

8) Admin + analytics

• Admin panel: manage vehicle metadata mappings, content snippets, feature flags
• Event tracking: quiz completion, shortlist adds, compare usage, conversion to paid

Explicit non-goals for MVP

• Full inventory ingestion across dealers
• Real-time dealer messaging
• Full financing marketplace

High-level components

• Frontend: Next.js web app (responsive; can be wrapped later for mobile)
• Backend API: Node.js (NestJS) or Next.js API routes (prefer separate service for scale)
• Database: Postgres for relational data; Redis for caching/rate limiting
• Search: Postgres full-text + trigram indexes for MVP; optional Meilisearch later
• External services:
• NHTSA recalls API (VIN → recalls)
• Vehicle specs/trim data provider (optional; otherwise seed curated dataset)
• Analytics (PostHog)
• Email (Resend)
• Payments (Stripe)

Deployment

• Vercel for frontend
• Backend on Fly.io/Render/Railway
• Postgres on Supabase/Neon
• Redis on Upstash

Data flow

1. User completes quiz → stored as preference profile.
2. User searches/selects vehicles → normalized vehicle entities + shortlist items.
3. Comparison/TCO endpoints compute derived metrics server-side.
4. Ownership: VIN stored → scheduled recall checks + reminder scheduler.

Mermaid diagram

flowchart LR
  U[User Browser] --> FE[Next.js Frontend]
  FE --> API[Backend API]
  API --> PG[(Postgres)]
  API --> R[(Redis Cache)]
  API --> STRIPE[Stripe]
  API --> NHTSA[NHTSA Recalls API]
  API --> ANALYTICS[PostHog]
  API --> EMAIL[Resend]

  subgraph Jobs
    CRON[Scheduler/Worker]
  end
  CRON --> API
  CRON --> PG
  CRON --> NHTSA

Core entities

Use normalized vehicle tables to support comparisons and trim decoding.

SQL-style schema (MVP)

-- Users
create table users (
  id uuid primary key,
  email text unique not null,
  password_hash text,
  oauth_provider text,
  created_at timestamptz not null default now()
);

-- User preferences from quiz
create table user_preferences (
  id uuid primary key,
  user_id uuid not null references users(id) on delete cascade,
  zip text,
  budget_min int,
  budget_max int,
  new_or_used text check (new_or_used in ('new','used','either')),
  body_types text[],
  seats_min int,
  annual_miles int,
  must_haves text[],
  created_at timestamptz not null default now()
);
create index on user_preferences(user_id);

-- Vehicle normalization
create table makes (
  id bigserial primary key,
  name text unique not null
);
create table models (
  id bigserial primary key,
  make_id bigint not null references makes(id),
  name text not null,
  unique(make_id, name)
);
create table vehicle_trims (
  id bigserial primary key,
  model_id bigint not null references models(id),
  year int not null,
  trim_name text not null,
  drivetrain text,
  engine text,
  transmission text,
  mpg_city numeric,
  mpg_hwy numeric,
  body_type text,
  seats int,
  msrp int,
  features jsonb not null default '{}',
  unique(model_id, year, trim_name)
);
create index vehicle_trims_model_year_idx on vehicle_trims(model_id, year);
create index vehicle_trims_features_gin on vehicle_trims using gin(features);

-- Listings (optional for MVP; can be user-entered)
create table listings (
  id uuid primary key,
  source text,
  external_id text,
  vehicle_trim_id bigint references vehicle_trims(id),
  vin text,
  price int,
  mileage int,
  dealer_name text,
  location_zip text,
  url text,
  fetched_at timestamptz,
  created_at timestamptz not null default now(),
  unique(source, external_id)
);
create index listings_trim_price_idx on listings(vehicle_trim_id, price);
create index listings_vin_idx on listings(vin);

-- Shortlist
create table shortlists (
  id uuid primary key,
  user_id uuid not null references users(id) on delete cascade,
  name text not null default 'My Shortlist',
  created_at timestamptz not null default now()
);
create table shortlist_items (
  id uuid primary key,
  shortlist_id uuid not null references shortlists(id) on delete cascade,
  vehicle_trim_id bigint references vehicle_trims(id),
  listing_id uuid references listings(id),
  note text,
  created_at timestamptz not null default now()
);
create index on shortlist_items(shortlist_id);

-- Owned vehicles
create table owned_vehicles (
  id uuid primary key,
  user_id uuid not null references users(id) on delete cascade,
  vehicle_trim_id bigint references vehicle_trims(id),
  vin text,
  purchase_price int,
  purchase_date date,
  current_mileage int,
  created_at timestamptz not null default now()
);
create index owned_vehicles_user_idx on owned_vehicles(user_id);
create index owned_vehicles_vin_idx on owned_vehicles(vin);

-- Maintenance reminders
create table maintenance_reminders (
  id uuid primary key,
  owned_vehicle_id uuid not null references owned_vehicles(id) on delete cascade,
  title text not null,
  due_date date,
  due_mileage int,
  cadence_months int,
  cadence_miles int,
  last_completed_date date,
  last_completed_mileage int,
  created_at timestamptz not null default now()
);
create index on maintenance_reminders(owned_vehicle_id);

-- Recall cache
create table vin_recalls (
  id uuid primary key,
  vin text not null,
  payload jsonb not null,
  fetched_at timestamptz not null default now(),
  unique(vin)
);
create index vin_recalls_vin_idx on vin_recalls(vin);

Relationships

• users 1—N user_preferences
• makes 1—N models 1—N vehicle_trims
• users 1—N shortlists 1—N shortlist_items → (vehicle_trims or listings)
• users 1—N owned_vehicles 1—N maintenance_reminders

Auth

• JWT-based session (httpOnly cookies) or NextAuth session cookies.
• All user-specific endpoints require auth.

Core endpoints (REST)

Auth

• POST /api/auth/signup
• POST /api/auth/login
• POST /api/auth/logout
• GET /api/me

Preferences / quiz

• POST /api/preferences create/replace preferences
• GET /api/preferences

Request

{
  "zip": "94107",
  "budgetMin": 15000,
  "budgetMax": 25000,
  "newOrUsed": "used",
  "bodyTypes": ["SUV", "Hatchback"],
  "seatsMin": 5,
  "annualMiles": 12000,
  "mustHaves": ["CarPlay", "AWD"]
}

Vehicle catalog

• GET /api/vehicles/makes
• GET /api/vehicles/models?make=Toyota
• GET /api/vehicles/trims?modelId=123&year=2021
• GET /api/vehicles/trim/:id

Recommendations

• GET /api/recommendations?limit=20 Returns ranked trims with fit score + reasons.

Response

{
  "items": [
    {
      "vehicleTrimId": 9912,
      "label": "2021 Toyota RAV4 XLE AWD",
      "fitScore": 0.86,
      "reasons": ["Matches AWD must-have", "Within budget", "5 seats"]
    }
  ]
}

Comparison

• POST /api/compare

Request

{ "vehicleTrimIds": [9912, 8811, 7722] }

TCO

• POST /api/tco

Request

{
  "vehicleTrimId": 9912,
  "purchasePrice": 22000,
  "annualMiles": 12000,
  "years": 5
}

Shortlist

• POST /api/shortlists
• GET /api/shortlists
• POST /api/shortlists/:id/items
• DELETE /api/shortlists/:id/items/:itemId

Negotiation tools

• POST /api/negotiation/otd out-the-door calculator
• GET /api/negotiation/playbook returns scripts/checklists
• GET /api/pricing/fair-band?vehicleTrimId=9912&zip=94107&mileage=45000

Ownership

• POST /api/owned-vehicles
• GET /api/owned-vehicles
• POST /api/owned-vehicles/:id/reminders
• GET /api/owned-vehicles/:id/recalls (uses VIN)

Notes

• Prefer server-side computation for scoring/TCO to keep logic consistent and protect heuristics.
• Add idempotency keys for Stripe and for any “create” endpoints that may be retried.

Recommended stack

Frontend

• Next.js (App Router) + TypeScript + Tailwind
  • Fast iteration, SSR for SEO (vehicle pages), strong ecosystem.
• UI: shadcn/ui for consistent components.

Backend

• NestJS (TypeScript)
  • Clear module boundaries (auth, vehicles, recommendations, ownership), good for scaling beyond MVP.
  • Alternatively: Next.js API routes for fastest MVP, but separation becomes painful.

Database

• Postgres
  • Relational fit for normalized vehicle data + user entities.
• Prisma ORM
  • Strong TypeScript integration and migrations.

Caching / rate limiting

• Redis (Upstash)
  • Cache recall responses, pricing computations, and apply per-IP/user rate limits.

Analytics

• PostHog
  • Product analytics + feature flags without heavy setup.

Payments

• Stripe
  • One-off purchases + subscriptions.

Hosting

• Frontend: Vercel
• Backend: Fly.io (simple deploy, regions) or Render
• DB: Neon/Supabase

Optional alternatives

• Search: Meilisearch if catalog grows and filtering becomes complex.
• Mobile: React Native/Expo once web workflow is validated.

Authentication

• Use OAuth + email/password.
• Store passwords with argon2id.
• Session via httpOnly secure cookies; rotate refresh tokens if using JWT.

Authorization

• Row-level checks on all user-owned resources (shortlists, owned vehicles, reminders).
• Admin routes behind role-based access (users.role in ['admin']).

Data protection

• Encrypt sensitive fields at rest if stored (VIN is moderately sensitive; treat as personal data).
• TLS everywhere.
• Avoid storing full payment details (Stripe handles).

Rate limiting + abuse

• Per-IP limits on auth endpoints.
• Per-user limits on recall/VIN lookups and pricing endpoints.
• Bot protection on public search endpoints (basic: rate limit + caching).

Threat considerations

• Scraping of vehicle catalog: mitigate with caching, rate limits, and pagination caps.
• Prompt injection not applicable unless LLM features are added; if added later, isolate tools and sanitize outputs.
• PII handling: clear data retention policy; allow account deletion.

Pricing model

Hybrid: free core workflow + paid “high-intent” tools.

Free

• Quiz + recommendations
• Shortlist + comparisons
• Basic TCO (limited scenarios)
• Basic maintenance reminders

Paid (MVP)

1. Negotiation Pack (one-time): $19–$49

• OTD calculator with state fee presets
• Dealer script pack PDF
• Fair price band + comps explanation

2. Ownership Plus (subscription): $5–$10/mo

• Recall monitoring + email alerts
• Maintenance schedules + history
• Resale tracking (basic)

3. VIN bundle add-on (pass-through + margin)

• If integrating a paid VIN history provider later.

Unit economics assumptions

• CAC initially low via content/SEO.
• Gross margin high (software) except VIN reports.
• Primary cost drivers: data provider fees, hosting, analytics.

Distribution strategy

• SEO-first: programmatic pages for make/model/year/trim explainers and comparison pages.
• Content: negotiation checklists, “trim decoder” guides, TCO explainers.
• Partnerships: driving schools, personal finance creators, credit unions (later).

Channels

• Organic search (vehicle comparisons, trim meanings, OTD calculators)
• YouTube/TikTok creators for first-time buyer education (affiliate links)
• Reddit/communities (r/whatcarshouldIbuy) with helpful tools (not spam)

Launch plan

1. Ship MVP with 20–50 popular models/trims seeded.
2. Publish 100+ programmatic pages (trim decoder + comparisons).
3. Offer negotiation pack free to first 200 users for feedback.

Growth loops

• Shareable comparison links (read-only) → new users.
• “OTD calculator” embedded widget → backlinks.
• Recall alerts → retention.

Validate before full build

1) Concierge MVP (1–2 weeks)

• Landing page + waitlist.
• Manual quiz (Typeform) → generate a shortlist + negotiation checklist manually.
• Measure willingness to pay for negotiation pack.

2) Prototype testing (2–3 weeks)

• Build only: quiz → shortlist → comparison.
• Use a small curated dataset (top 30 vehicles).
• Run user interviews while they complete tasks.

MVP testing approach

• Instrument funnel:
  • Visit → quiz start → quiz complete → shortlist add → compare → negotiation tool use → purchase intent.
• A/B test:
  • Fit score explanations vs none.
  • One-time negotiation pack price points.

Metrics

• Activation: % completing quiz and saving ≥1 vehicle.
• Engagement: comparisons per user, return rate within 7 days.
• Conversion: negotiation pack purchase rate.
• Retention: recall alert opt-in, reminder completion.

Phase 1 (MVP) — 8–12 weeks

• Auth + onboarding quiz
• Vehicle catalog + trim decoder
• Recommendations + shortlist
• Comparison + basic TCO
• Negotiation playbook + OTD calculator
• Ownership: reminders + NHTSA recall alerts
• Stripe payments (one-time + subscription)

Phase 2 — 3–4 months

• Better pricing intelligence (regional comps, mileage adjustments)
• VIN decode + richer vehicle configuration
• Programmatic SEO expansion + shareable comparison pages
• Mobile-friendly PWA enhancements

Phase 3 — 6–12 months

• Inventory integrations (dealer feeds) and alerting for matching listings
• Financing/insurance integrations (optional)
• Personalized depreciation/resale models
• Community owner insights (structured reviews tied to trims)

Technical risks

• Vehicle trim normalization is messy; provider data may be inconsistent.
• Pricing accuracy: poor estimates reduce trust.
• Scaling catalog/search without a dedicated search engine.

Market risks

• Users may default to marketplaces for inventory; CarCompass must prove value without listings.
• Monetization: negotiation pack must be compelling enough to pay.

Legal risks

• Pricing guidance must be framed as informational, not guarantees.
• Data licensing compliance for any third-party vehicle/pricing datasets.
• Privacy obligations for VIN and location data.

Competitive risks

• Marketplaces can add “guidance” features quickly.
• Differentiation depends on workflow continuity + clarity.

Future features

• Inventory alerts: notify when a matching listing appears within radius.
• Dealer offer tracker: upload buyer’s order, parse fees, flag add-ons.
• Document scanner: parse VIN, trim, MSRP from window sticker.
• Financing optimizer: compare loan offers, compute total interest.
• Insurance estimator integrations.
• Maintenance log + resale readiness score.
• Community insights: owner-reported real MPG, common issues by trim.

Scalability direction

• Move to event-driven jobs (BullMQ/Cloud Tasks) for recall checks and reminders.
• Introduce search service (Meilisearch/Elastic) when catalog grows.
• Add feature store-like tables for scoring signals.

You are a senior full-stack engineer building the MVP of CarCompass: an end-to-end car buying workflow app (discover → evaluate → negotiate → own).

TECH STACK
- Frontend: Next.js (App Router) + TypeScript + Tailwind + shadcn/ui
- Backend: NestJS (TypeScript) REST API
- DB: Postgres + Prisma
- Cache/rate limit: Upstash Redis
- Auth: email/password (argon2id) + optional Google OAuth; session via httpOnly cookies
- Payments: Stripe (one-time product + subscription)
- Analytics: PostHog events
- Email: Resend
- External API: NHTSA recalls (VIN)

DELIVERABLES
1) Monorepo with /apps/web and /apps/api and /packages/shared
2) Working local dev with docker-compose for Postgres + Redis
3) Prisma schema + migrations matching the provided schema
4) REST API with OpenAPI/Swagger docs
5) Web UI implementing the full MVP workflow
6) Seed script to load a small vehicle catalog (makes/models/trims) from JSON
7) Background job/scheduler for recall refresh and reminder emails
8) Stripe checkout + webhook handling

PROJECT STRUCTURE
- apps/web: Next.js app
  - routes: /onboarding, /recommendations, /shortlist, /compare, /tco, /negotiate, /own
  - components: VehicleCard, CompareTable, TcoChart, OtdCalculator, RecallPanel
- apps/api: NestJS
  - modules: auth, users, preferences, vehicles, recommendations, shortlists, compare, tco, negotiation, ownership, billing
- packages/shared:
  - zod schemas for request/response DTOs
  - shared types and utility functions

DATABASE SCHEMA
Implement tables:
- users, user_preferences
- makes, models, vehicle_trims
- listings (optional but include table)
- shortlists, shortlist_items
- owned_vehicles, maintenance_reminders
- vin_recalls
Add indexes as specified.

API ENDPOINTS (must implement)
Auth:
- POST /auth/signup, /auth/login, /auth/logout, GET /me
Preferences:
- POST /preferences, GET /preferences
Vehicles:
- GET /vehicles/makes
- GET /vehicles/models?make=...
- GET /vehicles/trims?modelId=...&year=...
- GET /vehicles/trim/:id
Recommendations:
- GET /recommendations?limit=...
Comparison:
- POST /compare { vehicleTrimIds: number[] }
TCO:
- POST /tco { vehicleTrimId, purchasePrice, annualMiles, years }
Negotiation:
- POST /negotiation/otd { price, state, docFee?, taxRate?, registrationFee? }
- GET /negotiation/playbook
- GET /pricing/fair-band?vehicleTrimId&zip&mileage
Shortlist:
- POST /shortlists
- GET /shortlists
- POST /shortlists/:id/items
- DELETE /shortlists/:id/items/:itemId
Ownership:
- POST /owned-vehicles
- GET /owned-vehicles
- POST /owned-vehicles/:id/reminders
- GET /owned-vehicles/:id/recalls
Billing:
- POST /billing/checkout (one-time and subscription)
- POST /billing/webhook (Stripe)

BUSINESS LOGIC REQUIREMENTS
- Recommendation scoring: implement a deterministic scoring function using preferences:
  - budget fit, body type match, seats >= min, must-have features present in vehicle_trims.features
  - return fitScore 0..1 and top reasons
- TCO: implement simplified model:
  - fuel = annualMiles/mpgCombined * fuelPrice
  - maintenance = baseRateByBodyType * years
  - depreciation = purchasePrice * depreciationCurve(years, vehicleAge)
  - insurance = user provided or default constant
- Fair price band (MVP):
  - if listings exist for same trim/year: compute percentile band (25th-75th) adjusted by mileage
  - else: return heuristic band around msrp or purchasePrice
- Recalls:
  - call NHTSA by VIN, cache in vin_recalls for 24h

SECURITY
- Validate all inputs with zod
- Use CSRF protection for cookie sessions
- Rate limit auth and VIN endpoints via Redis
- Enforce ownership checks on all user resources

DEPLOYMENT
- Provide Dockerfiles for web and api
- Provide docker-compose for local
- Provide environment variable templates (.env.example)
- Document deploy steps:
  - Web to Vercel
  - API to Fly.io/Render
  - Postgres to Neon/Supabase
  - Redis to Upstash

ACCEPTANCE CRITERIA
- A user can complete onboarding quiz, receive recommendations, save to shortlist, compare vehicles, view TCO, generate OTD calculation, add an owned vehicle, see recall results for VIN, and receive a scheduled reminder email.
- All endpoints documented in Swagger and covered by basic integration tests.