ReviewRank

Find the places locals trust most — ranked by real customer reviews, not paid placements.

Built with Next.js 16 · Tailwind CSS 4 · Deployed on Vercel · Native mobile via Capacitor (iOS + Android).

Smart Score = rating × log₁₀(review_count + 1)

---

Architecture

ReviewRank uses Capacitor's server.url mode: the native apps load the deployed Vercel URL inside a native WebView. The Google Places API key stays protected on the server. App updates go live the moment you deploy to Vercel — no new App Store release required for content changes.

[iOS App / Android App]
        │
   Capacitor WebView
        │
   https://your-app.vercel.app   ← Next.js on Vercel
        │
   /api/places ──────── Google Places API  (key server-side only)
   /api/lead-request ── Supabase

---

Prerequisites

Tool	Version	Notes
Node.js	24.x	Use .nvmrc; npm 11.6.2+ (11.x)
Xcode	15+	macOS only, required for iOS
Android Studio	Hedgehog+	Required for Android
Vercel account	—	Free tier works
Apple Developer Program	$99/year	Required for App Store
Google Play Console	$25 one-time	Required for Play Store

---

Local development

nvm install
nvm use
npm ci
# Create .env.local with development/staging credentials only if you need live integrations.
npm run dev

Open http://localhost:3000.

---

Dependency and security verification

The committed lockfile uses Next.js 16.4.1 (including patched PostCSS 8.5.23), Tailwind / its PostCSS plugin 4.3.3, root PostCSS 8.5.30, Vitest 5.0.5, and coordinated Capacitor 8.5.3 packages. React 18 is retained within Next's published peer range. Explicit Webpack flags preserve the established bundler rather than also adopting Next 16's default Turbopack migration. The admin request gate uses Next 16's proxy.ts convention; server-page authorization remains in place. Tests use Vitest's Oxc JSX transform; no Tinypool dependency remains.

npm ci
npm run typecheck
npm test
npm run verify:native-toolchain
npm run verify:build
npm run verify:smoke

verify:build performs a production-mode compilation with application/provider credentials blanked before dotenv loading, Next telemetry disabled, and Node fetch/http/https restricted to loopback and Google Fonts. Its self-test verifies the restrictions without contacting a provider. This is not an operating-system network sandbox: direct sockets and native clients are outside the interception. It allows font downloads but is not intended to exercise live integrations. Verification uses one build/render worker; normal deployments retain Next's defaults. Do not deploy its credential-free output; normal deployments use npm run build with the separately approved environment.

On 2026-10-15, npm audit --package-lock-only changed from 36 flagged dependency entries (6 critical, 14 high, 16 moderate) to 12 (0 critical, 6 high, 6 moderate). This follow-up removes the vulnerable Tailwind globbing chain and upgrades Next's bundled PostCSS through supported parent releases, not forced transitive overrides. That follow-up left 3 moderate entries, 0 high and 0 critical in Capacitor CLI's Xcode/UUID chain. Counts include inherited/metavulnerability entries, not distinct exploits.

The native-toolchain follow-up retains coordinated Capacitor 8.5.3 and Xcode 3.0.1, whose latest published releases still request UUID 7. A narrowly scoped [email protected] override selects UUID 11.1.1, the latest CommonJS-capable 11.x release and the patched threshold for GHSA-w5hq-g745-h8pq. It intentionally exceeds Xcode's declared UUID range: compatibility must be checked, not assumed. Xcode uses synchronous require('uuid').v4(); a blind upgrade to the latest ESM-only UUID release is not the chosen compatibility strategy. Remove/revisit the override when Xcode declares a supported patched dependency or either parent changes. No other UUID consumers are overridden.

verify:native-toolchain checks actual CLI-to-Xcode-to-UUID resolution, UUID buffer bounds and ID generation, the real Capacitor Swift-file registration helper against a temporary copy of the tracked Xcode project, idempotency and CLI startup. It does not write the original project, run native sync, compile, sign or distribute an app. Provider credentials are stripped and the same Node network guard is installed. This is API/project-file compatibility coverage, not macOS/Xcode or device QA.

The 2026-10-15 locked audit reports zero findings at every severity after this fix; the three moderate inherited entries are removed. CI audits all severities (--audit-level=info) without suppressing findings. Always rerun the current audit; a zero report is not proof that every dependency is vulnerability-free. Issue #15 remains open for overall release verification. next lint was removed in Next 16; no lint command is advertised until an ESLint configuration is supplied.

After the guarded build, verify:smoke starts only a loopback server with the same credential-stripping network guard. It verifies homepage SSR/security headers, fail-closed admin proxy behavior, short-input autocomplete (which returns before database/provider access), API no-store headers, and immutable static-asset caching. It does not exercise paid/live-provider workflows.

Browser and mobile compatibility release gate

Tailwind 4 raises the styling baseline to Safari 16.4+, Chrome 111+ and Firefox 128+. Confirm that this is acceptable for the supported audience before merging/deploying; older iOS WebViews can otherwise lose styling. Native device QA remains required. Compatibility CSS preserves legacy brand/named colors, shadows, focus outlines, responsive utilities and safe-area precedence. Automated CSS checks are not a substitute for real-device search/detail/forms/travel and Stripe test-mode verification. Cache keys, retention policy, provider-fetch code and lead-matching logic are unchanged.

Admin pages also revalidate Basic Auth on the server before fetching private records, rather than relying exclusively on middleware matching.

Updating Capacitor packages does not patch installed mobile apps. An approved native sync, signed rebuild, device testing, and redistribution are still needed; no mobile release is performed by these verification commands.

---

Environment variables

Variable	Required	Description
GOOGLE_PLACES_API_KEY	Yes	Google Cloud Places API key
NEXT_PUBLIC_SUPABASE_URL	No	Supabase project URL
SUPABASE_SERVICE_ROLE_KEY	No	Supabase service role key
ADMIN_SECRET	No	Secret for /admin/* pages
CAPACITOR_SERVER_URL	Mobile	Vercel URL loaded by the native app

---

Deploy to Vercel

The Capacitor mobile app loads your Vercel URL — deploy the web app first.

npm install -g vercel
vercel login
vercel --prod

Note the URL (e.g. https://reviewrank-abc123.vercel.app).

Set all environment variables in the Vercel dashboard under Project → Settings → Environment Variables.

---

Mobile setup

1. Set the Capacitor server URL

Edit capacitor.config.ts and replace your-app.vercel.app with your real Vercel URL.

2. Add native platforms (run once on your dev machine)

npx cap add ios
npx cap add android

3. Sync after any config change

npm run cap:sync

---

iOS — App Store build

Requirements

• macOS with Xcode 15+
• Apple Developer Program membership

Steps

npm run cap:ios       # opens Xcode

In Xcode:

1. Team & signing — select your Apple Developer team in Signing & Capabilities

2. Bundle ID — must match appId in capacitor.config.ts (com.reviewrank.app)

3. Location permissions — verify these keys exist in ios/App/App/Info.plist (the Geolocation plugin adds them, but check the description strings):

   <key>NSLocationWhenInUseUsageDescription</key>
   <string>ReviewRank uses your location to find trusted businesses near you.</string>
   

4. App icons — see public/assets/icons/README.md to generate all required sizes

5. Archive — Product → Archive → Distribute App → App Store Connect

TestFlight (recommended before release)

Upload via Xcode Organizer → Distribute → App Store Connect. Then invite testers from App Store Connect → TestFlight.

---

Android — Google Play build

Requirements

• Android Studio (Hedgehog or later)
• Java 17+
• Google Play Console account

Steps

npm run cap:android   # opens Android Studio

In Android Studio:

1. App ID — matches appId in capacitor.config.ts (com.reviewrank.app)

2. Location permissions — verify these exist in android/app/src/main/AndroidManifest.xml:

   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.INTERNET" />
   

3. App icons — see public/assets/icons/README.md to generate adaptive icons

4. Signing — Build → Generate Signed Bundle/APK → Android App Bundle (.aab)

   • Create a new keystore (back it up — you need it for every future update)

5. Upload — Google Play Console → Create app → Production → Upload AAB

---

Updating the app after release

Change type	Steps
UI / content / ranking logic	Push to main → Vercel auto-deploys → users see it immediately
New Capacitor plugin	npm install @capacitor/plugin → npx cap sync → rebuild in Xcode/Android Studio → submit new binary
App name, icon, permissions	Update config → npx cap sync → rebuild and submit new binary

---

App icons and splash screens

See public/assets/icons/README.md for source file requirements and generation steps.

Quick reference:

npm install -D @capacitor/assets
npx capacitor-assets generate --assetPath public/assets/icons

---

Project structure

review-rank/
├── app/
│   ├── api/                    Server-side API routes (Places, leads, reports)
│   ├── business/[id]/          Business detail page
│   ├── results/                Search results page
│   ├── admin/                  Admin panels (leads, report requests)
│   └── page.tsx                Homepage
├── components/                 Shared UI components
│   ├── NavLogo.tsx             Logo mark — single source of truth
│   ├── BusinessCard.tsx        Search result card with quote CTA
│   ├── QuoteButton.tsx         Lead capture modal
│   └── SearchForm.tsx          Search form with Capacitor Geolocation
├── lib/
│   ├── places.ts               Google Places API client
│   ├── ranking.ts              Smart Score + trust tier logic
│   └── types.ts                TypeScript types
├── public/
│   ├── assets/icons/           Source images for app icons and splash screens
│   └── favicon.svg             Browser favicon (copper pin mark)
├── supabase/migrations/        Database schema
├── capacitor.config.ts         Capacitor configuration
├── next.config.ts              Next.js config (CSP, image domains)
└── .env.production             Environment variable template

---

Scripts

Command	Description
npm run dev	Start development server
npm run build	Production build
npm run start	Start production server
npm run cap:sync	Sync Capacitor config and plugins
npm run cap:ios	Open iOS project in Xcode
npm run cap:android	Open Android project in Android Studio
npm run cap:copy	Copy web assets to native projects

---

Google Places API setup

1. Go to Google Cloud Console → Credentials
2. Create credentials → API key
3. Enable Places API (New) under APIs & Services → Library
4. Restrict the key to your Vercel domain under key settings
5. Set GOOGLE_PLACES_API_KEY in Vercel environment variables

---

Supabase setup (optional)

Used for lead requests (/api/lead-request) and report submissions (/api/report-request).

1. Create a project at supabase.com
2. Run migrations in the SQL editor:
   • supabase/migrations/0002_business_report_requests.sql
   • supabase/migrations/0003_leads.sql
3. Set NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in Vercel