Allin — engineering deep dive

01Stack & the core loop

Allin is an iOS wellbeing app: a daily emotional check-in routes the user to a matched guided-audio "rewire" session, plus a 10-step beliefs plan, an audio library and a journal.

• Client: SwiftUI, repo Maelwi/allin-ios → ~/Documents/allin-gh/allin-ios, branch main. Bundle com.allinwellltd.allin, App Store ID 6754271583, v2.2(5).
• Backend: Supabase wsxpmcbtcknewpiwudsc (us-east-1) — repo Maelwi/allin-backend → ~/Documents/allin-backend. Postgres + Auth (Sign in with Apple) + Storage (bucket audio-sessions) + 2 Deno edge functions.
• Third-party (SPM): supabase-swift, Segment analytics-swift, RevenueCat purchases-ios, facebook-ios-sdk. All analytics/subscription/Meta code is behind #if canImport(...) — compiles + no-ops until the packages/keys are present.

The loop: check in (emotion → situation → intensity+body → intent) → routed to a matched audio → reflect (pre/post mood + note) → journal/streak. The plan is a parallel 10-step path with the same reflect mechanic per step.

02Launch & app entry

03Auth & identity

Core/AuthenticationManager.swift — Apple Sign In via Supabase, session restore, and identity fan-out.

04AppView — the orchestrator

Core/AppView.swift is the hub: it owns every top-level @StateObject (auth, sessions, plan, audio library) and a currentScreen: AppScreen switch across ~15 screens, and it hosts the whole check-in → recommendation → audio → reflection flow.

Other key handlers: applyPendingDeepLinkIfReady() (:403, waits for auth+onboarding+library before applying a deep link), handleStartCheckIn() (:512), handleSessionComplete() (:623, carries reframe+reflectionNotes through the completion upsert — fixes an earlier NULLing bug), checkForceUpgrade() (:718, vs app_config min version, fails open).

05Check-in flow & gates

Home/EmotionalCheckIn.swift is a step state-machine whose step list changes by lane.

enum Step { emotion, situation, intensity, intent,      // universal core
            consent, belief, pattern, origin, kinder,   // Unblock tail
            claritySubTap, confidenceSubTap, embodyNew } // Clarity/Confidence tails

Core is always [emotion, situation, intensity, intent]; then it forks on AudioLane(selectedIntent): soothe → (none); clarity → +claritySubTap; embody → +[confidenceSubTap, embodyNew]; unblock/default → +[consent, belief, pattern, origin, kinder]. Indices are clamped with min(currentStep, steps.count-1) because the list length changes mid-flow.

The in-flow gates — handleNext() (:849)

• Crisis tripwire on text steps (emotion/belief): if crisisDetected(crisisText()) { onCrisis() }. On situation it runs an async layered check (crisisGateThenAdvance).
• Express gate (:871): if step == .intensity && Int(intensity) >= 7 → checkExpressOrAdvance: classifies valence, and if .unpleasant completes immediately (skipping the intent fork) so the router forces soothe-first; if .pleasant it advances to the fork.

06The router & classifiers

Core/CheckinRouter.swift — static func route(_ c: CheckIn, catalog:) async -> Recommendation (:165). Gate order:

1. Crisis A (:174): keyword crisisDetected(allText) → safety_handoff, no network.
2. Crisis B + affect, concurrent (:178): async let the euphemism classifier and the affect classifier; if crisis → handoff.
3. Intensity × valence (:184): mustSootheFirst = (c.intensity >= 7 && valence == .unpleasant) → activeLane = mustSootheFirst ? .soothe : intentLane. Authoritative gate, threshold 7.

Candidate resolution: filter catalog by activeLane, then lane-narrow (soothe → sleep-need if mentionsSleep else emotion-family match; clarity/embody → sub-tap → need map). 1 candidate → use it; 0 → lane default; blank situation → default with no AI call; else AIRouter.pick POSTs candidates to edge fn /recommend-audio and validates the returned id is in-set (else falls back to default).

07Crisis detection

Three independent layers; any one triggers the support hand-off. High-recall by design.

• Layer A (on-device keyword): crisisDetected() substring-matches a 21-phrase list ("kill myself", "want to die", "self harm", "overdose", …). Scans only free-text (customEmotion, triggerText, customBelief) — chips aren't crisis signal.
• Layer B (edge classifier): CrisisClassifier.flags() POSTs to /classify-crisis for euphemisms; network failure → false (layers A + C still cover).
• Layer C: the router's own safety_handoff when no audio resolves.

CrisisResources.forCurrentRegion() (region from Locale.current.region): US/CA 988, GB/IE Samaritans 116 123, AU Lifeline 13 11 14, NZ 1737, else findahelpline.com; plus a constant emergency line (911/999/000/111/112). Tap-to-dial via UIApplication.open. CrisisSupportView shows no audio. Gap: no UK Shout 85258 text line.

08Audio selection & playback

Two matchers coexist: the new router (primary) and a legacy keyword matcher (Core/AudioLibraryStore.swift) used as fallback when the routed audio isn't playable.

09Beliefs plan engine

iOS BeliefsPlanManager (cache) → BeliefsPlanService (I/O) → edge fn recommend-plan (composition). The whole path is deterministic Postgres FTS — no LLM.

Server: recommend-plan/index.ts

Service-role client validates the JWT via getUser(token) (the fn is deployed --no-verify-jwt, so this is the only auth gate). validateIntake requires exactly 3 areas with all 4 text fields. Then buildFTSPlan:

• allocateSteps: rating→steps (r≤3→4, ≤6→3, else 2), adjust to total 10; sequenceStepAreas interleaves so areas don't clump.
• Per area: buildAreaQuery concatenates the 4 fields, strips stop-words, OR-joins tokens → RPC search_audio_library(query_text, 20) → keep only candidates whose cluster ∈ AREA_CLUSTERS[area] (structured gate); fallbacks = cluster-mapped, then any non-situational.
• Pick top per step; step_type alternates reset/rewire by parity; repeats allowed; final fallback slug unblocking_empowerment_legacy.
• Persists: marks prior plans is_active=false, inserts beliefs_plans (intake_json) + 10 beliefs_plan_steps, re-selects joined with audio_library, fires server event plan_generated.

10Data layer & sessions

11Analytics & lifecycle

iOS Segment SDK + backend edge fns → Segment "Allin iOS" source → Amplitude + Customer.io (EU) + Meta.

• AnalyticsClient (Segment): configure() with lifecycle-tracking on, flushAt 20 / interval 30s. identify(userId, email) on sign-in; track/screen; registerDeviceToken → CIO push. iOS must not fire plan_generated/_failed — the backend emits those (double-count guard).
• MetaAdsClient: configure enables auto-app-events + IDFA collection at launch; ATT (requestTrackingAuthorization) is only called from the consent sheet (not at launch). trackPurchase, trackCompleteRegistration. trackStartTrial() is defined but unused.
• _shared/segment.ts (server): fetch-only track (no identify); no-op if SEGMENT_WRITE_KEY unset; swallows all errors. Server events: plan_generated, plan_generation_failed, and from revenuecat-webhook the subscription_* family.

12Subscriptions & entitlements

Entitlement RPCs (live SQL, §13/§14): can_start_audio_session() — active sub → unlimited; trial_audio_sessions_used < 10 → trial; else rolling-7-day free; else paywall. record_audio_session_complete() increments the counter / stamps last_free_audio_at. iOS EntitlementService fails open (rpc_error_fail_open) so an infra hiccup never walls a user.

13Backend: migrations, RPCs, CI

9 migrations under supabase/migrations/. Highlights: audio_library (+ GIN tag indexes), beliefs_plans/_steps (RLS own-rows, cascade to auth.users), storage bucket audio-sessions, the FTS search_vector, user_entitlements (+ entitlement RPCs + triggers), an emotional_sessions reframe column patch, the situational cluster data-migration, and checkin_config.

Live RPC bodies (from prod)

-- delete_user(): cascading erase (auth.users delete cascades to all user tables)
delete from public.emotional_sessions where user_id = auth.uid();
delete from public.users            where id      = auth.uid();
delete from auth.users              where id      = auth.uid();

-- search_audio_library(query_text, limit_count=10): ranked FTS
SELECT * FROM audio_library
 WHERE search_vector @@ websearch_to_tsquery('english', query_text)
 ORDER BY ts_rank(search_vector, websearch_to_tsquery('english', query_text)) DESC, created_at DESC
 LIMIT limit_count;

Also live but unused by the app yet: record_consent_granted() and has_granted_consent() exist (they write/read user_entitlements.consent_granted_at) — the durable consent record the GDPR plan calls for is already scaffolded in the DB, just not wired from iOS. handle_new_user() + ensure_user_entitlement() triggers auto-create users + user_entitlements rows on signup.

CI — .github/workflows/deploy.yml

Push to main, path-filtered jobs (parallel): migrations/** → supabase db push; functions/** → deploy only recommend-plan (--no-verify-jwt); seed/audio_metadata.json → node scripts/seed.mjs (PostgREST upsert on slug). Auth via repo secrets SUPABASE_ACCESS_TOKEN/_DB_PASSWORD/_SERVICE_ROLE_KEY.

14Data model & RLS

Every user-owned table has ON DELETE CASCADE to auth.users, so delete_user() fully erases the database (verified). Special-category (mental-health) free-text lives in emotional_sessions, beliefs_plans.intake_json, and beliefs_plan_steps.feedback_text — the targets for the GDPR pseudonymisation/encryption work.

15Known bugs & dead code

16Env & secret locations

No secret values here — locations only. Full values live in your password manager / the vaults below.