Fault Line — Architecture Map

┌─────────────────────────────────────────────────────────┐
│                    CLIENT (Mobile App)                    │
│  React Native 0.76 + Expo SDK 55 + TypeScript            │
│  73 source files | 11 screens | 10 components             │
│  43 service modules | 5 hooks | 3 stores                  │
├─────────────────────────────────────────────────────────┤
│                         ↕ HTTPS                          │
├─────────────────────────────────────────────────────────┤
│               BACKEND (Supabase Cloud)                    │
│  PostgreSQL 15 + PostGIS 3.4 | Row Level Security         │
│  11 tables | 12 RPC functions | 6 triggers                │
│  Auth (magic link) | Storage (report-media bucket)        │
│  Realtime (WebSocket subscriptions)                       │
├─────────────────────────────────────────────────────────┤
│            EDGE FUNCTIONS (Deno Runtime)                   │
│  5 functions | Authenticated | Rate-limited               │
│  escalate-clusters | analyze-photo | ai-generate          │
│  ai-compare-photos | send-report-email                    │
├─────────────────────────────────────────────────────────┤
│              EXTERNAL APIs                                │
│  Anthropic Claude (Haiku 4.5 + Sonnet 4.6)               │
│  Resend (transactional email)                             │
│  Census Bureau Geocoder (election districts)              │
│  OpenStreetMap (offline tile cache)                       │
│  Open311 / SeeClickFix (bidirectional 311 sync)          │
└─────────────────────────────────────────────────────────┘
  

Build System

• app.config.js — Expo config with dotenv. Reads .env at build time via require('dotenv').config()
• eas.json — EAS Build profiles: development (APK), preview (internal), production (auto-increment)
• Bundle ID: com.faultline.app (both platforms)
• TypeScript strict mode. Zero errors.

Navigation

• React Navigation v6: NativeStackNavigator (stack) + BottomTabNavigator (tabs)
• Deep linking: faultline://report/:reportId, faultline://dashboard
• 5 tabs: Home, Report, Map, Dashboard, Profile
• Stack screens: ReportDetail, ARView, Features, PrivacyPolicy, TermsOfService, Onboarding

State Management

• No Redux/MobX — Supabase client + React state + AsyncStorage persistence
• ThemeProvider (React Context): light/dark/system with AsyncStorage persistence
• expo-constants reads config.extra for env vars at runtime

Key Dependencies

• @supabase/supabase-js — DB client with RLS-enforced queries
• react-native-maps — MapView with Markers, Callouts, draggable pins
• expo-camera — CameraView for AR overlay
• expo-image-picker — photo/video capture and gallery selection
• expo-location — GPS, reverse geocoding, heading for AR
• expo-sensors — Accelerometer for bump detection
• expo-speech-recognition — native STT for voice commands
• expo-speech — TTS for audio-guided reporting
• expo-notifications — push notifications with 3 Android channels
• expo-haptics — tactile feedback on all interactions
• @expo/vector-icons — MaterialCommunityIcons throughout
• @sentry/react-native — crash reporting (disabled until DSN configured)
• i18n-js — 5 locales (en, es, pt, zh, ht)

reports (PostGIS)
├── id UUID PK
├── user_id UUID FK→profiles (nullable for anonymous)
├── category TEXT (24 enum values)
├── latitude/longitude DOUBLE PRECISION
├── location_point GEOGRAPHY(POINT,4326) — auto-set by trigger
├── address, city, state, zip TEXT
├── description TEXT
├── size_rating, hazard_level, urgency, condition_level TEXT
├── media JSONB[] — [{id, uri, uploadedUrl, thumbnailUrl, type}]
├── resolved_media JSONB[] — before/after photos
├── vehicle_damage JSONB
├── status TEXT (draft|submitted|acknowledged|in_progress|resolved|closed|rejected)
├── authority_id UUID FK→authorities
├── cluster_id UUID FK→report_clusters
├── upvote_count, confirm_count INTEGER
├── is_anonymous, sensor_detected, offline_queued, is_quick_report BOOLEAN
├── _hp TEXT — honeypot (bot detection)
└── created_at, updated_at, resolved_at TIMESTAMPTZ

profiles
├── id UUID PK FK→auth.users
├── display_name, avatar_url, push_token TEXT
├── total_reports, total_upvotes, total_confirms, points INTEGER
├── badges JSONB[]
└── created_at, updated_at TIMESTAMPTZ

authorities (42 seeded for MA/RI/NH)
├── id UUID PK
├── name, level (federal|state|county|city|town), state, city, county TEXT
├── submission_methods JSONB[] — [{method, endpoint, priority, notes}]
├── boundary_geojson JSONB
├── response_time_avg_days, fix_rate_percent REAL
└── is_active BOOLEAN

report_clusters
├── id UUID PK
├── category TEXT, centroid_lat/lng, centroid_point GEOGRAPHY
├── report_count, unique_reporters INTEGER
├── max_hazard_level, status TEXT
├── authority_id UUID FK→authorities
├── city, state, address TEXT
└── first_reported_at, last_reported_at, submitted_at, escalated_at TIMESTAMPTZ

report_votes (UNIQUE: report_id + user_id + vote_type)
escalation_log (cluster_id, method, recipient, subject, body, status)
feedback (type, name, email, subject, message, status, votes)
ai_cache (report_id, task_type, result JSONB, model)
submission_log (user_id, ip_address, user_agent)
cluster_reports (cluster_id, report_id — link table)
  

Key Triggers

• set_report_point — BEFORE INSERT/UPDATE: auto-creates PostGIS geography point from lat/lng
• auto_cluster_on_insert — AFTER INSERT: assigns report to nearest cluster (50m radius, same category) or creates new cluster
• enforce_rate_limit — BEFORE INSERT: rejects if user has 10+ reports in last hour
• reject_honeypot — BEFORE INSERT: rejects if _hp field is populated (bot detection)
• handle_new_user — AFTER INSERT on auth.users: auto-creates profile row

Key RPC Functions

• get_nearby_reports(lat, lng, radius_km) — PostGIS ST_DWithin query
• get_nearby_clusters(lat, lng, radius_km) — same for clusters
• assign_report_to_cluster(report_id) — clustering algorithm
• get_clusters_ready_for_escalation() — confirmed + 10 reports + 30 days
• get_cluster_summary(cluster_id) — full data for email generation
• find_authority_by_point(lat, lng) — PostGIS boundary lookup
• award_points(user_id, points) — gamification point system
• increment_upvote/increment_confirm(report_id) — atomic counter updates

RLS Policies

• All tables: SELECT open to everyone (public data)
• reports INSERT: user_id IS NULL OR auth.uid() = user_id
• reports UPDATE/DELETE: auth.uid() = user_id
• profiles UPDATE/DELETE: auth.uid() = id
• feedback INSERT: open (no auth required)

System prompt provides full app context: 24 categories, 3 state statutes with notice periods, clustering thresholds, anti-hallucination rules.

• Zero secrets in client — only Supabase publishable key (public by design, gated by RLS)
• Edge functions require auth — Bearer token validated via supabase.auth.getUser()
• Server-side rate limiting — Postgres trigger, cannot bypass by decompiling app
• Bot honeypot — _hp column, BEFORE INSERT trigger rejects non-empty
• Domain whitelist — createPinnedFetch() wraps global.fetch, blocks non-whitelisted domains, enforces HTTPS
• File validation — magic byte checks (JPEG/PNG/GIF/WebP/BMP), 5MB limit
• Deep link validation — UUID regex before any DB query
• Root/jailbreak detection — logged, not blocked (civic app)
• CSP on all web pages — no external scripts, no frames, no objects
• Email obfuscation — JS runtime reconstruction, not in HTML source

1. supabase/schema.sql — core tables, PostGIS, triggers, RLS, RPC functions
2. supabase/seed_authorities.sql — 42 MA/RI/NH authorities with real contact info
3. supabase/clustering.sql — cluster tables, auto-assign trigger, escalation functions
4. supabase/migration_001_add_missing_columns.sql — urgency, condition, quick report, cluster_id, resolved_media, push_token
5. supabase/migration_002_missing_rpcs.sql — award_points, get_nearby_clusters
6. supabase/migration_003_security_fixes.sql — RLS: enforce user_id on insert, add DELETE policies
7. supabase/migration_004_server_rate_limit.sql — rate limit trigger, honeypot, submission_log
8. supabase/migration_005_feedback.sql — feedback table with RLS
9. supabase/migration_006_ai_cache.sql — AI result cache table
10. supabase/migration_007_rpc_auth_guards.sql — increment_upvote / increment_confirm now require auth; prevent self-voting
11. supabase/migration_008_reports_insert_rls.sql — tightened INSERT policy so an attacker cannot forge reports under another user's ID
12. supabase/migration_009_schedule_escalation_cron.sql — enable pg_cron + pg_net, schedule escalate-clusters-daily to run at 14:00 UTC every day

One-time costs: Google Play $25. That's it.

Revenue potential: Banner ads at $1-3 eCPM. 500 DAU × 3 impressions = 1,500/day = 45K/month = $45-135/month in ad revenue. Covers all costs at ~300 DAU.