HISTORICAL DOCUMENT -- This specification was written during initial project planning and references Supabase Auth, which has since been replaced by Clerk (see ADR-001). For the current system architecture, see Architecture.

Reggie V1 Specification¶

1. Vision & Positioning¶

A WHOIS for UK number plates — but opt-in. Owners verify ownership, making themselves discoverable. Anyone can look up a registration, see what it's worth, and make an offer.

The Problem¶

If you own a private plate, you have no idea what it's worth without talking to a dealer who wants 20% commission. If you want a specific plate, you have no way to find the owner. The existing marketplace model (Regtransfers, National Numbers) only captures active sellers — ignoring the vast majority who aren't selling but might consider the right offer.

How It Works¶

Search K3NDW
    → See it exists (DVLA verified) + estimated value (ML valuation)
    → See it's claimed by @kendrew (verified via V5C)
    → Make an offer (£5,000)
    → Owner gets notified, can accept or decline
    → If accepted: payment via Stripe, transfer guided by Reggie

    OR

    → See it's UNCLAIMED
    → If you own it: claim it, become discoverable, receive offers
    → If you don't: add to watchlist, get notified if it's ever claimed

Competitive Positioning¶

	Regtransfers	Reggie
Model	Marketplace (seller lists)	Registry (owner claims, buyer discovers)
Who's there	Active sellers only	Everyone who's claimed
Price discovery	Seller sets price (often inflated)	ML valuation provides independent estimate
Revenue	~20% dealer markup	5% buyer protection fee

Core Value Loop¶

Free valuations → Organic traffic ("what's my plate worth?")
    → Owners claim plates → Registry grows
        → Buyers find owners → Offers made
            → Word spreads → More owners claim → ...

2. Business Model¶

Revenue¶

Buyer protection fee: 5% on completed transactions. Seller receives the full agreed amount. Buyer pays plate price + 5%.

Examples: - £500 plate → Buyer pays £525 → Seller gets £500 → Reggie keeps £25 - £5,000 plate → Buyer pays £5,250 → Seller gets £5,000 → Reggie keeps £250

Zero seller fees (Vinted model). Revenue scales with transaction volume. Stripe takes ~1.5% + 20p from Reggie's fee — margins favour higher-value plates.

Future revenue (v2+): Premium seller features, dealer tools, API access.

Transaction Flow¶

1. Buyer makes offer → payment method on file (required before offering)
2. Seller accepts → funds captured immediately to Stripe Connect
   → If seller hasn't completed Stripe KYC: prompted now (money waiting = motivation)
   → KYC timeout: 14 days → auto-refund buyer
   → Seller sent step-by-step DVLA transfer guidance
3. Transfer verification:
   → Buyer confirms receipt of plate/certificate
   → Dispute at any point → funds frozen, manual review (email)
4. Completion → funds released to seller, ownership transfers on Reggie

Fraud safeguards: - Funds held by Stripe Connect (Reggie never holds money directly) - V5C verification at claim time proves seller ownership - Buyer must have verified email + payment method on file before making offers - Buyer confirmation for transfer completion - Dispute resolution handled manually via email at v1 scale - Dispute history tracked per user

Identity handling: Legal names collected at signup. The concierge agent handles the V317 DVLA form — Reggie collects the necessary details from both parties and provides each side only what they need. Buyer and seller never communicate directly.

Privacy Model¶

Public: username, plate ownership, sale history (prices + dates)
Hidden: real name, email, phone, address
All communication routed through Reggie (including DVLA transfer details)
No "hide from offers" toggle — claiming means you're discoverable
Buyer friction to prevent offer spam: verified email + payment method on file, 24-hour cooldown between offers on the same plate

3. User Journeys¶

Personas (Priority Order)¶

Curious Browser — "What's my plate worth?" Drives traffic via SEO. Volume play.
Passive Owner — Claims plate because it's free and there's upside. Builds the registry.
Active Seller — Zero fees attract sellers from Regtransfers/Facebook. Revenue driver.
Plate Hunter — "I want THIS specific plate." Validates the WHOIS thesis.

Journey: Search & Discover¶

Homepage is a search bar. Direct search only — no browsing, categories, or discovery feeds.

User types registration → normalised (uppercase, no spaces/dashes)
    → Check DVLA VES API (or local cache if <30 days)
        → DVLA confirms: create/update plate record, run valuation
        → DVLA 404: check plate format validity
            → Valid UK format: "This plate may be on retention or not currently assigned.
               If you own it, you can claim it with a V750 certificate."
               Add to watchlist option (logged-in) or signup prompt (anonymous).
            → Invalid format: "This doesn't look like a valid UK registration."
    → Return plate with valuation

URL format: /plate/{REG} (e.g. /plate/K3NDW). Case-insensitive — /plate/k3ndw resolves to K3NDW.

Valuation access:

Visitor	What They See
Anonymous	Value range (£4,000-£6,000), plate type, ownership status. CTA: "Sign up free for full breakdown"
Logged in	Full breakdown in their account: confidence score, contributing factors, comparables

Public plate page shows the range for everyone (this is what Google indexes). Full breakdown lives in the user's account, not on the public page.

Valuation is labelled as beta. Honest about ~50% MAPE accuracy.

Valuation feedback: - All users: thumbs up/down (directional accuracy signal) - Plate owners only: optional "What do you think it's worth? £___" (owners have real market knowledge; non-owner price submissions create bias) - Feedback tagged as user-reported, weighted lower than auction data for retraining

Completed Reggie sales feed back into the ML model as the highest-quality pricing signal. Plate pages show last sale price and date when available.

The plate page — most important page. Ranks in Google, shared on WhatsApp, converts browsers to claimers. The valuation number itself is the shareable moment ("my plate's worth £12k!").

/plate/K3NDW
┌─────────────────────────────────────┐
│  K3 NDW                            │  ← plate rendered visually
│  Dateless · 4 characters           │
│                                    │
│  Estimated value: £8,000-£12,000   │  ← range for all visitors
│  Confidence: 72% · Beta           │
│                                    │
│  Claimed by @kendrew ✓             │  ← or "Unclaimed — Claim it free"
│  12 people watching this plate     │  ← shown to owner only
│  [Make an Offer]                   │
│                                    │
│  Activity                          │
│  Mar 2026 · Sold for £10,000      │  ← full provenance history
│  Jan 2026 · Claimed by @kendrew   │
│                                    │
│  Does this valuation seem right?   │
│  [👍 Yes]  [👎 No]                  │
└─────────────────────────────────────┘

Already-claimed plate: If a user tries to claim a plate that's already claimed, they see: "Claimed by @owner. [Make an Offer] or [I own this plate — dispute claim]". Dispute flow requires uploading their own V5C for admin review.

No vehicle data displayed on plate pages in v1. DVLA VES is used for search verification and claim cross-checking only.

Journey: Claim & Verify¶

Owner uploads V5C → Reggie verifies → plate becomes "claimed" (publicly linked to username).

User sees "Unclaimed" → "Own this plate? Claim it for free."
    → Must be logged in
    → Upload V5C or V750 photo (camera/file, JPG/PNG/PDF, max 10MB, direct to R2)
    → Optional: "What did you pay?" + "When?"
    → Status: PENDING → admin reviews → APPROVED or REJECTED

V5C and V750 both accepted. Same upload flow regardless of document type. No public distinction between plates on vehicles vs on retention.

Smart claim verification (AI-assisted human review): OCR extracts registration and keeper name from V5C. AI annotates findings and highlights matches/mismatches. Human admin always makes the final call. No auto-approve, no auto-reject in v1.

Claim rejection: Admin selects from predefined reasons ('Document unclear', 'Name doesn't match', 'Wrong document type') and can add freetext notes. User sees both the reason and notes, with a link to resubmit. No limit on resubmissions.

Ownership disputes: Any user can challenge a claim by uploading their own V5C. Admin reviews both documents and decides. Complex cases handled via email support.

Off-platform sales: If a plate is sold outside Reggie, the new owner can dispute the existing claim by uploading their V5C. Standard dispute flow — admin reviews and transfers the claim.

Journey: Offer & Buy¶

Buyer sees claimed plate → "Make an Offer"
    → Must have verified email + payment method on file
    → Offer form shows valuation range as subtle context (grey text, not anchoring)
    → Enters amount → sees "Total with buyer protection: £X + 5%"
    → Owner notified via email + in-app
    → Owner can: accept or decline (no counter-offers)
    → Accepted → payment captured to Stripe Connect → transfer guidance begins

Offer rules: - Fixed 30-day expiry on all offers. After expiry, offer disappears. Buyer can make a new one. - Multiple buyers can have active offers on the same plate simultaneously - Seller sees all active offers and can pick the best one. Accepting one auto-withdraws all others. - 24-hour cooldown between offers on the same plate (prevents spam) - No hard limit on total active offers across plates - Offer form does NOT anchor to the valuation — shows range as subtle context only - No counter-offers. Seller accepts or declines. Buyer can submit a new offer at a different price after decline or expiry.

Journey: Transfer & Complete¶

After offer accepted and payment captured, the concierge agent takes over. Hybrid model: automated emails for the happy path, founder steps in manually for anything off-script.

Offer accepted → Stripe captures payment to Connect
    → If seller needs Stripe KYC → prompted with hosted onboarding (14-day timeout)
    → Agent determines transfer type and sends seller personalised DVLA instructions
    → Concierge handles V317 form details (names collected at signup)
    → Automated nudge emails: day 3, 7, 14
    → Buyer confirms receipt → funds released to seller
    → Plate ownership auto-transfers to buyer's Reggie account
    → Sale recorded in plate's public activity history
    → Dispute at any point → funds frozen, manual review via email

Seller no-show: Nudge sequence at day 3, 7, 14. No auto-refund — handle stalled transactions manually until real DVLA transfer timelines are understood from experience. Approach will evolve based on where bottlenecks actually appear.

No VES polling for transfer verification. Verification relies on buyer confirmation.

The concierge agent is a deterministic state machine with LLM-generated communications. Not an LLM in a loop. Every state transition logged, every communication stored, admin can override any decision.

DVLA transfer fees: The £80 DVLA retention/transfer fee is paid by the parties directly to DVLA, not through Reggie. Exact fee structure and who pays what needs further research — flagged as open question.

Account & Profile¶

Auth: Supabase Auth with email/password.

Signup: Email + password + legal name → email confirmation → choose username (unique, alphanumeric, 3-20 chars). Legal name required upfront (needed for V317 DVLA forms during transfers).

Reserved usernames: Pre-block known dealer names at launch (Regtransfers, NationalNumbers, etc). Manual override for trademark disputes.

Public profile at /user/{username}: Username, member since, claimed plates with valuations, sale history (plates previously owned with sale dates and prices). No avatar, no bio. Profiles are intentionally public — if someone has 50 claimed plates, that's a valid use of the platform.

Private dashboard:

My Plates (claimed)
    → K3NDW - £8,000-£12,000 - Claimed ✓
    → AB12CDE - Claim pending...

Previously Owned
    → M3 XYZ - Sold for £5,000 (Mar 2026)

Watching
    → X1 - On retention (interest registered)

My Offers (sent and received)

Quick Actions: Search / Claim

Watchlist: Claimed plates (public on profile) + watched plates (private). Owner sees watcher count ("12 people are watching your plate") — social proof and motivation.

Watcher notifications when a plate is claimed: To be designed carefully. High-intent moment (someone watching a plate gets notified it's now claimable) but risk of instant offer spam on new claimers. Flagged as open question — needs thoughtful UX to balance conversion with new-owner experience.

Notifications¶

Channels: Email (Resend) + in-app (bell icon with unread count). Transactional only in v1 — no marketing or re-engagement emails.

Trigger	Notification
Account created	Welcome email
Claim submitted	Confirmation email
Claim approved	Celebration email
Claim rejected	Reason + resubmit link
Watched plate claimed	"K3NDW has been claimed"
Offer received	Amount + link to respond
Offer expiring (day 28)	Reminder to buyer that offer expires in 2 days
Offer accepted	Next steps + transfer guidance
Transfer nudges	Day 3, 7, 14 reminders to seller

Design Principles¶

Mobile-first. Search is thumb-friendly. Claim uses camera capture. Dashboard is vertical scroll, touch targets, no hover-dependent interactions. Plate pages shareable via native share sheet. Desktop supported but secondary.

Plate Card System¶

Every plate is rendered as a visual card — the core visual unit across the product. The card's visual treatment scales automatically with the plate's valuation. A £250 generic plate looks understated. A £150k trophy plate looks premium. The visual intensity communicates value without needing to read the number. No labels or tier names are shown — the design speaks for itself.

Tiers (derived from estimated_value, no new data models):

Value Range	Feel
< £500	Clean, minimal
£500 – £2k	Slightly elevated
£2k – £20k	Noticeably premium
£20k – £100k	High-end, distinctive
£100k+	Unmistakable presence

Effects respect prefers-reduced-motion. The PlateCard component is reusable across the product: plate pages, search results, profiles, dashboards, social share images.

Accessibility¶

WCAG 2.1 AA compliance required. Key requirements: - Keyboard navigation for all interactive elements - Screen reader support for plate visuals (text alternatives for rendered plate images) - Colour contrast meeting AA ratios (4.5:1 for text, 3:1 for UI components) - Visible focus states on all interactive elements - Touch targets minimum 44x44px on mobile

Dealer / Trade Users¶

Dealers are regular users in v1. No special account type. Same 5% buyer fee. Dealer features (bulk listing, inventory, analytics) deferred to v2. Known dealer usernames reserved at launch.

4. Data Architecture¶

Core Models¶

Model	Purpose	Key Fields
`Plate`	Registration, type, ownership, cached valuation	`registration`, `plate_type`, `owner_id`, `cached_valuation`
`Claim`	Ownership claim with document upload	`plate_id`, `user_id`, `document_url`, `status`, `reviewed_by`, `ocr_data` (JSONB)
`VerificationEvent`	Full audit trail for all admin actions	`claim_id`, `event_type`, `actor_id`, `reason` (predefined), `notes` (freetext), `timestamp`
`Valuation`	Cached valuation results	`plate_id`, `estimated_value`, `confidence`, `factors` (JSONB), `comparables` (JSONB)
`Profile`	User account	`user_id`, `username`, `legal_name`, `created_at`
`Watchlist`	User's plate portfolio	`user_id`, `plate_id`, `relationship` (claimed/watched), `nickname`, `purchase_price`
`ValuationFeedback`	User feedback on valuations	`plate_id`, `user_id`, `is_accurate`, `suggested_price` (owner-only)
`Notification`	In-app + email notification log	`user_id`, `type`, `channel`, `read`, `sent_at`, `data` (JSONB)
`Offer`	Offer on a plate	`plate_id`, `buyer_id`, `seller_id`, `amount`, `status`, `expires_at`
`Transaction`	Sale being processed	`offer_id`, `buyer_id`, `seller_id`, `amount`, `fee_amount`, `stripe_payment_id`, `transfer_status`
`TransferGuidance`	Agent-led transfer steps	`transaction_id`, `transfer_type`, `current_step`, `steps_completed` (JSONB)
`PlateActivity`	Public provenance/history log	`plate_id`, `event_type` (claimed/sold/transferred), `actor_id`, `price`, `timestamp`

Removed from earlier drafts: Listing model (no active listings in v1 — claimed = discoverable, only path is receiving offers). parent_offer_id on Offer (no counter-offers).

Offer State Machine¶

PENDING → ACCEPTED → (creates Transaction, auto-withdraws other offers on same plate)
PENDING → DECLINED
PENDING → WITHDRAWN (by buyer)
PENDING → EXPIRED (30 days)

Transaction State Machine¶

PAYMENT_PENDING → PAYMENT_CAPTURED → KYC_PENDING (if seller needs Stripe onboarding)
KYC_PENDING → KYC_TIMEOUT (14 days) → REFUNDED
KYC_PENDING → KYC_COMPLETE → TRANSFER_IN_PROGRESS
PAYMENT_CAPTURED → TRANSFER_IN_PROGRESS (if seller already KYC'd)
TRANSFER_IN_PROGRESS → BUYER_CONFIRMED → COMPLETED
PAYMENT_PENDING → PAYMENT_FAILED → CANCELLED
Any state → DISPUTED → RESOLVED_BUYER / RESOLVED_SELLER (manual)

Caching Strategy¶

Valuations: Cached per plate, refresh if >24h stale
DVLA data: Re-checked on search if >30 days stale
Plate pages: SSR-cached by Next.js/Vercel
No monthly background VES re-checks

5. Technical Architecture¶

Stack¶

Component	Technology
Frontend (web)	Next.js 15, Vercel
Frontend (admin)	Next.js 15, Vercel (separate deployment, mobile-capable)
Backend API	FastAPI, Railway
Database	Supabase PostgreSQL
Auth	Supabase Auth (JWT, admin roles, MFA on admin)
File storage	Cloudflare R2 (EU jurisdiction)
Cache	Upstash Redis (rate limiting, DVLA cache)
Email	Resend (transactional only)
Payments	Stripe Connect (pending FCA legal review)
ML	LightGBM + rules engine
Analytics	Vercel Analytics + key server-side events
DNS	Cloudflare

Auth Model¶

Supabase JWTs → FastAPI validates → DB uses service_role (no RLS). Admin portal: separate domain, MFA required.

Admin¶

Separate deployment at admin.getreggie.co.uk. Responsive layout — works on mobile for quick reviews, desktop for complex cases. Primary admin is the founders.

Claim review: Queue sorted oldest-first. Each claim shows: user info, registration, uploaded document (inline), DVLA cross-check data, AI-extracted OCR annotations, current valuation, previous claims. Actions: Approve, Reject (predefined reason dropdown + freetext notes).

Transaction management: View active transactions, transfer status, dispute queue. Ability to force-refund or release funds via Stripe dashboard.

Audit trail: Every admin action logged immutably via VerificationEvent: who, what, when, why (predefined reason + freetext). Required for dispute resolution and accountability.

Security¶

HTTPS everywhere, R2 signed URLs (15-min expiry), Doppler for secrets
Rate limiting on public endpoints (Redis-backed)
Pydantic input validation, no RLS (backend enforces permissions)
Buyer verification required before offers: verified email + payment method on file

Monitoring & Analytics¶

V1: Railway metrics, Supabase dashboard, structured logging (structlog), /api/v1/health uptime check. Vercel Analytics for frontend. Key server-side events tracked: search, signup, claim, offer, transaction completion (enough to see the conversion funnel).

V1.1: Sentry error tracking, correlation IDs, valuation feedback dashboard.

6. SEO & Growth¶

SEO Strategy¶

Every searched plate gets an SSR page at /plate/{REG}. Seed 17,813 plates from DVLA auction data for immediate Google coverage. Seed plates behave identically to any unclaimed plate — same CTA, same layout.

Target queries: "how much is my number plate worth", "UK plate valuation", "{plate} value", "sell my number plate"

Implementation: Dynamic meta tags per plate, XML sitemap, Schema.org structured data, Google Search Console submission.

Growth Loops¶

Organic search → valuation → claim (primary)
Social sharing — valuations are inherently shareable ("my plate's worth £12k!")
Offer virality — "someone offered me £5k on Reggie!" drives more claims

Launch Strategy¶

First 50+ claims are founder-seeded: personal outreach, friends, 1:1 contact with plate owners. Organic funnel conversion comes after. Launch channels: Facebook plate groups, PistonHeads, Reddit, Product Hunt.

Success metric: 100+ verified claims (aspirational — even 20-30 genuine claims validates the thesis).

What's NOT V1¶

Native mobile app
Dealer/trade accounts or features
Social features (messaging, forums, following)
Promoted listings / advertising
Third-party API access
Full concierge (Reggie as intermediary grantee)
DVLA Recognised Reseller status
Advanced search / discovery / browsing / category pages
Price alerts
Vehicle data display on plate pages
Automated VES polling or monthly re-checks
Counter-offers or structured negotiation
Active listings with asking prices
Marketing or re-engagement emails
Curated editorial pages for famous plates (v2 — card system provides the foundation)
Famous plates directory / browsing page
Explicit rarity tier labels (visual treatment only, no gamification)

7. Open Questions¶

FCA / regulatory position — BLOCKER. Does Reggie need FCA registration for facilitating plate transactions? Legal advice required before launching payment features. How does Stripe Connect's marketplace model interact with UK FCA rules?
DVLA transfer fee structure — The £80 DVLA fee applies when taking a plate off a vehicle (goes to retention). Putting a retained plate onto a vehicle may be free. Who pays what in different transfer scenarios needs research. Does the buyer or seller cover the DVLA fee? Is it always £80 or does it vary?
Stripe Connect onboarding — Sellers KYC with Stripe after accepting an offer (money waiting = motivation). 14-day timeout before auto-refund. Confirm Stripe hosted onboarding flow works for UK sellers.
DVLA API rate limits — Plan for 5 req/sec initially. Investigate actual limits.
Valuation accuracy — ~50% MAPE. When is "good enough" to remove beta label?
Dispute rate — Unknown until real transactions happen. Vinted sees ~2-3%. Plate transfers are higher-value — does that increase or decrease fraud?
Watcher → offer conversion — When a watched plate gets claimed, watchers are notified. Should the notification prompt them to make an offer? High-intent moment but risks instant spam for new claimers. Needs careful UX design.
Seller no-show policy — Currently manual. Will evolve based on where bottlenecks actually appear in real transfers. May need auto-refund after X days once patterns are understood.

V1 Scope Boundaries¶

V1 is NOT a dealer inventory system, a social network, or a full concierge service. The goal: prove the registry model works — owners claim because discovery creates value, buyers find owners through Reggie that they couldn't find anywhere else.