iFarted/memory-bank/systemPatterns.md

System Patterns — iFarted

Target Architecture (user decisions locked: Bun backend + Expo Push API)

[Sender phone — iOS/Android, Expo/RN]
   │  POST /v1/farts { recipientId, lat?, lng? }   (Bearer apiKey)
   ▼
[Bun relay server]  (TypeScript, Hono or plain fetch handlers, bun:sqlite)
   │  auth + rate limit → insert message → call Expo Push API:
   │  POST https://exp.host/--/api/v2/push/send
   │     { to: <recipient ExpoPushToken>, title: senderName,
   │       body: "I farted.", sound: "fart.caf|mp3", data: {...} }
   ▼
[Expo Push Service] → [APNs / FCM]
   ▼
[Recipient phone] → OS notification → tap → in-app fart view (map pin if coords)

Guiding rules:

• No P2P push; no raw APNs/FCM on the server. Bun talks only to the Expo Push API; Expo's service handles APNs/FCM. (Android still needs a Firebase project for the client's FCM token.)
• Thin client, thin backend: client sends a tiny intent; backend validates, persists a stub, and relays; there is no inbox to serve.
• Server must run identically under Bun or Node (keep bun-specific APIs optional so Node is a trivial fallback).

REST API (draft)

Endpoint	Purpose
POST /v1/register	Create user. Body: { username?, phoneE164?, inviteCode? } → returns { userId, apiKey }. Username claim is unique/case-insensitive; inviteCode pre-links.
POST /v1/tokens	Register/refresh device push token { expoPushToken, platform } (Bearer).
POST /v1/farts	Send. Body: { recipientId, lat?, lng? }. Server: check relationship+block list → rate limit → persist → Expo Push. Returns { ok, messageId }.
GET /v1/users/search?username=	Public lookup by username (returns only id/username/displayName — never phone).
POST /v1/contacts	Body: { phoneE164: string[] } → returns which of my contacts are users who enabled phone discovery. Contact numbers hashed/normalized server-side; not stored raw.
POST /v1/invites	Create invite code for my username; client renders as code + deep link (exp:// / https link).
POST /v1/block	Body { userId } → stop receiving/sending.

Mobile Client Patterns

• Navigation: expo-router; flows = auth/onboarding, home(recipients), fart-detail(maps), settings.
• State: React Context or Zustand. No Redux at MVP.
• Home data: recipient list = contacts + people who sent you a fart (latest first, Yo-style), not a server inbox.
• Screens: Onboarding (username/phone/invite) → Home (list + big send + location toggle + ad banner) → Send toast → Fart detail (+ map pin, one-tap fart back) → Settings (Remove Ads + Restore, sound toggle, phone-discovery toggle, account).
• Permissions: notifications at first run with purpose text; location lazily via expo-location only when "attach location" tapped (iOS When-In-Use).
• Ads abstraction: single gated <AdBanner/> routed through one isAdFree flag.
• Deep links: invite links and notification taps both resolve into navigation (messageId or username pre-link).
• Push payload (data): { type:"fart", messageId, senderId, senderName, lat?, lng?, sentAt } — notification body is "I farted.", title is sender name, custom sound file.

Data Model (SQLite)

• users: id, username (unique ci), display_name?, phone_e164?, phone_discovery (bool), invite_code (unique), api_key_hash, created_at, updated_at.
• push_tokens: id, user_id, expo_push_token (unique), platform, last_seen_at.
• relationships: id, owner_id, peer_id, status (added/blocked/pending-invite), added_via (username|contacts|invite), created_at.
• messages: id, sender_id, recipient_id, lat?, lng?, created_at — retained only for rate limiting/abuse/receipts; never rendered as history.
• invites: code, creator_id, created_at, accepted_by_user_id?.

Monetization Architecture

• Product: non-consumable remove_ads in App Store Connect + Play Console.
• Entitlement source of truth = store state (expo-iap or RevenueCat — library TBD; RevenueCat favored for cross-platform entitlement mgmt + restore).
• Launch + purchase + restore resolve isAdFree → ad components unmount and stop loading.
• AdMob: non-personalized ads initially → no ATT complexity.

Security & Privacy (direct responses to the 2014 Yo hack)

• Every endpoint requires Bearer apiKey (random 256-bit, hashed at rest). No unauthenticated PII access.
• Username search returns only non-PII profile fields. Contacts matching uses hash-normalized numbers and only reveals matches to users who enabled discovery.
• Server-side rate limits per sender (e.g., N farts/hour) + per-recipient cap + block list → stops fart-spam/spoofing.
• Location: per-message opt-in, only to the chosen recipient; not logged in analytics.
• Expo push tokens are the only "FCM/APNs" secret-ish material on the server; no server keys ship in the app.
• No API keys/tokens in client source; issued per-install at register.
• Invite deep links carry a random unguessable code, not phone numbers.