App Architecture

Service layer, progressive sync, authentication, and cross-platform in-app purchases

High-Level Architecture

Flutter App

UI + Services

↔

HTTPS

Supabase

Auth + Edge Functions

↔

Validate

App Stores

Apple + Google

Device Storage

Encrypted audio + JSONs

Core Services (Singletons)

GeneralSettingsService

Copies bundled assets to internal storage on first run. Always reads fresh from disk (no caching).

SyncService

Orchestrates content sync. Tests internet speed (min 1.5 Mbps), builds checksum payload, sends handshake.

ProgressiveSyncOrchestrator

Multi-phase sync: analyze → storage check → download courses → update system JSONs.

SupabaseService

Authentication, session management, local session caching for offline.

UserProvider

ChangeNotifier for user state. Auto-login, session persistence, offline mode.

InAppPurchaseService

Cross-platform IAP. Google Play Billing + Apple StoreKit with backend validation.

Sync Handshake Flow

Speed test — measure internet speed; skip sync if below 1.5 Mbps

↓

Build payload — MD5 checksums of all local JSON files

↓

Handshake — POST /functions/v1/handshake

↓

Receive manifest — server returns list of updates needed

↓

Progressive download — courses, then system JSONs, with progress tracking

Authentication

Method	Details
Email / Password	Standard Supabase auth
Google Sign-In	OAuth via Supabase, deep link callback
Magic Links	Used for device removal confirmation
Offline Mode	Cached local session → HomeScreen without network

Deep links: lucidflow://app (mobile) | Uri.base.origin (web)

In-App Purchases

Platform	Product ID Format	Example
Android	Lowercase course code	h01enb
iOS	Bundle prefix + lowercase	me.hypnoelp.app.h01enb

User selects subscription, course, custom audio, or AI credits

↓

Native purchase via Google Play / App Store

↓

Receipt sent to /functions/v1/validate_purchase

↓

Backend validates → course added → sync triggered

Content Updaters

AdsUpdater

ads.json

BackgroundsUpdater

background.json

CoreSegmentsUpdater

core_segments.json

CourseUpdater

Audio, workbooks, icons

FaqsUpdater

FAQs.json

ShopUpdater

shop.json

Platform Configuration

Platform	Key Setting	Value
Android	Min SDK	23 (Android 6.0)
Android	NDK	29.0.13599879
iOS	Bundle ID	me.hypnoelp.app
iOS	Deep link	lucidflow://
Web	Allowed routes	signup-success, reset-password, auth/callback

Detailed docs: Core Services | Sync System | Auth & IAP | Platform Config

Back to Hypnoelp App