VanMeet — Technical Documentation

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                    Flutter App (Dart)                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│  │ Riverpod │ │ GoRouter │ │ Drift DB │ │ RevenueCat │ │
│  │  State   │ │   Nav    │ │ (SQLite) │ │    SDK     │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬──────┘ │
│       │            │            │              │         │
│  ┌────┴────────────┴────────────┴──────────────┴──────┐ │
│  │              Repository Layer                       │ │
│  └────┬───────────────┬──────────────┬────────────────┘ │
└───────┼───────────────┼──────────────┼──────────────────┘
        │               │              │
   ┌────▼────┐   ┌──────▼──────┐  ┌───▼────────┐
   │Supabase │   │   Mapbox    │  │  Firebase   │
   │ Backend │   │   Maps      │  │  (FCM/AI)   │
   └────┬────┘   └─────────────┘  └───┬────────┘
        │                              │
   ┌────▼──────────────────────────────▼──────┐
   │         Supabase Edge Functions           │
   │  ┌──────────────┐  ┌──────────────────┐  │
   │  │AWS Rekognition│  │ Gemini Vision AI │  │
   │  │(Face Liveness)│  │(Van Photo Check) │  │
   │  └──────────────┘  └──────────────────┘  │
   └──────────────────────────────────────────┘

Tech Stack

Layer	Technology	Purpose
Frontend	Flutter 3.35 / Dart 3.9	Cross-platform mobile UI
State Management	Riverpod + StateNotifier	Reactive state, dependency injection
Navigation	GoRouter	Declarative routing, deep links, shell routes
Backend	Supabase (PostgreSQL)	Auth, database, real-time, storage, RLS
Edge Functions	Deno (TypeScript)	Serverless compute for AI/verification
Maps	Mapbox GL	Route drawing, builder locations, camp scout
Payments	RevenueCat SDK	Subscription management, entitlements
Push Notifications	Firebase Cloud Messaging	Real-time alerts for connections, messages
AI	Google Gemini 2.0 Flash	Van photo analysis, content moderation
Verification	AWS Rekognition	Face liveness detection
Local DB	Drift (SQLite)	Offline caching
Geospatial	PostGIS	Route intersection computation

Project Structure

lib/
├── app/                    # App entry point, MaterialApp
├── core/
│   ├── auth/               # Auth state notifier (Riverpod)
│   ├── config/             # Environment config (.env)
│   ├── network/            # Supabase client provider
│   ├── router/             # GoRouter config, MainShell (7 tabs)
│   ├── services/           # Mapbox, FCM, geocoding services
│   └── widgets/            # Shared widgets (in-app notifications)
├── features/
│   ├── auth/               # Login, register, forgot password
│   ├── matching/           # Discover page (swipe + grid), profile cards, filters (Dating/Friends/Near Me/Routes Cross)
│   ├── connections/        # Connection requests, accepted connections
│   ├── chat/               # Real-time messaging (Supabase Realtime)
│   ├── marketplace/        # Builder profiles (3 types: Nomad/Mobile/Workshop), reviews, community forum, builder onboarding
│   ├── routes/             # Route intersector, wave system (mutual wave → auto-connection), convoy system
│   ├── toolkit/            # Camp Scout (campsites, water, fuel)
│   ├── verification/       # Photo + van verification, trust scores
│   ├── subscription/       # RevenueCat integration, paywall, feature gates
│   ├── profile/            # User profile, edit, location
│   ├── onboarding/         # Multi-step onboarding flow (6–7 steps)
│   ├── search/             # User search with filters
│   ├── settings/           # App settings, blocked users
│   └── ai/                 # Gemini AI repository
└── database/               # Drift local database schema

Database Schema (Supabase PostgreSQL)

Core Tables (27 tables, all with Row Level Security):

users — 45+ columns: profile, van details, dating preferences, location, verification status, trust score, subscription tier
connection_requests — sender/receiver with status (pending/accepted/declined)
connections — accepted mutual connections enabling chat
messages — real-time chat messages between connections
builder_profiles — business name, builder type (nomad_builder/mobile_service/workshop), specialties, pricing, service area, portfolio images, contact info (WhatsApp, phone, website, Instagram)
builder_reviews — star ratings and text reviews for builders
community_posts — forum posts (categories: build_help, showcase, tips, parts_gear)
community_replies — threaded replies on posts
community_likes — likes on posts and replies
user_routes — travel routes with PostGIS geometry line strings
route_intersections — computed spatial/temporal overlaps between user routes
convoy_requests / active_convoys — convoy matching system
route_conversations / route_messages — route-based chat
route_waves — lightweight "wave" interactions on route matches (mutual wave auto-creates connection via create_connection_on_mutual_wave RPC)
verification_requests — photo (liveness) and van verification records
user_reports / user_blocks / user_vouches — safety infrastructure
user_usage — daily usage tracking for free-tier limits
user_locations — location history for proximity features

        Security: Row Level Security (RLS) enabled on every
        table. Users can only access their own data. Connection-based access
        gates chat. Builder profiles are publicly readable.
      

Subscription Integration Details

SDK Setup

Package: purchases_flutter integrated in bootstrap.dart at app startup
Platform-specific API keys loaded from .env (never hardcoded)
RevenueCatService singleton initializes SDK, identifies user by Supabase auth ID
Customer info listener syncs subscription status changes in real-time

Entitlement Model

Single entitlement: pro (configured in subscription dashboard)
Mapped to SubscriptionStatus entity with isPro / isFree computed getters
Subscription tier synced to Supabase users.subscription_tier for server-side enforcement

Provider Architecture (Riverpod)

subscriptionProvider    → SubscriptionNotifier (manages subscription state)
isProProvider           → bool (derived, true if user has 'pro' entitlement)
isFreeProvider          → bool (derived, inverse of isProProvider)
dailyUsageProvider      → DailyUsageNotifier (tracks free-tier daily limits)
offeringsProvider       → FutureProvider<Offerings?> (loads RevenueCat offerings)

Gating Strategy

Tab-level gating (full-screen lock):

Find Builders tab — free users see a locked overlay with upgrade CTA
_BuilderLockedView widget shows Pro benefits and opens paywall

Inline gating (usage limits):

DailyUsageNotifier tracks per-day usage for free-tier users
Connection requests (Connect/Interested): 5/day free, unlimited Pro (enforced in ConnectRequestDialog)
Community posts: 3/day free, unlimited Pro (enforced in CommunityFeedPage)
Camp Scout results: 3 free, unlimited Pro (enforced in CampScoutPage)

Content gating (dating photos):

On dating profiles, free users see the hero photo full-size but additional gallery photos are blurred with a lock icon
Tapping blurred photos opens the paywall with source tracking (gallery_photos)
Pro users see all photos unblurred (enforced in _buildPhotoGallery in DiscoverPage)

Dating verification gate:

Tapping "Interested" on a dating profile requires photo verification
Unverified users see a "Verify to Date" button instead, linking to the verification hub

Paywall:

Custom-built paywall page (PaywallPage) loads RevenueCat offerings
Displays monthly/annual pricing with savings calculation
Feature comparison list (free vs Pro)
Purchase flow via Purchases.purchasePackage()
Restore purchases support
Subscription terms displayed per App Store/Play Store requirements

Purchase Flow

User hits limit → FeatureGate shows upgrade prompt → PaywallPage opens
→ RevenueCat offerings loaded → User selects package → purchasePackage()
→ Google Play billing sheet → Purchase confirmed → CustomerInfo updated
→ subscriptionProvider notified → UI unlocks immediately

Supabase Edge Functions (Deployed)

Function	Purpose	Auth
`create-liveness-session`	Creates AWS Rekognition Face Liveness session	JWT required
`verify-liveness-result`	Validates liveness result, updates user verification	JWT required
`analyze-van-photo`	Gemini Vision 2.0 Flash analyzes van photo for authenticity	JWT required

Verification Flow

Photo verification: User takes selfie → ML Kit face detection (client-side) → AWS Rekognition Face Liveness (server-side) → confidence score → auto-approve if >90%
Van verification: User uploads van photo → Gemini Vision AI analyzes for real van presence → confidence score → auto-approve if >85%
Trust score: Base 50 + photo verified (+20) + van verified (+15) + vouches (+2 each, max +20) = max 100

Real-Time Features (Supabase Realtime)

Chat messages: Instant delivery via Supabase Realtime subscriptions on messages table
Connection requests: Real-time notification when someone sends a connection request
Connection accepted: Real-time notification when your request is accepted
Unread message badges: Live count updates on Chat tab badge
Pending request badges: Live count updates on Likes tab badge

Maps Integration (Mapbox GL)

Route creation: Users set start/end points via Mapbox geocoding autocomplete, route polyline fetched via Mapbox Directions API, stored as PostGIS geometry
Builder map: Shows verified builders on a map with location pins and service areas
Camp Scout: List-based results for nearby campsites, water, fuel, dump stations with radius control (Pro: unlimited results + "Who's Here" social overlay)
Intersection map: Visualizes where two users' routes overlap geographically
Convoy live map: Map view for convoy partners (location sharing infrastructure in progress)

Key Technical Decisions

Riverpod over Bloc — Chosen for compile-time safety, auto-dispose, and cleaner provider composition across 15+ feature modules
Supabase over Firebase — PostgreSQL with RLS provides row-level security without cloud functions for every query; real-time subscriptions built-in
Subscription SDK over raw billing — Abstracts platform billing complexity; single entitlement check works across Android/iOS; dashboard analytics for monetization tracking
PostGIS for routes — Native geospatial queries for route intersection computation; ST_Intersection and ST_Buffer for overlap detection
Edge Functions for AI — Keeps API keys server-side; Deno runtime with Web Crypto API for AWS SigV4 signing