Real-Time Trust Engine for Local Economies
| Field | Value |
|---|---|
| Version | v2.2 — Deep Backend Audit Pass |
| Last Updated | June 11, 2026 |
| Stack | React 19 / TypeScript / Vite / Rust Axum / Supabase / Vercel |
Vantage is a trust-first local business discovery platform. It surfaces nearby businesses through verified activity, credibility-weighted reviews, recency, and community engagement. Ranking is earned, never bought.
Business claiming has zero effect on the Live Visibility Score (LVS). That is an
architectural invariant enforced in backend/src/services/visibility_score.rs.
Browser
-> Vercel static frontend
-> /api/* rewrite
-> api/index.rs Vercel Rust wrapper
-> backend/src/lib.rs Axum router
-> Supabase Auth Admin API + Supabase PostgREST
- Rust + Axum workspace package:
vantage-backend - Vercel serverless wrapper:
api/index.rs - App factory and route mounting:
backend/src/lib.rs - Central configuration:
backend/src/config.rs - Supabase client:
backend/src/db/supabase.rs - Route modules: auth, users, businesses, discovery, saved, reviews, claims, deals, subscriptions, activity, location
- Integrations: Supabase, Google Places/Geocoding, reCAPTCHA Enterprise, Stripe Checkout, in-memory rate limiting
- Serverless request bodies are capped at 2 MiB and collected responses are capped at 20 MiB in the Vercel Rust wrapper.
- React 19 + TypeScript + Vite 8
- React Router route tree in
frontend/src/main.tsx - Central API client in
frontend/src/api.ts - Auth state in
frontend/src/contexts/AuthContext.tsx - Saved business guest/auth sync in
frontend/src/hooks/useSavedBusinesses.ts
Supabase is the single source of truth for authentication, relational data, storage buckets, realtime activity, and user metadata.
Authoritative schema migration:
scripts/supabase/migrations/202605180001_supabase_single_source.sql
scripts/supabase/migrations/202605200001_postgis_geo_queries.sql
scripts/supabase/migrations/202605200002_review_summary_rpc.sql
scripts/supabase/migrations/202605200003_deal_status_consistency.sql
| Table | Purpose |
|---|---|
businesses |
Listings, owner linkage, Google place metadata, rating aggregates, profile media fields, generated PostGIS geography for indexed radius reads |
reviews |
One review per user/business with platform-owned rating aggregate updates |
saved_businesses |
User bookmarks |
claims |
Business ownership claim workflow |
deals |
Business promotions |
subscriptions |
Business-owner subscription records, including pending Stripe Checkout sessions |
checkins |
Self-reported and geo-verified visits |
activity_feed |
Community feed, likes, comments counters, realtime publication |
activity_comments |
Feed comments, realtime publication |
owner_events |
Business owner events, realtime publication |
The migration creates public Supabase Storage buckets:
business-mediauser-avatars
The migration adds these tables to supabase_realtime:
activity_feedactivity_commentsowner_events
The PostGIS migration adds:
search_businesses_geoactivity_pulse_geoowner_events_geo
The Rust API uses these RPCs for nearby/discovery/activity radius reads after the migration is applied, with compatibility fallbacks to the older Haversine path while deployments catch up.
refresh_business_review_summary updates a business rating and review count
inside Postgres after review writes. The Rust API uses it after the migration is
applied and falls back to the older API-side calculation while deployments catch
up.
refresh_business_has_deals keeps the denormalized businesses.has_deals flag
aligned with active, unexpired deals. A Supabase trigger runs it after deal
writes, and the Rust API calls it with an API-side fallback while deployments
catch up.
All endpoints are mounted under /api.
| Area | Endpoints |
|---|---|
| Auth | /auth/register, /auth/login, /auth/logout, /auth/me, /auth/google |
| Users | /users/me, /users/me/preferences, /users/me/password, /users/:id |
| Businesses | /businesses, /businesses/nearby, /businesses/:id, /businesses/:id/profile, /photos |
| Discovery | /discover, /decide, /explore/lanes |
| Saved | /saved, /saved/:business_id |
| Reviews | /reviews, /reviews/:id, /reviews/business/:id, /businesses/:id/reviews |
| Claims | /claims, /claims/my, /claims/:id |
| Deals | /deals, /deals/:id, /deals/business/:id, /businesses/:id/deals |
| Subscriptions | /subscriptions/tiers, /subscriptions/my, /subscriptions/business/:business_id, /subscriptions, /subscriptions/cancel, /subscriptions/webhook/stripe, /stripe/webhook |
| Activity | /feed, /activity, /checkins, /activity/pulse, /feed/:id/like, /feed/:id/comments, /feed/posts, /credibility/me, /events, /businesses/:id/activity |
| Location | /location/reverse |
Current Rust implementation computes a 0-100 score from:
- Rating confidence dampened by review count
- Review volume
- Verified status
- Description presence
- Photo presence
is_claimed and owner_id are intentionally excluded.
Known invariant violation (unfixed): visibility_score.rs lines 15–18 return
any stored visibility_score > 0 verbatim before computing organic signals. A
single non-zero value written to the DB permanently freezes that business's
ranking. The stored-override path must be removed or gated behind an explicit
admin override flag.
Known deceptive advertising (unfixed): SubscriptionTier::visibility_boost()
and featured_placement() return true for PRO/PREMIUM and are surfaced in the
/subscriptions/tiers response, but visibility_score::compute() never reads
them. Paid subscribers are promised ranking benefits that do not exist. Either
remove the flags from TierInfo, or honour them in the scoring function without
violating the LVS invariant (e.g. as a tie-breaker after organic score, never
boosting above organic score).
Business owners cannot create or update reviews for their own listings, because rating and review-count signals contribute to discovery trust and visibility.
Discovery supports category, text, verified-only, radius, distance, rating,
newest, most-reviewed, and canonical LVS sorting. Distance filtering is
application-side against the stored GeoJSON-style location field.
/decide accepts intent, radius, category, and modifier constraints. It returns
ranked business items plus explanation strings for the UI.
Email/password and Google OAuth are mediated by the Rust backend through
Supabase Auth. Login/register/Google flows return Supabase Auth sessions, and
the backend stores Supabase access and refresh tokens in httpOnly cookies. API
auth guards verify the Supabase access token with SUPABASE_JWT_SECRET and can
refresh expired access tokens with the Supabase refresh-token endpoint. Auth
response bodies return the user object only; bearer tokens are not exposed to
browser JavaScript.
Owners can claim a business, update profile fields, create events, post activity
updates, create deals, and manage subscriptions. Owner checks compare
businesses.owner_id against the authenticated Supabase user id and require the
authenticated user to have a business_owner or admin role for owner-only
flows. Claim submission and approval cannot take over a business that is already
claimed or owner-linked to another user. Frontend claim/search and business
modal actions use the same owner_id claimability rule, and owners are not
offered review entry points for their own listings because the API rejects
self-reviews.
Paid subscription creation starts a Stripe Checkout Session with server-side
price IDs and creates a pending_checkout row. Free subscriptions can be
activated immediately. Signed Stripe webhooks promote paid rows to active
after checkout payment confirmation and downgrade rows when Stripe reports a
subscription deletion. Subscription cancellation is scoped by business when a
user owns multiple listings, cancels Stripe before local downgrade, and keeps
Supabase Auth subscription metadata aligned to the highest remaining active
business subscription. Paid-plan replacement cancels the prior Stripe
subscription before activating the replacement row locally.
Activity feed, comments, check-ins, owner events, pulse cards, and business
activity status are served from Supabase tables. Pulse and event endpoints apply
location/radius filtering when coordinates are provided. Reverse geocoding
returns both backend-friendly fields (formatted_address, state) and
frontend contract fields (label, region). Check-ins accept either no
coordinates or a complete valid latitude/longitude pair; partial coordinate
payloads are rejected.
Required:
SUPABASE_URLSUPABASE_SERVICE_ROLE_KEYSUPABASE_JWT_SECRET
Recommended/feature-specific:
GOOGLE_API_KEYRECAPTCHA_ENTERPRISE_*STRIPE_SECRET_KEYSTRIPE_WEBHOOK_SECRETSTRIPE_PRICE_STARTER_MONTHLYSTRIPE_PRICE_STARTER_YEARLYSTRIPE_PRICE_PRO_MONTHLYSTRIPE_PRICE_PRO_YEARLYSTRIPE_PRICE_PREMIUM_MONTHLYSTRIPE_PRICE_PREMIUM_YEARLYFRONTEND_URLPRODUCTION_URL
Production FRONTEND_URL/PRODUCTION_URL values must resolve to public
origins; localhost fallback origins are rejected in production to protect
checkout redirects.
Frontend-specific:
VITE_API_URLVITE_GOOGLE_CLIENT_IDVITE_RECAPTCHA_SITE_KEY
MongoDB, Redis, frontend Supabase public env vars, and frontend Stripe publishable-key env vars are no longer part of the target runtime architecture.
Vercel configuration:
buildCommand:cd frontend && npm install && npm run buildoutputDirectory:frontend/dist/api/:path*rewrites to/api/index- SPA fallback rewrites to
/index.html - Static security headers are configured in
vercel.json, including HSTS, content-type, frame, referrer, permissions, and CSP headers. - Backend API responses also apply security headers and use
no-storecache control for private user/owner/billing endpoints.
Local development:
cargo run -p vantage-backend --bin vantage
cd frontend && npm run devCompleted in the current baseline:
- Rust backend compiles with MongoDB dependency removed.
- Supabase REST client handles select/insert/update/delete/count JSON flows.
- Core MongoDB-backed route modules were migrated to Supabase tables.
- Frontend API route mismatches were addressed with backend aliases.
- Unused frontend
purgeChainsAPI method was removed. - Supabase schema migration now covers data, storage, realtime, indexes, and RLS.
- Supabase RLS policies for claims and check-ins restrict direct authenticated access to safe read/insert paths instead of broad user-managed updates.
- Malformed UUID and coordinate inputs are rejected before database access.
- Credibility tiers, reverse-geocode responses, pulse/event filters, and auth cache behavior are aligned with frontend contracts.
- Supabase count queries use exact count headers instead of loading all rows.
- Local Vantage-owned JWT sessions were removed; auth cookies now carry Supabase Auth access/refresh tokens and backend guards verify Supabase JWTs.
- Claim detail access, claim submission, business subscription lookup, public profiles, reviews, and activity display names were tightened to reduce PII and billing-data exposure.
- Deal/event timestamp validation and SPA catch-all routing were added.
- Paid subscriptions now create Stripe Checkout Sessions and
pending_checkoutrows instead of activating paid access before payment confirmation; signed Stripe webhooks activate confirmed paid checkouts and cancel deleted Stripe subscriptions. Cancellation is business-scoped and auth subscription metadata is recomputed from remaining active business subscriptions. - Serverless body caps, static/backend security headers, private API no-store cache-control, and production checkout-origin validation were added.
- Google Places/photo/reverse-geocode requests use bounded HTTP clients and sanitized public errors for upstream failures.
- Auth JSON responses no longer expose Supabase bearer tokens to frontend JavaScript; sessions are held in httpOnly cookies.
- Auth mutations explicitly clear loading state, and stale in-flight
/auth/meresponses cannot leave the frontend stuck on route-loading screens. - Claim takeover protection now rejects claims against owner-linked businesses,
and owner dashboard/pricing/profile-edit UI follows backend
owner_idauthorization. - Claim/search and business modal actions follow owner-linked claimability and owner self-review restrictions.
- Owner self-review is blocked, check-in coordinates must be complete, and business/discovery/activity coordinate inputs must provide latitude and longitude as a complete valid pair. Review aggregate updates now use a Supabase RPC with fallback and propagate failures instead of silently leaving business rating state stale.
- Deal create/update/delete flows now refresh
businesses.has_dealsthrough a Supabase RPC with fallback, and Supabase has a trigger migration so the deal badge remains database-owned even for non-API writes. Activity feed inserts and comment-count updates now propagate persistence failures instead of silently losing related state. - Frontend diagnostics now use a dev-only logger, and reCAPTCHA Enterprise is loaded lazily only when configured, with bounded polling and load-failure messaging. Explore session-cache operations are best-effort so blocked browser storage does not break refresh flows. Explore business/event cards now use separate native buttons for open/save/view actions instead of nested clickable wrappers. Overlay scroll locking now goes through a shared stacked hook so the business modal and mobile drawer cannot restore body scrolling out of order.
- Unused Redis/governor/nonzero dependencies and unused public frontend Supabase/Stripe env variables were removed.
- Repository guidance files now reflect the Rust + Supabase architecture instead of the removed FastAPI/MongoDB stack.
- Owner-only workflows now require owner/admin role checks in addition to
matching
businesses.owner_id. - Verification run:
cargo check,cargo fmt --all,cargo test,cargo clippy --all-targets --all-features -- -D warnings,cd frontend && npm run lint,cd frontend && npm run build,npm audit --audit-level=high.
Known limitations and open bugs (June 2026 audit pass):
Broken by default (data correctness):
- All domain model structs (
Business,User,Review,Subscription,ActivityFeedItem,CheckIn,OwnerPost,BusinessClaim,Deal,SavedRecord) have#[serde(rename = "_id")]onid. Supabase columns are namedid, not_id. These structs fail to deserialize DB rows;idis alwaysNonewhen these types are used directly. Thenormalize_id_aliashelper inroutes/support.rspatches this only in JSON-blob paths. create_businesssetsowner_id: auth_user.idandis_claimed: falsesimultaneously.ensure_business_open_for_claim_submissionblocks claims whenowner_idis non-null. Owner-created listings can never be formally claimed.SubscriptionTier::max_deals()defines per-tier deal limits that are never enforced inroutes/deals.rs. Free-tier businesses can create unlimited deals.
Security (unfixed):
middleware/auth.rs:121–122: Session cookie overwrites an already-extracted Bearer token. A validAuthorization: Bearerheader is discarded if a stalesession=cookie is also present.middleware/rate_limit.rs:51:X-Forwarded-Foruses the leftmost (client-controlled) IP via.split(',').next(). Rate limiting is trivially bypassed by prepending a spoofed IP.middleware/security_headers.rs:25:is_localhostis derived from the client-suppliedHostheader. SendingHost: localhostbypasses all security headers in production.config.rs: Dev origins (http://localhost:5173,:3000,:5174) and all Vercel previewVERCEL_URLvalues are included in the CORS allowlist unconditionally, combined withallow_credentials(true).routes/auth.rs: Logout clears cookies but never calls Supabase token revocation. A stolen refresh token stays valid for up to 7 days.jwt.rs:nbf(not-before) claim is never verified. A token with a futurenbfis accepted immediately.
Race conditions (unfixed):
reviews.rs:create_reviewduplicate-check and insert are two separate DB calls (TOCTOU). Concurrent requests both see no duplicate and both insert.subscriptions.rs:415–521: Stripe webhook activation is a non-atomic 4-step sequence. Duplicate at-least-once webhook deliveries create two active subscriptions.saved.rs:77–102:save_businesschecks then inserts in two separate calls. Concurrent saves create duplicate saved records.claims.rs:168–215: Already-approved claims can be re-reviewed. Claim approval is a non-atomic read+write.
Performance / resource (unfixed):
saved.rs:43–57:list_savedcallsselect_one_jsonper saved business (N+1 round-trips). No pagination limit on the initialsaved_businessesquery.activity.rs:438–480:get_activity_pulsecallsfind_businessinside a loop — up to 90 sequential DB round-trips per request.activity.rs:651–673:list_owner_eventscallsfind_businessper event — up to 100 sequential round-trips.stripe.rs,google_places.rs,recaptcha.rs: Newreqwest::Clientper call. TLS connection pooling is completely defeated. All three services should use a shared client stored inAppState.
Behaviour bugs (unfixed):
discovery.rs:150+163:/decidealways returns exactly 5 results regardless of thelimitparameter. The over-fetch multiplier corrupts the truncation target.discovery.rs:118–139:/explore/lanesinheritsq/searchfrom the caller. A request with?q=keyworddistorts all 5 curated lanes with the user's search.location.rs:49: Any Google geocoding API error (rate limit, auth, network) returns 400 Bad Request, misleading clients into thinking their coordinates were invalid.models/deal.rs:DealUpdatehas no#[derive(Validate)]. Update requests can settitleto empty ordiscount_percentto999.0.models/business.rs:BusinessUpdatehas no#[derive(Validate)]. Name and address are unconstrained on update.BusinessCreate.addresshas no max length.
Migration / deployment (unchanged):
- Supabase migration has been authored but not applied to the live project.
- Full integration tests for auth guards, owner checks, saved businesses, reviews, check-ins, subscriptions, and activity flows are still needed.
- Stripe webhook delivery needs smoke-testing against the deployed endpoint.
- PostGIS RPCs need migration applied and smoke-tested.
- Frontend still polls rather than subscribing to Supabase Realtime channels.
npx vercel buildcannot be verified locally without linked Vercel project settings.
P0 — Must fix before production launch:
- Remove
#[serde(rename = "_id")]from all model structs and replace with#[serde(rename = "id")]or plainpub id, so Supabase rows deserialize correctly. - Fix
create_business: either setowner_idbut also setis_claimed: true, or clearowner_idand let the claims workflow handle ownership. Currently owner-created listings are in an unclaimable limbo state. - Remove the stored-override early-return from
visibility_score::compute(). If admin overrides are needed, model them as an explicit flag separate from the organic LVS. - Fix
X-Forwarded-ForIP extraction to use the rightmost trusted IP, not the leftmost client-controlled one. - Fix
is_localhostto use the server's configured origin list, not the client-suppliedHostheader. - Enforce
max_deals()increate_deal— read the business's active subscription tier and reject requests that exceed the tier limit.
P1 — Fix before exposing paid features:
- Remove or rename
visibility_boost/featured_placementfromTierInfountil they are actually wired into the scoring function. - Replace the 4-step non-atomic Stripe webhook activation with a single conditional upsert or idempotency key check.
- Add Stripe token revocation to the logout path.
- Add
nbfcheck tojwt.rs::parse_claims. - Fix
middleware/auth.rs:121–122cookie-overwrites-Bearer bug.
P2 — Stability and performance:
- Batch-fetch businesses in
list_savedinstead of N+1 round-trips. - Batch-fetch businesses in
get_activity_pulseandlist_owner_events. - Move
reqwest::Clientconstruction out of per-call functions and intoAppStatefor Stripe, Google Places, and reCAPTCHA. - Fix
/decidelimit truncation — preserve original limit through the over-fetch multiplier. - Add
#[derive(Validate)]and constraints toDealUpdateandBusinessUpdate. - Guard CORS dev origins behind an environment check.
P3 — Integration and deployment:
- Apply the Supabase migrations and verify table/storage/PostGIS RPC permissions with real anon/authenticated/service-role requests.
- Add backend integration tests for all protected route families.
- Add fraud-resistant moderation for review/check-in abuse and coordinated engagement.
- Add frontend realtime subscriptions for activity feed, comments, and events.
- Add deployment smoke tests for
/api/health,/api/discover,/api/stripe/webhook,/api/auth/me, and SPA fallback routes.