SpeakTrue

Repository Onboarding Reference (Surface- and Function-Depth)

Last refreshed: 2026-06-29

Use this as the first read for first-contact engineering, incident response, and change planning.

What this document is

This document answers:

• What each surface (iOS, Android, web, backend) owns.
• Which files to touch for specific behavior changes.
• What every backend function does and where callers live.
• Deployment and verification commands by surface.
• How to edit safely without breaking parity or auth/contract boundaries.

For complete file-by-file ownership enumerations, use:

• docs/reference/ios-file-inventory.md
• docs/reference/android-file-inventory.md
• docs/reference/web-file-inventory.md

This document keeps those inventories as source-of-trust and adds change-oriented context and behavioral mappings.

1) Golden architecture rules

1. Privileged provider and credential operations stay on backend contracts (backend/supabase/functions/*).
2. Clients call edge functions for speech/voice/soundboard/identity operations.
3. Storage and entitlement changes must be reflected in:
   • backend handler logic
   • callers in iOS/Android/legacy web
   • DB migration(s)
   • function tests + platform contract tests
4. When changing runtime behavior, keep docs/index and these inventories consistent with behavior.

2) Deployment and code surfaces quick map

Surface	Primary roots	Notes
iOS app	ios/	SwiftUI + service/feature split + tests
Android app	android/	Jetpack Compose + DI/core + feature modules + tests
Legacy web app	web/python-web-app/	Flask request surface + service/router layer + legacy compatibility seam
Marketing web	web/marketing/	Static hosting + waitlist callback/copy
Backend	backend/supabase/	Edge functions + shared helpers + migrations + migration SQL

3) iOS surface: what and where

3.1 Startup and control flow

• App bootstrap: ios/SpeakTrue/SpeakTrueApp.swift
• Root navigation and auth gate:
  • ios/SpeakTrue/ContentView.swift
  • ios/SpeakTrue/AuthGateView.swift
  • ios/SpeakTrue/MainTabView.swift
• Shared app-level config and clients:
  • ios/SpeakTrue/SupabaseConfig.swift
  • ios/SpeakTrue/SupabaseClientProvider.swift
  • ios/SpeakTrue/AuthService.swift
  • ios/SpeakTrue/AIProxyService.swift
• Auth/state entry:
  • ios/SpeakTrue/AuthState.swift
  • ios/SpeakTrue/UserSettings.swift

3.2 If you change X in iOS, edit Y

• TTS defaults / voice behavior
  • ios/SpeakTrue/TTSViewModel.swift
  • ios/SpeakTrue/TextToSpeechView.swift
  • ios/SpeakTrue/TTSCatSelectView.swift
  • backend/supabase/functions/user-settings-*
  • migration in backend/supabase/migrations/
• STT / STS behavior
  • ios/SpeakTrue/STTViewModel.swift
  • ios/SpeakTrue/STSViewModel.swift
  • ios/SpeakTrue/SpeechToTextView.swift
  • ios/SpeakTrue/SpeechToSpeechView.swift
  • ios/SpeakTrue/AudioRecorderService.swift
  • ios/SpeakTrue/LiveVoiceSTSService.swift
  • ios/SpeakTrue/RealtimeSTTService.swift
  • backend functions: sts-*
• Soundboard behavior
  • ios/SpeakTrue/SoundboardViewModel.swift
  • ios/SpeakTrue/SoundboardView.swift
  • ios/SpeakTrue/SoundboardCacheManager.swift
  • ios/SpeakTrue/SoundboardCacheIndex.swift
  • backend functions: soundboard-*
• Voice clone behavior
  • ios/SpeakTrue/VoiceCloneTabView.swift
  • ios/SpeakTrue/VoiceCloneViewModel.swift
  • backend: voice-clone-*
• Settings and subscription gating
  • ios/SpeakTrue/SettingsTabView.swift
  • ios/SpeakTrue/SettingsView.swift
  • ios/SpeakTrue/SettingsModels.swift
  • ios/SpeakTrue/UserSettingsSyncService.swift
  • backend: user-settings-*, quota-status, _shared/subscription-gating-config.ts

3.3 Tests that should change on iOS behavior edits

• VM/service behavior: ios/SpeakTrueTests/*ViewModel*, *Tests.swift
• Settings contract and defaults: ios/SpeakTrueTests/Settings*
• UI flow checks: ios/SpeakTrueUITests/*

3.4 iOS deployment checklist

1. Build/run in Xcode for selected target.
2. Verify signing and environment in ios/Config/App.*.xcconfig if changing runtime keys.
3. Run changed-feature smoke checks manually before commit.

4) Android surface: what and where

4.1 Startup and control flow

• App and DI entry: android/app/src/main/java/com/speaktrue/app/SpeakTrueApp.kt
• Activity shell: android/app/src/main/java/com/speaktrue/app/MainActivity.kt
• Navigation host: android/app/src/main/java/com/speaktrue/ui/navigation/AppNavGraph.kt
• Core network/auth/runtime:
  • android/app/src/main/java/com/speaktrue/core/config/RuntimeConfig.kt
  • android/app/src/main/java/com/speaktrue/core/network/*
  • android/app/src/main/java/com/speaktrue/core/auth/*
  • android/app/src/main/java/com/speaktrue/core/audio/*
  • android/app/src/main/java/com/speaktrue/core/storage/*

4.2 If you change X in Android, edit Y

• TTS behavior
  • android/app/src/main/java/com/speaktrue/features/tts/data/*
  • android/app/src/main/java/com/speaktrue/features/tts/presentation/TTSViewModel.kt
  • android/app/src/main/java/com/speaktrue/features/tts/ui/TTSScreen.kt
  • backend: tts-generate, models-list, voices-list, user-settings-*, quota-status
• STT / STS behavior
  • android/app/src/main/java/com/speaktrue/features/stt/*
  • android/app/src/main/java/com/speaktrue/features/sts/*
  • android/app/src/main/java/com/speaktrue/features/sts/data/*
  • backend: stt-transcribe, sts-*
• Soundboard behavior
  • android/app/src/main/java/com/speaktrue/features/soundboard/*
  • backend: soundboard-save-generated, soundboard-delete, clip-order-batch
• Voice clone behavior
  • android/app/src/main/java/com/speaktrue/features/voiceclone/*
  • backend: voice-clone-preflight, voice-clone-create, voice-clone-delete
• Settings and contract surfaces
  • android/app/src/main/java/com/speaktrue/features/settings/*
  • android/app/src/main/java/com/speaktrue/features/agreement/*
  • backend/supabase/functions/user-settings-*

4.3 Android tests to touch on edits

• Unit and contract: android/app/src/test/java/com/speaktrue/**
• Instrumentation smoke: android/app/src/androidTest/java/com/speaktrue/**
• Keep parity tests green:
  • GenerationContractParityTest
  • SettingsContractParityTest
  • SoundboardContractParityTest
  • VoiceCloneContractParityTest

4.4 Android release/deploy commands (project-standard)

• Debug build: ./gradlew -p android :app:assembleDebug
• Release bundle: ./gradlew -p android :app:bundleRelease
• Unit tests: ./gradlew -p android :app:testDebugUnitTest
• Lint: ./gradlew -p android :app:lintDebug
• Play release checks: run scripts in android/scripts/ and docs/ops/ANDROID_PLAY_RELEASE_CHECKLIST.md

5) Web surface: marketing + legacy web

5.1 Marketing surface

• Static entry points: web/marketing/index.html, web/marketing/auth/callback/index.html
• Runtime behavior: JS + CSS assets only (web/marketing/scripts, web/marketing/styles)
• Deployment: static hosting (docs/ops/CLOUDFLARE_PAGES_DEPLOY.md)

5.2 Legacy web runtime

• App/WSGI bootstrap:
  • web/python-web-app/wsgi.py
  • web/python-web-app/src/app.py
• Route layer:
  • web/python-web-app/src/routes/*.py
• Service/business layer:
  • web/python-web-app/src/services/*.py
• Templates/static:
  • web/python-web-app/templates/*
  • web/python-web-app/static/*
• Compatibility seam:
  • web/python-web-app/src/legacy_runtime_adapter.py
  • web/python-web-app/src/legacy_runtime.py

5.3 If you change web behavior, edit Y

• Speech route/service behavior
  • web/python-web-app/src/routes/stt.py, tts.py
  • web/python-web-app/src/services/stt_service.py, tts_service.py, speech_service.py
  • JS runtime checks in web/python-web-app/static/js/*
  • tests in web/python-web-app/tests/* and web/python-web-app/tests/js/*
• Settings and user settings behavior
  • web/python-web-app/src/routes/settings.py
  • web/python-web-app/src/services/user_settings_service.py
  • web/python-web-app/templates/settings.html
  • settings JS in web/python-web-app/static/js/index_settings.js
  • tests in web/python-web-app/tests/test_settings*
• Soundboard behavior
  • web/python-web-app/src/routes/soundboard.py
  • web/python-web-app/src/services/soundboard_service.py
  • web/python-web-app/static/js/index_soundboard.js
  • templates under web/python-web-app/templates/soundboard/*
• STS and STT realtime behavior in web
  • web/python-web-app/src/routes/stt.py
  • web/python-web-app/static/js/index_speech.js, index_stt.js, index_sts_live_voice.js
  • tests in web/python-web-app/tests/js/sts_*.mjs

6) Backend function deep map

This section is the canonical behavior map for function ownership and maintenance.

Legend:

• route is the logical endpoint name at /functions/v1/<route>.
• read = read-only operation.
• write = persistence or mutation operation.
• providers = third-party API interactions.

6.1 Auth / billing / entitlement functions

account-delete

• route: /account-delete
• files: backend/supabase/functions/account-delete/index.ts, handler.ts, handler_test.ts
• what it does: Deletes signed-in user account and related resources via handler orchestration; rejects unauthorized requests.
• behavior contract: strict auth checks, idempotent error/success envelope.
• callers: native apps settings/account deletion flows.

billing-apple-sync

• route: /billing-apple-sync
• files: backend/supabase/functions/billing-apple-sync/index.ts, logic.ts, logic_test.ts
• what it does: Accepts Apple transaction IDs, contacts Apple server API, resolves transaction state and entitlement mapping (active/expired/revoked), and classifies mutation decisions for entitlement writes.
• providers: Apple App Store Connect API (itunes endpoints), auth JWS flow.
• callers: backend admin/billing sync flows.

billing-apple-notifications

• route: /billing-apple-notifications
• files: backend/supabase/functions/billing-apple-notifications/index.ts, handler.ts, handler_test.ts, deno.json
• what it does: Processes signed Apple push notifications, safely ignores unsupported events, validates mapping and signature, and writes entitlement mutations with deterministic skips and errors.
• providers: Apple JWS decode and entitlement policy helpers.
• special note: webhook security paths must remain strict; unsupported notification types should not mutate state.

billing-google-play-sync

• route: /billing-google-play-sync
• files: backend/supabase/functions/billing-google-play-sync/index.ts, handler.ts, google-play-verifier.ts, google-play-verifier_test.ts, handler_test.ts
• what it does: Verifies Google Play signed token payloads and applies entitlement updates using replay-safe mutation policy.
• providers: Google Play token verifier.

billing-stripe-webhook

• route: /billing-stripe-webhook
• files: backend/supabase/functions/billing-stripe-webhook/index.ts, logic.ts, dispatch.ts, persistence.ts, signature.ts, validation.ts, *_test.ts
• what it does: Verifies webhook signatures, validates payload shape, routes stripe events, deduplicates webhook payloads, and applies entitlement transitions with conflict resolution.
• callers: billing infra and entitlement readers.

6.2 Speech and translation functions

stt-transcribe

• route: /stt-transcribe
• files: backend/supabase/functions/stt-transcribe/index.ts, capture.ts, capture_test.ts, validation.ts, validation_test.ts, handler.ts, handler_test.ts
• what it does: Validates auth + request format, resolves quota and usage policies, invokes provider transcription path, and returns transcript payload with error envelopes.
• providers: provider dispatch configured by backend/user key settings.
• read/write: read + writes usage counters.

tts-generate

• route: /tts-generate
• files: backend/supabase/functions/tts-generate/index.ts, handler.ts, pronunciation.ts, pronunciation_test.ts, policy.ts, policy_test.ts, handler_test.ts
• what it does: Validates input, applies policy + quotas, resolves model/voice/user defaults, calls TTS provider, handles artifact_mode, and returns speech artifact metadata.
• providers: ElevenLabs (and configured provider route).
• read/write: reads settings, writes usage + artifact metadata.

language-recommend

• route: /language-recommend
• files: backend/supabase/functions/language-recommend/index.ts, handler.ts, handler_test.ts
• what it does: Returns recommended language options based on user/platform constraints and provider recommendation rules.

models-list

• route: /models-list
• files: backend/supabase/functions/models-list/index.ts, handler.ts, handler_test.ts
• what it does: Returns available speech model catalog with entitlement-aware filtering and provider mapping.

voices-list

• route: /voices-list
• files: backend/supabase/functions/voices-list/index.ts, handler.ts, handler_test.ts
• what it does: Returns available voices with private/public filtering, ownership checks, and default selection semantics.

6.3 STS workflow functions

sts-live-voice-tts-session

• route: /sts-live-voice-tts-session
• files: backend/supabase/functions/sts-live-voice-tts-session/index.ts, handler.ts, handler_test.ts
• what it does: Starts live voice-to-speech path: validates live workflow payload, builds provider socket contract, and prepares auth token/materialization for streaming.

sts-near-realtime-session

• route: /sts-near-realtime-session
• files: backend/supabase/functions/sts-near-realtime-session/index.ts, handler.ts, handler_test.ts
• what it does: Boots near-realtime STS mode session, issues STT and TTS socket contracts, and persists snapshot context for finalize path.

sts-realtime-session

• route: /sts-realtime-session
• files: backend/supabase/functions/sts-realtime-session/index.ts, handler.ts, handler_test.ts
• what it does: Legacy/active near-live start path. Validates and returns provider token + session metadata for realtime STS.

sts-realtime-finalize

• route: /sts-realtime-finalize
• files: backend/supabase/functions/sts-realtime-finalize/index.ts, handler.ts, handler_test.ts
• what it does: Finalization pass for realtime/live STS sessions: merges artifact/transcript, handles metadata-only finalize, persists transcript and artifact results, maps errors from providers, and returns final contract.

sts-live-interpreter-session (migration/untracked state)

• route: /sts-live-interpreter-session
• files: backend/supabase/functions/sts-live-interpreter-session/index.ts
• what it does: New migration function path for interpreter live mode bootstrap.
• current status: currently only entrypoint scaffold; verify if this function is intentionally staged and implement handler layer before release.

sts-live-interpreter-tts-session (migration/untracked state)

• route: /sts-live-interpreter-tts-session
• files: backend/supabase/functions/sts-live-interpreter-tts-session/index.ts
• what it does: Live interpreter relay-to-TTS session bootstrap path in migration stream.
• current status: currently only entrypoint scaffold; verify implementation completeness before any routing changes.

6.4 Settings and profile functions

user-settings-get

• route: /user-settings-get
• files: backend/supabase/functions/user-settings-get/index.ts, handler.ts, handler_test.ts
• what it does: Returns persisted settings with defaults + migration compatibility behavior for workflow flags.

user-settings-update

• route: /user-settings-update
• files: backend/supabase/functions/user-settings-update/index.ts, handler.ts, handler_test.ts
• what it does: Applies partial patch updates to user settings, validates setting shapes, normalizes malformed values, writes defaults/override flags.

quota-status

• route: /quota-status
• files: backend/supabase/functions/quota-status/index.ts, handler.ts, handler_test.ts
• what it does: Reads and returns usage counters/limit status for TTS/STT + other quota surfaces.

6.5 Data write and content management functions

clip-order-batch

• route: /clip-order-batch
• files: backend/supabase/functions/clip-order-batch/index.ts, handler.ts, handler_test.ts
• what it does: Applies mixed clip and folder reorder payloads with ownership and persistence checks.

soundboard-save-generated

• route: /soundboard-save-generated
• files: backend/supabase/functions/soundboard-save-generated/index.ts, handler.ts, handler_test.ts
• what it does: Saves generated audio clips from artifacts/storage paths into user soundboard, handles transcript copy/linking, dedupes filename conflicts, and cleans up transient artifact artifacts on failure.

soundboard-delete

• route: /soundboard-delete
• files: backend/supabase/functions/soundboard-delete/index.ts, handler.ts, delete_storage_error.ts, delete_storage_error_test.ts, handler_test.ts
• what it does: Deletes soundboard clip entries, supports soft-delete behavior and ownership checks, and normalizes storage cleanup.

soundboard-clip-ingest (migration/untracked state)

• route: /soundboard-clip-ingest
• files: backend/supabase/functions/soundboard-clip-ingest/ (currently empty)
• what it does: Not implemented in tracked source yet.
• action: either implement fully or remove the directory to avoid confusion.

pronunciation-dictionary

• route: /pronunciation-dictionary
• files: backend/supabase/functions/pronunciation-dictionary/index.ts, handler.ts, handler_test.ts
• what it does: Read/write pronunciation map entries with validation and DB fallback semantics.

bug-report-submit

• route: /bug-report-submit
• files: backend/supabase/functions/bug-report-submit/index.ts, handler.ts, handler_test.ts
• what it does: Accepts structured bug report payloads, stores/report-forwards and handles email/queue failure states as non-fatal reporting state where configured.

style-presets

• route: /style-presets
• files: backend/supabase/functions/style-presets/index.ts, handler.ts, handler_test.ts
• what it does: Fetches/updates preset lists and style metadata consumed by generation UI/features.

pronunciation-dictionary, style-presets, language-recommend, voices-list are important for speech UX parity and should remain in sync with mobile-side UI.

6.6 BYOK and keys

byok-resolve

• route: /byok-resolve
• files: backend/supabase/functions/byok-resolve/index.ts, handler.ts, handler_test.ts
• what it does: Resolves whether BYOK is enabled and returns status without exposing secret material.

byok-upsert

• route: /byok-upsert
• files: backend/supabase/functions/byok-upsert/index.ts, handler.ts, handler_test.ts
• what it does: Upserts user key configuration state and toggles BYOK enablement.

waitlist-signup

• route: /waitlist-signup
• files: backend/supabase/functions/waitlist-signup/index.ts, handler.ts, handler_test.ts
• what it does: Captures email captures, deduplicates duplicates, and supports marketing capture semantics.

voice-clone-preflight

• route: /voice-clone-preflight
• files: backend/supabase/functions/voice-clone-preflight/index.ts, handler.ts, validation.ts, validation_test.ts, handler_test.ts
• what it does: Runs preflight checks for voice cloning constraints, returning normalized checklist-like readiness outcomes before create.

voice-clone-create

• route: /voice-clone-create
• files: backend/supabase/functions/voice-clone-create/index.ts, handler.ts, validation.ts, validation_test.ts, handler_test.ts, telemetry.ts, telemetry_test.ts
• what it does: Validates and executes voice-clone creation flow, calls provider clone creation, maps provider errors, and stores provider-linked metadata.

voice-clone-delete

• route: /voice-clone-delete
• files: backend/supabase/functions/voice-clone-delete/index.ts, handler.ts, validation.ts, validation_test.ts, handler_test.ts
• what it does: Deletes user voice clone and cleans provider metadata if needed.

7) Shared backend helpers (read before editing function logic)

• backend/supabase/functions/_shared/cors.ts (CORS envelope behavior)
• backend/supabase/functions/_shared/auth-context.ts (auth extraction and resolution)
• backend/supabase/functions/_shared/usage.ts (usage counters and usage metadata)
• backend/supabase/functions/_shared/quotas.ts (quota computations)
• backend/supabase/functions/_shared/entitlements.ts (entitlement fetch helpers)
• backend/supabase/functions/_shared/billing-entitlement-policy.ts (entitlement precedence/de-duplication)
• backend/supabase/functions/_shared/private-voice-access.ts (private voice gating)
• backend/supabase/functions/_shared/byok.ts (BYOK utilities)
• backend/supabase/functions/_shared/subscription-gating-config.ts (feature flags, if you are touching gating)

8) Migration and data schema map for backend-safe changes

When backend behavior changes touch persistence, migration strategy is:

1. Add new migration under backend/supabase/migrations/ with a timestamp and clear intent in filename.
2. Update dependent function tests and contracts in backend/supabase/functions/*_test.ts.
3. Update client callers (iOS/Android/web) if request/response contracts change.
4. Update docs/contracts and surface docs.
5. Run function + coverage gate command(s).

Duplicate migration naming risks exist in current history; avoid reusing older migration stamps and prefer strictly monotonic filenames.

9) Deployment and operations playbook by change type

9.1 iOS release change

• Update code + tests in ios/ and any assets in ios/ as needed.
• Build in Xcode + run impacted XCTest suites.
• Verify Info.plist / xcconfig values only when key behavior changes.

9.2 Android release change

• Run ./gradlew -p android :app:testDebugUnitTest and ./gradlew -p android :app:lintDebug before merge.
• Use Play release scripts in android/scripts/ for screenshot/verification if release-bound.

9.3 Backend function change

• Run function tests for changed directories.
• Update any SQL migration needed.
• Redeploy function from CLI for changed directories.
• Verify web/native contracts and parity tests.

9.4 Legacy web change

• Update route/service/tests/templates in web/python-web-app/ together.
• Run Python tests (pytest) and JS browser checks (web/python-web-app/tests/js/*.mjs) for public-facing behavior.

9.5 Marketing change

• Update static assets and scripts in web/marketing/.
• Deploy via Cloudflare Pages flow (docs/ops/CLOUDFLARE_PAGES_DEPLOY.md).

10) If you are asked “where do I change X Y Z”

Use this decision checklist:

• Add or change feature defaults for all clients: 1) migrate defaults SQL → 2) backend user settings handlers → 3) platform mappers/tests (iOS + Android + web) → 4) docs/contracts.

• Change voice availability / filtering: 1) backend entitlements/voice list functions (voices-list, _shared/private-voice-access.ts) → 2) client catalogs/view models (voices/language) → 3) parity tests.

• Change soundboard ordering rules: 1) clip-order-batch and DB stored function logic → 2) Android/iOS soundboard models → 3) platform integration tests.

• Change STS workflow mode: 1) user settings schema/migration and handlers → 2) STS function route contracts (sts-*) → 3) iOS/Android UI mode selectors and tests → 4) web STS runtime.

11) What to read after this document

• docs/reference/repository-full-deep-reference.md
• docs/reference/repository-operator-manual.md
• docs/contracts/speech-workflow-contract.md
• docs/contracts/native-speech-parity-anchor.md
• docs/ops/* for release-specific gates
• docs/reference/{ios-file-inventory,android-file-inventory,web-file-inventory}.md