How to Clone Truecaller

Create a Truecaller-style number-lookup directory called RingRadar using Next.js (App Router), Tailwind, Prisma + SQLite. SEO-rendered public pages + community spam reporting.

## What to build
A 'who called me' directory: search any phone number, view its public reputation page, and file categorized spam reports that drive a computed spam score. Mobile-first; pages must be server-rendered.

## Screens
- Home: hero search box accepting any number format, live 'recently reported' ticker, stats strip, how-it-works cards
- Number page at /number/[e164] (server component): formatted number, name (if corroborated), spam score gauge with color verdict (Safe/Suspicious/Spam), category breakdown bars, carrier/line-type row, chronological report timeline with comments, Report button, same-prefix related numbers, SEO title 'Who called from {number}? Spam score and reports'
- Report modal: category radio cards (scam/telemarketing/robocall/debt collector/safe), optional name suggestion and comment, login-gated
- Trending: ranked table of most-reported numbers this week with score chips and sparkline of daily reports
- Profile: my reports with corroboration status, reputation score and level, watched numbers
- Admin: dispute queue (claims from number owners) with approve/reject

## Prisma schema
NumberEntry (id, e164 unique, countryCode, nationalFormat, carrier, lineType, spamScore, reportCount, lookupCount, lastReportedAt), Report (id, numberId, userId, category enum, nameSuggestion, comment, weight, createdAt) with unique (numberId, userId) refreshed monthly, User (id, email, displayName, reputation, createdAt), Watch (userId, numberId), Dispute (id, numberId, claimantEmail, evidence, status)

## Core logic (must actually work)
- lib/phone.ts: normalize any input to E.164 with libphonenumber-js; all routes and queries key on E.164 only - reject unparseable input with a friendly error
- GET /number/[e164]: find-or-create the NumberEntry (increment lookupCount), render even with zero reports ('No reports yet - be the first')
- Spam score recomputed on every new report: sum of report weights (reporter reputation 1–3, halved if report older than 12 months, 'safe' counts negative), normalized to 0–100 and stored
- Reputation: +1 to all earlier reporters of category C on number N when a new report matches; recompute their report weights lazily
- Display name = mode of nameSuggestions with >= 3 agreements
- Rate limits: 1 report per user per number per 30 days; anonymous visitors get 5 number pages per day (cookie counter) then a signup wall

## SEO requirements
- generateMetadata per number page with the score in the description; JSON-LD; /sitemap.xml listing all number pages; trending pages statically regenerated hourly

## Style
Security-brand aesthetic: #0E2A47 navy header/footer, white content, verdict colors #30A46C safe / #FFB224 suspicious / #E5484D spam, big tabular-numeral phone numbers, shield icons, Inter font, zero clutter - trust is the design goal.

Seed: 60 numbers across 4 country codes (20 heavily reported with realistic scam comments, 25 light, 15 clean with safe votes), 10 users with reputation spread 1–3, and lookup counts so trending and tickers render believably.

Build a production-quality Truecaller-style number-reputation directory. The scoring system must resist brigading, and the number pages must be flawless for SEO - they are the entire acquisition channel.

## Stack
- Next.js 14 App Router + TypeScript + Tailwind + shadcn/ui; ISR for number pages (revalidate 1h, on-demand revalidate after new reports)
- PostgreSQL via Prisma; NextAuth (email magic links); Upstash Redis for rate limiting; libphonenumber-js for parsing
- Twilio Lookup API behind a cached enrichment service (carrier, line type, validity - cache 90 days)

## Core design: E.164 is the primary key of the business
- lib/phone/normalize.ts: parse anything a user pastes into E.164 or a typed error; property-based tests with messy international inputs - a normalization bug silently forks the directory
- numbers table unique on e164; find-or-create on first lookup; never store unparsed input

## Scoring engine (server-authoritative, anti-brigading)
- lib/score/compute.ts, pure and unit-tested: score = clamp(0–100, Σ report.weight), where weight = baseSeverity(category) * reporterReputation(1–3) * ageDecay (halves at 12 months); 'safe' reports carry negative weight
- Anti-gaming: reports from accounts < 48h old get weight 0.25; max 3 counted reports per /24 IP subnet per number per week (store hashed IP); score recompute is a queued job, not inline
- Reputation: corroboration-driven - when report categories agree across distinct users, earlier reporters gain reputation; stored as an append-only reputation_events ledger, balance derived
- disputes: number owners verify via SMS code to the number itself (Twilio Verify), then contest labels; sustained disputes mark a number 'contested' on the page

## SEO architecture (the moat)
- /number/[e164] ISR pages: title 'Who called from {national format}? Spam reports & score', meta description with verdict + report count, JSON-LD, canonical URLs, breadcrumbs
- Segmented sitemaps (50k URLs each) at /sitemaps/numbers-[n].xml regenerated nightly; internal linking: same-prefix blocks, trending, 'recently reported' - every page reachable in 3 clicks
- Empty-state pages (zero reports) still render with lookup metadata but ship noindex until the first report - avoids thin-content penalties

## Schema
numbers (e164 unique, enrichment fields, spam_score, contested), reports (unique number_id+user_id per 30d window, category enum, weight snapshot), users, reputation_events, watches, disputes, lookups (number_id, day, count - for trending). Indexes: reports(number_id, created_at), lookups(day, count desc).

## Implementation order
1. Normalization lib with property tests + schema + seed (60 numbers, skewed report distributions, 10 reporters)
2. Number page (ISR) with score gauge, timeline, enrichment row - verify metadata output
3. Report flow with rate limits + queued score recompute + on-demand revalidation
4. Reputation ledger + corroboration job
5. Trending + sitemaps + internal linking
6. Dispute flow with Twilio Verify
7. Browser extension (Manifest V3): content script highlights phone numbers on any page, badge shows cached verdict from GET /api/v1/lookup, popup with mini number page

## Quality bar
- Number pages score 95+ on Lighthouse (these pages ARE the business); CLS-safe gauge rendering
- Score engine fully unit-tested including brigading scenarios (100 new accounts hammering one number must move the score < 5 points)
- API responses cached at the edge; rate limiting on every write

Start with step 1; show me normalize.ts and its property tests before anything else.

Design the complete UI for a phone-number lookup and spam-report directory called RingRadar (Truecaller-style web product). React + Tailwind + shadcn/ui + lucide-react. Aesthetic: consumer security brand - deep navy #0E2A47 header/footer, white content surfaces, verdict colors (#30A46C safe, #FFB224 suspicious, #E5484D spam), shield iconography, Inter with tabular numerals for phone numbers, calm and trustworthy, zero clutter.

## Screens

### 1. Home
- Navy hero: 'Who called you?' headline, subline 'Community-powered caller ID and spam reports', giant white search input with phone icon and Search button; trust row beneath ('2.1M numbers indexed · 48k reports this week')
- Live ticker card: horizontally scrolling recently-reported numbers with red/amber score chips
- Three how-it-works cards (Search, Read reports, Report back) with line icons

### 2. Number page (the money page)
- Breadcrumb (Home / +1 415 / this number); huge formatted number as the H1 with a copy button
- Verdict block: semicircular gauge showing 78/100 in red with label 'Likely Spam', 'Reported 23 times · last reported 2 days ago'
- Identity row: reported name ('Parcel Delivery Scam' with quote icon), carrier chip (T-Mobile), line type chip (VoIP, amber-flagged), country flag
- Category breakdown: horizontal bars (Scam 14, Telemarketing 6, Robocall 2, Safe 1) in category colors
- Red 'Report this number' button + secondary 'Watch' bell button
- Report timeline: cards with category icon, relative date, comment text, reporter level badge (Scout/Sentinel/Guardian), helpful upvote; 'Contested by owner' amber banner variant
- Sidebar: same-prefix related numbers list with mini score chips, 'Trending this week' list, subtle ad placeholder slot

### 3. Report modal
- Category radio cards with icons (Scam, Telemarketing, Robocall, Debt collector, Safe - green outline), 'Who was it?' optional input, comment textarea with 280-char counter, navy submit; logged-out state swaps submit for 'Sign in to report'

### 4. Trending
- Filter chips (Today / This week / By country); ranked table: rank, number (mono), name, score chip, top category badge, report count, 7-day sparkline; top 3 rows get flame icons

### 5. Profile
- Reputation card: level badge with shield art (Guardian), progress bar to next level, stats (reports filed, corroborated %)
- My reports table with status pills (Corroborated green / Pending gray); watched numbers list with score-change indicators (+12 red arrow)

### 6. Browser extension popup (design it as a 360x520 panel)
- Mini number page: number, gauge, top category, last report, 'View full report' button, 'Report' shortcut - same design language compressed

Fully responsive, mobile-first. Fill every screen with realistic data: international numbers in proper formats, believable scam comments ('Claimed my package was held at customs, asked for $2 fee'), report counts and dates - no lorem ipsum.

Build a phone-number reputation directory (Truecaller model, web version) called RingRadar - community spam reports with public lookup pages.

## Entities
- NumberEntry: e164 (unique), countryCode, nationalFormat, carrier, lineType, spamScore (0–100), reportCount, lookupCount, lastReportedAt, contested flag
- Report: number reference, reporter, category (scam/telemarketing/robocall/debt_collector/safe), nameSuggestion, comment, weight, createdAt
- Watch: user + number references (alerts when score changes)
- Dispute: number reference, claimantEmail, evidence text, status (open/accepted/rejected)
- UserStats: user, reputation (1–3 tiers: Scout/Sentinel/Guardian), reportsFiled, corroboratedCount

## Roles
- Visitor: searches numbers, views up to 5 number pages per day before a signup wall
- Member: files reports (one per number per 30 days), suggests names, watches numbers, earns reputation
- Admin: reviews disputes from number owners, can lock or reset abused number pages

## Pages
1. Home: large search box accepting any phone format, recently-reported ticker, stats strip, how-it-works cards
2. Number page (public, one per number): formatted number, spam score gauge with verdict colors (0–39 Safe green, 40–69 Suspicious amber, 70–100 Spam red), corroborated name, carrier and line type, category breakdown bars, report timeline with comments, Report and Watch buttons, related same-prefix numbers
3. Report modal: category cards, optional name suggestion, optional comment, login required
4. Trending: most-reported numbers this week, ranked with score chips and report counts
5. Profile: reputation level and progress, my reports with corroboration status, watched numbers
6. Admin dispute queue: owner claims with evidence, approve/reject actions

## Rules
- Every input is normalized to international E.164 format before lookup; unknown numbers get a page created on first search with a 'no reports yet' state
- Spam score = sum of report weights: weight = reporter reputation (1–3), halved for reports older than 12 months; 'safe' reports subtract; clamp to 0–100 and store on the number
- Corroboration: when a new report matches the category of earlier reports by other users, those earlier reporters gain +1 reputation progress
- Display name appears only when 3+ users suggested the same name
- One report per member per number per 30 days; new accounts' reports count at quarter weight for 48 hours (anti-brigading)
- Accepted disputes reset wrongful labels and mark the page 'verified by owner'

## Look & feel
Trustworthy security brand: deep navy #0E2A47 header and footer, white content, verdict palette #30A46C / #FFB224 / #E5484D, shield icons, large tabular numerals for phone numbers, Inter font, clean and calm - credibility is the product.

Seed: 60 numbers across 4 countries - 20 heavy-spam with 8–30 reports and realistic comments ('Fake customs fee scam'), 25 lightly reported, 15 clean with safe votes - plus 10 members across all three reputation tiers and 2 open disputes so every page state is demonstrable.