Sapid: Technical Documentation
Architecture & Implementation
System Architecture
Sapid is built as a modern cross-platform mobile application with cloud-based synchronization and AI capabilities.
1. System Overview
Sapid is a client-first mobile application that turns unstructured recipe inspiration into structured, actionable meal plans. We chose a "thick client, thin backend" architecture to ensure maximum responsiveness while maintaining a production-grade security posture for sensitive AI and monetization logic.
The system is built on a modern distributed architecture:
- Frontend (Mobile): React Native + Expo (SDK 54), Expo Router for file-based navigation.
- Identity: Clerk for authentication and cross-service identity management.
- Data Layer: Firebase Firestore (Real-time DB) and Firebase Storage (Images).
- Monetization: RevenueCat for cross-platform subscriptions and entitlement enforcement.
- Backend Layer: Node.js Express hosted on Google Cloud Run.
- AI Integration: Google Vertex AI for multimodal recipe extraction.
- Analytics: Mixpanel for event-driven behavior analysis.
- Local Logic: Zustand for state management and Fuse.js for fuzzy ingredient matching.
Diagram 1: High-Level Architecture
graph TD
subgraph Client ["Mobile App (React Native + Expo)"]
UI[User Interface]
Heuristics[Local Heuristics & Fuse.js]
UX[Zustand State]
end
subgraph Identity ["Identity & Auth"]
Clerk[Clerk Auth]
end
subgraph Data ["Cloud Services"]
Firebase[(Firebase Firestore)]
RC[RevenueCat]
Mixpanel[Mixpanel Analytics]
end
subgraph AI ["AI Strategy Layer"]
Proxy[Express AI Proxy]
Gemini[Google Vertex AI]
end
UI <--> Clerk
UI <--> Firebase
UI <--> RC
UI --> Mixpanel
UI --> Proxy
Proxy --> RC
Proxy --> Gemini
Proxy --> UI
style Client fill:#f5fbf6,stroke:#3b8048
style Proxy fill:#3b8048,color:#fff
style Gemini fill:#fef9f0,stroke:#3b8048
2. Authentication and Identity (Clerk)
We utilize Clerk to provide a secure, frictionless entry point for users across Google, Apple, and Email providers. This choice allows us to focus on our core product value while delegating complex security tasks like multi-factor authentication and session management.
- Canonical Identifier: The Clerk
user_idserves as the primary key across our entire ecosystem. - ID Linking: This identifier is mapped directly to Firebase documents, RevenueCat app_user_ids, and Mixpanel user profiles, ensuring a consistent user history regardless of the device.
- Proxy Security: Auth tokens are attached to every proxy request. The proxy validates the sender's identity with Clerk before any AI processing begins, preventing unauthorized API usage.
3. Data Storage and Sync (Firebase)
Sapid is built for the "always-on" user. All user-generated data, including custom recipes, weekly meal plans, pantry items, and shopping lists, is stored in Firebase Firestore.
The Sync Model: We chose Firebase because it provides seamless cloud persistence with minimal latency. The client architecture handles optimistic updates, meaning users see their changes instantly even if they have a weak connection. Full offline support is achieved through local persistence, with data syncing automatically once a connection is re-established.
4. Monetization Architecture (RevenueCat)
Our monetization engine is designed for professional reliability, centered around the Sapid Pro entitlement. We chose RevenueCat because it abstracts the complexity of cross-platform billing, expiration dates, and grace periods.
Server-Side Enforcement
Critical to our security is the realization that client-side checks are not enough. While the app UI unlocks features based on RevenueCat status, all AI-powered Pro features are strictly routed through our Express proxy.
The proxy validates the entitlement by calling the RevenueCat Subscriber API directly using a secret server-side token. We implement a custom caching layer (TTL: 5 mins) to minimize latency while ensuring that if a subscription expires or is revoked, the Pro features are immediately disabled. If the entitlement is invalid, the request is rejected before any AI cost or processing is incurred.
Diagram 2: Pro Feature Enforcement Flow
sequenceDiagram
participant U as User
participant C as Client App
participant P as AI Proxy
participant RC as RevenueCat
participant AI as Gemini AI
U->>C: Taps Pro Feature (e.g. AI Import)
C->>C: Local Entitlement Check
C->>P: Request + Auth Token
P->>RC: Verify Subscription (Secret Key)
RC-->>P: Entitlement Status
alt is Pro
P->>AI: Authorize & Call LLM
AI-->>P: Structured Result
P-->>C: Data Delivered
else not Pro
P-->>C: 401 Unauthorized
C->>U: Show Paywall
end
5. Paywall System and Mixpanel Integration
Sapid's growth strategy is data-driven. We've integrated Mixpanel to track significant milestones in the user's journey, from recipe_import_started to cooking_mode_started.
Growth Thinking: While we currently offer a single production paywall, our architecture is built for experimentation. By segmenting users based on Mixpanel behavior (e.g., users who import frequently but don't plan), we can dynamically present different RevenueCat offerings, optimizing for conversion without structural code changes.
Diagram 3: Paywall Selection Flow
graph LR
subgraph Behavior ["Behavior Phase"]
Events[Mixpanel Events] --> Segment[User Segmentation]
end
subgraph Selection ["Selection Phase"]
Segment --> Rule{Selection Logic}
Rule -->|Import Heavy| Off1[Annual Offer]
Rule -->|Casual User| Off2[Monthly Trial]
end
subgraph Presentation ["Presentation Phase"]
Off1 --> RC[RevenueCat Paywall]
Off2 --> RC
RC --> User((User))
end
style Rule fill:#3b8048,color:#fff
style Behavior fill:#f5fbf6,stroke:#3b8048
6. AI and Express Proxy Layer
Our AI strategy is centralized through a secured Express Proxy. This approach was chosen to ensure:
- Key Protection: No AI API keys are ever stored on the user's device.
- Prompt Control: System prompts are managed server-side, allowing us to tune AI behavior without an app store update.
- Usage Monitoring: We log every AI interaction to optimize performance and prevent abuse.
Diagram 4: AI Request Sequence
sequenceDiagram
participant Client
participant Proxy
participant RC as RevenueCat
participant Gemini as Vertex AI
Client->>Proxy: AI Request (Text/Image/URL)
Proxy->>Proxy: Validate Clerk Session
Proxy->>RC: Enforce Entitlement
Proxy->>Proxy: Inject Specialized System Prompt
Proxy->>Gemini: Request Structured JSON
Gemini-->>Proxy: Raw Data
Proxy->>Proxy: Sanitize & Validate Schema
Proxy-->>Client: Clean Structured Response
7. Recipe Import and Matching Pipeline
The import pipeline is Sapid's core differentiator. We combine deep AI reasoning with fast, local heuristics to create a "magic" import experience that actually understands food. To handle complex sources like Instagram Reels or TikTok videos, we utilize a fully asynchronous pipeline.
Asynchronous Cloud Processing: For video-heavy URLs, the client offloads the request to a Cloud Tasks queue. Our Express proxy acts as a background worker, leveraging tools like Supadata to extract video transcripts and metadata. The user is free to continue using the app or even close it. Once complete, the parsed recipe is synchronized back to the user's device via Firebase real-time listeners.
Hybrid Intelligence: Regardless of how the recipe was extracted, we perform heuristic ingredient matching using fuse.js on the client. This allows for instant fuzzy matching of extracted ingredients to our normalized catalog, reducing server costs and providing immediate feedback for user validation.
Diagram 5: Asynchronous Import & Matching Pipeline
graph TD
Input[URL / Mobile Share] --> Route{Source Type}
Route -->|Standard Web| Sync[Synchronous AI Extraction]
Route -->|Social Media / Video| Async[Cloud Tasks Background Job]
Async --> Supa[Supadata Transcript Extraction]
Supa --> Proxy[AI Extraction via Express Proxy]
Sync --> Proxy
Proxy --> DB[(Firebase Firestore)]
DB --> |Real-time Sync| ClientApp[Mobile App]
ClientApp --> Local[Client Heuristic Matching]
Local --> Fuse[fuse.js Fuzzy Search]
Fuse --> Validation[User Review & Edit]
style Proxy fill:#3b8048,color:#fff
style Async fill:#3b8048,color:#fff
style Local fill:#fef9f0,stroke:#3b8048
style Fuse fill:#fef9f0,stroke:#3b8048
8. Planning and Smart Trip Logic
The Sapid Smart Planner is designed to eliminate the mental load of grocery shopping. The logic follows a cascading dependency model:
- Pantry Subtraction: The system automatically cross-references planned ingredients with your current inventory, ensuring you only buy what you need.
- Aggregation: Ingredients are normalized and combined across multiple recipes (e.g., "3 onions" from two different recipes).
- Smart Trip: Our grouping logic assigns items to categories or specific stores. Users can toggle between Preferred Store Mode (prioritizing favorites) and Efficient Mode (minimizing stops).
9. Cooking Mode
The Cooking Mode is a distraction-free focused UI tailored for the heat of the kitchen. It features immersive step rendering, integrated timer management for every instruction, and a hands-free interaction model designed to keep messy fingers away from the screen.
10. Security and Privacy
We maintain a "Privacy by Design" posture. User data is protected through Firebase security rules that enforce row-level access, and all sensitive operations, such as monetization checks and AI calls, are validated server-side with secret tokens. We chose this architecture because it offers the speed of a modern mobile app with the security of a traditional enterprise system.