SpeakTrue

SpeakTrue Repository — Extreme Engineering Guide

Last updated: 2026-06-29

This is the single-entry onboarding and reference guide for first-time engineers joining the SpeakTrue monorepo.

1) Purpose and who this is for

• First-pass reading for new contributors to understand the entire app behavior and boundaries.
• Practical reference for cross-surface changes (iOS ↔ Android ↔ Web ↔ Supabase backend).
• Deployment/runbook map for local, CI, and release workflows.
• Point of truth for where to edit and what checks to run when changing a behavior.

2) Repository-level orientation

Root surfaces

• ios/ — native iOS SwiftUI app.
• android/ — native Android app (Jetpack Compose).
• web/ — legacy Python web runtime + marketing web assets.
• backend/supabase/ — Supabase edge functions + SQL migrations + tests.
• .github/workflows/ — CI/CD and deployment workflows.
• scripts/ — contract/ smoke/regression verification helpers.
• docs/ — architecture, ops, contracts, and onboarding references.

3) First things to read before changing anything

1. README.md
2. docs/index.md
3. docs/reference/repository-onboarding-reference.md
4. docs/reference/repository-full-deep-reference.md
5. docs/contracts/native-speech-parity-anchor.md
6. docs/contracts/speech-workflow-contract.md
7. docs/ops/MIGRATION_REGRESSION_GATES.md
8. backend/supabase/functions handler tests for the function you are touching
9. Surface-specific tests for the client feature you are touching

3.1 Canonical exhaustive per-file inventories

• docs/reference/ios-file-inventory.md
• docs/reference/android-file-inventory.md
• docs/reference/web-file-inventory.md
• docs/reference/backend-functions-detailed-map.md
• docs/reference/backend-functions-deep-dive.md

The first three files provide per-file inventories for UI and web surfaces. The backend maps are the source of truth when editing function contracts.

Those files contain file-by-file ownership and are the canonical “every file in a directory” map for the UI surfaces. Use this guide for architecture and behavior context, and those inventories (plus the backend function maps) when you need direct per-file confirmation.

4) Core architecture and boundaries

4.1 Runtime architecture

• All privileged speech/audio operations are executed through server boundaries.
• Client surfaces are thin orchestration + rendering layers.
• Shared source of truth and contracts are maintained in:
  • backend/supabase/functions/_shared/*
  • docs/contracts/*
  • migration + RPC definitions under backend/supabase/migrations/*

4.2 Surface ownership

• iOS owns real-time UX interaction patterns and local playback/storage fallback paths.
• Android owns mirrored feature contracts, test-backed parity checks, and parity-focused screen/tests.
• Legacy web runtime currently serves compatibility routes and migration seams while core app flow converges to edge contracts.
• Marketing web remains a standalone static marketing surface.

4.3 Contract discipline

• For each server call path from client, map
  1. Client entrypoint file
  2. Edge function name (backend/supabase/functions/<name>/)
  3. Optional edge shared helper modules
  4. SQL/RPC/migration dependencies
• Keep this mapping up to date before changing API fields, payloads, or persisted schemas.

5) iOS detailed reference (ios/)

5.1 App lifecycle and bootstrapping

• ios/SpeakTrue/SpeakTrueApp.swift — application composition root; service injection and startup orchestration.
• ios/SpeakTrue/Info.plist — Info.plist-level config and auth/deep-link declarations.
• ios/SpeakTrue/SupabaseConfig.swift — Supabase runtime configuration constants/keys.
• ios/SpeakTrue/AuthGateView.swift — auth gate UI and flow control.
• ios/SpeakTrue/AuthService.swift / ios/SpeakTrue/AuthState.swift — session/login/auth state management.
• ios/SpeakTrue/SupabaseClientProvider.swift / ios/SpeakTrue/UserSettingsSyncService.swift / ios/SpeakTrue/CloudStorageService.swift / ios/SpeakTrue/StorageManager.swift — session-bound backend, cloud, and sync services.
• ios/SpeakTrue/StartupLoadingView.swift — initial loading UX while bootstrapping services.

5.2 Core voice generation workflows (TTS, STT, STS)

• TTS entry/model/UI
  • ios/SpeakTrue/TextToSpeechView.swift
  • ios/SpeakTrue/TTSViewModel.swift
  • ios/SpeakTrue/HeaderViewTTS.swift
  • ios/SpeakTrue/GenerateButtonView.swift
  • ios/SpeakTrue/TTSCatSelectView.swift
  • ios/SpeakTrue/AIProxyService.swift — API adapter into backend speech function contracts.
• STT / STS screens and viewmodels
  • ios/SpeakTrue/SpeechToTextView.swift
  • ios/SpeakTrue/STTViewModel.swift
  • ios/SpeakTrue/STSViewModel.swift
  • ios/SpeakTrue/HeaderViewSTT.swift
  • ios/SpeakTrue/SpeechToSpeechView.swift
• STT/STS services
  • ios/SpeakTrue/RealtimeSTTService.swift
  • ios/SpeakTrue/LiveVoiceSTSService.swift
  • ios/SpeakTrue/LiveVoiceAudioPlayer.swift
  • ios/SpeakTrue/ElevenLabsSTTService.swift
  • ios/SpeakTrue/ElevenLabsService.swift
• Shared controls used by voice features
  • ios/SpeakTrue/WaveFormView.swift
  • ios/SpeakTrue/AudioControlsView.swift
  • ios/SpeakTrue/ResetButtonView.swift

5.3 Soundboard

• Feature entry and rendering
  • ios/SpeakTrue/SoundboardView.swift
  • ios/SpeakTrue/SoundboardCategories.swift
  • ios/SpeakTrue/SBCategoryDetailView.swift
  • ios/SpeakTrue/SoundboardAudioClips.swift
• soundboard models/services
  • ios/SpeakTrue/SoundboardCacheIndex.swift
  • ios/SpeakTrue/SoundboardCacheManager.swift
  • ios/SpeakTrue/SoundboardCacheManager.swift (runtime cache behavior and local index integrity)
  • ios/SpeakTrue/StorageTestView.swift (manual verification helper)

5.4 Voice clone and agreement

• ios/SpeakTrue/VoiceCloneTabView.swift
• ios/SpeakTrue/VoiceCloneViewModel.swift
• ios/SpeakTrue/VoiceModelSelectionView.swift
• ios/SpeakTrue/AIDataSharingAgreementService.swift
• ios/SpeakTrue/AIDataSharingConsent.swift
• ios/SpeakTrue/AIDataSharingConsentGateView.swift
• ios/SpeakTrue/AIDataSharingAgreementService.swift and related consent gate logic should be updated together when legal/data-sharing flow changes.

5.5 Settings and personalization

• Settings surface: ios/SpeakTrue/SettingsTabView.swift, ios/SpeakTrue/SettingsView.swift, ios/SpeakTrue/SettingsModels.swift.
• User preference storage/persistence: ios/SpeakTrue/UserSettings.swift, ios/SpeakTrue/UserSettingsSyncService.swift.
• Shared navigation/settings model state: ios/SpeakTrue/MainTabView.swift, ios/SpeakTrue/ContentView.swift.

5.6 Audio services and playback

• ios/SpeakTrue/AudioRecorderService.swift — recording orchestration.
• ios/SpeakTrue/AudioPlayerService.swift — audio playback service.
• ios/SpeakTrue/LiveVoiceAudioPlayer.swift — streaming/interpreter playback utility.
• ios/SpeakTrue/BreakManager.swift — break/segment handling for playback sessions.
• ios/SpeakTrue/ShareSheet.swift — export/share hooks.

5.7 Diagnostics, theme, utility, and shared models

• ios/SpeakTrue/AppTheme.swift, ios/SpeakTrue/ColorExtension.swift
• ios/SpeakTrue/CategoryInfo.swift, ios/SpeakTrue/SettingsModels.swift
• ios/SpeakTrue/DebugLogger.swift (gated debug logging behavior)
• ios/SpeakTrue/AsyncTimeout.swift
• ios/SpeakTrue/AuthState.swift
• ios/SpeakTrue/PronunciationGlossaryView.swift
• ios/SpeakTrue/PronunciationGlossaryViewModel.swift
• ios/SpeakTrue/AppTour.swift and onboarding prompts.
• ios/SpeakTrue/HeaderViewTTS.swift, ios/SpeakTrue/HeaderViewSTT.swift, ios/SpeakTrue/TextInputView.swift.

5.8 App configuration and entitlements

• ios/SpeakTrue/Info.plist and ios/SpeakTrue/SpeakTrue.entitlements are required for auth, permissions, and app service contracts.
• Assets: ios/SpeakTrue/Assets.xcassets/**, ios/SpeakTrue/Preview Assets.xcassets/**.

5.9 iOS tests

• ios/SpeakTrueTests/* — unit and contract tests.
• ios/SpeakTrueUITests/* — UI smoke/navigational tests.

6) Android detailed reference (android/)

6.1 Project and app shell

• android/app/src/main/java/com/speaktrue/app/SpeakTrueApp.kt
• android/app/src/main/java/com/speaktrue/app/MainActivity.kt
• android/app/src/main/AndroidManifest.xml

6.2 Core architecture modules

• Auth
  • android/app/src/main/java/com/speaktrue/core/auth/*.kt
  • android/app/src/main/java/com/speaktrue/features/auth/**/*
• Network/runtime
  • android/app/src/main/java/com/speaktrue/core/network/*.kt
  • android/app/src/main/java/com/speaktrue/core/config/RuntimeConfig.kt
  • android/app/src/main/java/com/speaktrue/core/supabase/SupabaseModule.kt
  • android/app/src/main/java/com/speaktrue/core/storage/*.kt
  • android/app/src/main/java/com/speaktrue/core/di/*.kt
  • android/app/src/main/java/com/speaktrue/core/reliability/*.kt
• Permissions
  • android/app/src/main/java/com/speaktrue/core/permissions/*.kt
  • android/app/src/main/java/com/speaktrue/core/permissions/ui/*.kt

6.3 Feature groups

• Speech generation
  • features/tts/ui/TTSScreen.kt
  • features/tts/presentation/TTSViewModel.kt
  • features/tts/data/*.kt
• STT
  • features/stt/ui/STTScreen.kt
  • features/stt/presentation/STTViewModel.kt
  • features/stt/data/*.kt
• STS (Streaming TTS/RT path)
  • features/sts/ui/STSScreen.kt
  • features/sts/presentation/STSViewModel.kt
  • features/sts/data/*.kt
  • features/sts/data/STSOrchestrator.kt
• Soundboard
  • features/soundboard/ui/SoundboardScreen.kt
  • features/soundboard/ui/SoundboardComponents.kt
  • features/soundboard/presentation/SoundboardViewModel.kt
  • features/soundboard/data/*.kt
• Voice cloning
  • features/voiceclone/ui/VoiceCloneScreen.kt
  • features/voiceclone/ui/VoiceCloneComponents.kt
  • features/voiceclone/presentation/VoiceCloneViewModel.kt
  • features/voiceclone/presentation/VoiceCloneState.kt
  • features/voiceclone/data/*.kt
• Presets
  • features/presets/ui/StylePresetScreen.kt
  • features/presets/presentation/StylePresetViewModel.kt
  • features/presets/data/StylePresetRepository.kt
• Settings and agreements
  • features/settings/ui/SettingsScreen.kt, features/settings/ui/SettingsSections.kt, features/settings/ui/SoundboardSettingsSection.kt
  • features/settings/presentation/SettingsViewModel.kt
  • features/settings/data/*.kt
• Shared language/quality features
  • features/language/data/*.kt
  • features/dictionary/ui/PronunciationDictionaryScreen.kt
  • features/dictionary/presentation/PronunciationDictionaryViewModel.kt
  • features/dictionary/data/PronunciationRepository.kt
• Agreement gate
  • features/agreement/ui/AIDataSharingAgreementGate.kt
  • features/agreement/presentation/AIDataSharingAgreementViewModel.kt
  • features/agreement/data/AIDataSharingAgreementRepository.kt
• App tour
  • features/tutorial/AppTour.kt
  • features/tutorial/AppTourContractsTest.kt

6.4 Shared UI and navigation

• android/app/src/main/java/com/speaktrue/ui/navigation/AppNavGraph.kt
• android/app/src/main/java/com/speaktrue/features/shared/*.kt
• android/app/src/main/java/com/speaktrue/ui/theme/*.kt
• android/app/src/main/res/values/**, android/app/src/main/res/drawable/**, android/app/src/main/res/mipmap-*/**

6.5 Audio and runtime services

• android/app/src/main/java/com/speaktrue/core/audio/*.kt
• android/app/src/main/java/com/speaktrue/core/network/OriginSecurity.kt
• android/app/src/main/java/com/speaktrue/core/text/ (if added in future)

6.6 Android tests

• Unit tests in android/app/src/test/java/com/speaktrue/**
• Instrumented tests in android/app/src/androidTest/java/com/speaktrue/**
• Contract parity tests under .../contracts/*

7) Web detailed reference (web/)

7.1 Marketing site (production/static)

• web/marketing/index.html — main marketing SPA shell.
• web/marketing/scripts/main.js, web/marketing/scripts/waitlist.js, web/marketing/scripts/theme_boot.js, web/marketing/scripts/deploy_refresh.js
• web/marketing/styles/main.css, web/marketing/styles/tokens.css
• web/marketing/auth/callback/index.html — OAuth callback route handling.
• web/marketing/_headers, _redirects, web/marketing/site.webmanifest
• web/marketing/assets/** — icons/screenshots/asset bundle.

7.2 Legacy Python runtime (compatibility and migration boundary)

• web/python-web-app/src/app.py — Flask application entry + blueprint registration.
• web/python-web-app/src/legacy_runtime.py — staged compatibility bridge for legacy runtime behavior.
• web/python-web-app/wsgi.py and web/python-web-app/Procfile — deployment entrypoints.
• web/python-web-app/src/config.py — environment-driven config loading.
• web/python-web-app/src/routes/*.py — HTTP route handlers for health, legacy features, settings, soundboard, stt, tts, voice_clone.
• web/python-web-app/src/services/*.py — cross-service orchestration for auth, jobs, clips, categories, cache, API keys.
• web/python-web-app/src/storage/*.py (if present via runtime package usage) and migration helpers.
• web/python-web-app/src/jobs/*.py — async/background jobs path for queued tasks.
• SQL bootstrap helpers used by legacy runtime: web/python-web-app/src/create_*.sql, src/db_table_names.py

7.3 Environment and deployment assets

• Docker: web/python-web-app/Dockerfile, web/python-web-app/docker-compose.yml, web/python-web-app/docker-entrypoint.sh
• Environment examples: web/python-web-app/.env.example
• Docs: web/python-web-app/README.md, README_CONTEXT.md, docs/*.md.

7.4 Web tests and validation

• Python tests under web/python-web-app/tests/**
• API coverage and migration parity tests include references in web/python-web-app/run_regression_gate.sh and related CI integration.

8) Backend functions and data layer (backend/supabase/)

8.1 Edge function map

Function	Location	Responsibility	Primary client surfaces	Notes
account-delete	backend/supabase/functions/account-delete/index.ts	user account teardown orchestration	iOS, Android, future API callers	includes handler and tests
billing-apple-notifications	.../billing-apple-notifications	Apple receipt/notification intake, webhook handling	backend-only, iOS billing sync bridge	has explicit deno.json
billing-apple-sync	.../billing-apple-sync	Apple sync orchestration logic/state transitions	iOS billing path	check entitlement transitions
billing-google-play-sync	.../billing-google-play-sync	Google Play purchase sync and verifier wrapper	Android billing	includes verifier test and handler
billing-stripe-webhook	.../billing-stripe-webhook	Stripe webhook processing + persistence	backend-only billing connector	multi-stage validation/persistence logic
bug-report-submit	.../bug-report-submit	capture/report bug payloads	app surfaces as support path	lightweight support ingestion
byok-resolve	.../byok-resolve	map BYOK credentials for private voice access	edge auth/billing gating + service path
byok-upsert	.../byok-upsert	write/update BYOK credential records	settings/admin surface
clip-order-batch	.../clip-order-batch	batch reorder/ordering RPC contract	soundboard reorder flows	includes dedicated tests
language-recommend	.../language-recommend	suggest or resolve TTS language behavior	TTS/STS language selection
quota-status	.../quota-status	returns usage/quota status snapshot	TTS/STT/STS gating UX
soundboard-delete	.../soundboard-delete	delete soundboard assets with storage/metadata handling	soundboard feature
soundboard-save-generated	.../soundboard-save-generated	persist generated clip metadata + storage pointers	generated clip pipeline
stt-transcribe	.../stt-transcribe	non-streaming STT path and validation hooks	STT feature
sts-near-realtime-session	.../sts-near-realtime-session	near-real-time session lifecycle
sts-live-interpreter-session	.../sts-live-interpreter-session	live interpreter session control
sts-live-interpreter-tts-session	.../sts-live-interpreter-tts-session	TTS leg handling in interpreter mode
sts-live-voice-tts-session	.../sts-live-voice-tts-session	voice model-driven live TTS session
sts-realtime-session	.../sts-realtime-session	main realtime STS session creation and status
sts-realtime-finalize	.../sts-realtime-finalize	finalize realtime transcripts/artifacts
style-presets	.../style-presets	read/update style preset contract
tts-generate	.../tts-generate	request validation + provider call + output metadata
user-settings-get	.../user-settings-get	fetch settings profile
user-settings-update	.../user-settings-update	persist settings updates
voices-list	.../voices-list	provider voice listing + filtering
voice-clone-preflight	.../voice-clone-preflight	validate preflight for voice clone requests
voice-clone-create	.../voice-clone-create	create voice-clone entities
voice-clone-delete	.../voice-clone-delete	delete voice clone records
models-list	.../models-list	provider model listing
waitlist-signup	.../waitlist-signup	marketing/web signup intake
pronunciation-dictionary	.../pronunciation-dictionary	dictionary lookup/update pipeline

8.2 Shared backend helpers

• backend/supabase/functions/_shared/cors.ts
• backend/supabase/functions/_shared/auth-context.ts
• backend/supabase/functions/_shared/types.ts
• backend/supabase/functions/_shared/billing-entitlement-policy.ts
• backend/supabase/functions/_shared/byok.ts
• backend/supabase/functions/_shared/private-voice-access.ts
• backend/supabase/functions/_shared/entitlements.ts
• backend/supabase/functions/_shared/theme.ts
• backend/supabase/functions/_shared/quotas.ts
• backend/supabase/functions/_shared/usage.ts
• backend/supabase/functions/_shared/subscription-gating-config.ts

Every function should consume this layer first for shared auth / gating and avoid duplicating policy checks.

8.3 Database migration inventory (backend/supabase/migrations/)

• 001_core_schema.sql through numbered historical migrations (001..031) define base schema, billing, entitlements, and storage defaults.
• Date-prefixed migrations (202603... to 202606...) are more recent production-alignment changes: auth trigger repair, quota policy hardening, STS/STT mode expansions, soundboard soft-delete migration cleanup, storage grants, workflow settings.
• Relevant clusters:
  • Billing and entitlement: 011_*, 012_*, 013_*, 016_*, 019_*, 020_*, 022_*, 026_*, 027_* and 2026 date-stamped entitlement/role adjustments.
  • Soundboard lifecycle: 004_*, 006_*, 028_*, 029_*, date-prefixed soundboard patch sets in May/June 2026.
  • STS features and modes: 023_*, 024_*, and 2026-06-23/2026-06-27 STS/near-realtime migrations.
  • Voice/style settings: pronunciation and dictionary migrations (021, 024, 024_ai?, 015, 030, 018).
  • Access/storage grants and hardening: 007_*, 002, 005, 008, date-prefixed grant updates.

8.4 Backend test surface

• Function tests are near each function in backend/supabase/functions/<fn>/*_test.ts.
• Shared helper behavior tests in backend/supabase/functions/_shared/*_test.ts.
• Python migration and API-grant smoke tests in backend/supabase/tests/*.

9) Deployment and release matrix

9.1 iOS

• Build and run from Xcode using the current workspace/project.
• For parity and release checks, inspect docs/ops/ checklists and Android parity contracts for cross-surface behavior.
• Entitlement/billing/version changes should always be cross-reviewed in:
  • ios/SpeakTrue/ billing/supabase config files
  • backend/supabase entitlement-related migrations/functions
  • Android migration and contract tests.

9.2 Android

• ./gradlew based project under android/.
• Release/deployment runbook for Play is in:
  • android/SpeakTrueAndroid/app/build.gradle.kts
  • docs/ops/ANDROID_PLAY_RELEASE_CHECKLIST.md
  • scripts/verify_android_play_release_blockers.py

9.3 Backend

• Local function and migration checks rely on scripts under:
  • scripts/coverage_backend_contracts.sh
  • scripts/regression_migration_paths.sh
• Supabase deployment is governed by project configuration in backend/supabase/config.toml and function code.
• For any schema-affecting change, align:
  • function behavior tests
  • migration script updates
  • relevant docs/contract files

9.4 Marketing and legacy web

• Marketing deployment and asset updates: docs/ops/CLOUDFLARE_PAGES_DEPLOY.md.
• Legacy web runtime (if changed): web/python-web-app/Dockerfile, requirements*.txt, src/app.py, wsgi.py.

10) Change recipes: “where to edit X”

10.1 Add/update a TTS voice provider

• iOS: ios/SpeakTrue/AIProxyService.swift, ios/SpeakTrue/AIData* components as needed.
• Android: features/language/*, features/tts/data/VoiceCatalogRepository.kt, features/tts/data/ModelCatalogRepository.kt.
• Backend: backend/supabase/functions/voices-list/, backend/supabase/functions/models-list/, optional tts-generate/policy.ts and style-presets defaults.
• Contract/docs: docs/contracts/speech-workflow-contract.md if request/response shape changes.

10.2 Change STS stream behavior

• iOS: LiveVoiceSTSService.swift, STSViewModel.swift, RealtimeSTTService.swift.
• Android: features/sts/data/*, features/sts/presentation/STSViewModel.kt, core/audio/*.kt.
• Backend: sts-live-*, sts-realtime-session, sts-realtime-finalize, shared entitlement/usage helpers.
• Re-run contracts and near-real-time specific tests, plus both platform parity checks.

10.3 Add/modify soundboard category/clip ordering behavior

• iOS: SoundboardCacheManager.swift, SoundboardCacheIndex.swift, SBCategoryDetailView.swift.
• Android: features/soundboard/data/SoundboardRepository.kt, SoundboardAudioCacheManager.kt, reorder mapping tests.
• Backend: clip-order-batch and related soundboard SQL functions/migrations.
• Verify with soundboard contract tests and migration rollback checks.

10.4 Change voice-clone path

• iOS: VoiceClone*, AIDataSharing*.
• Android: features/voiceclone/*.
• Backend: voice-clone-preflight, voice-clone-create, voice-clone-delete, optional BYOK/auth policy helpers.
• Ensure legal/consent copy and defaults are kept in sync with app settings screens.

10.5 User setting default changes

• iOS: UserSettings.swift, UserSettingsSyncService.swift, SettingsModels.swift, settings screens.
• Android: features/settings/data/SettingsStore.kt, SettingsRepository.kt, SettingsViewModel.kt.
• Backend: user-settings-get, user-settings-update, supporting SQL defaults + migrations.

11) Observability and troubleshooting map

11.1 Runtime triage first principles

1. Confirm which surface calls the target function or local service.
2. Confirm auth context and user entitlement path.
3. Confirm payload shape at client call site and backend validation.
4. Confirm DB migration state and function contract version.
5. Confirm app UI state management for failure path (loading/error state).

11.2 Useful checkpoints

• iOS: logs via DebugLogger plus obvious published state transitions.
• Android: state and UI tests in the relevant feature module + contract tests.
• Backend: function-specific test module and shared policy tests.
• Migration/regression checks via scripts in docs/ops/ and scripts/.

12) Mandatory documentation cross-links

• App onboarding baseline: docs/reference/repository-onboarding-reference.md
• Deep implementation map: docs/reference/repository-full-deep-reference.md
• Operator workflow: docs/reference/repository-operator-manual.md
• Platform parity: docs/contracts/native-speech-parity-anchor.md
• Migration and release gate docs: docs/ops/*
• Backend function testing and contract docs: docs/contracts/*

13) Change discipline and governance

• If changing behavior: edit surface + function + migration + contract docs in the same pass.
• If changing persisted payload: update:
  • mobile models/view models,
  • edge validation/parsing,
  • SQL migration or storage format,
  • contract docs and operator checklists.
• Prefer explicit and named tests near the changed file.
• If you need an explicit “what files to edit” workplan for each change type, use:
  • Engineer Change Cookbook

14) What to do next after this doc

• Use this as the default first stop for any change request.
• For concrete implementation questions, open the linked function-specific section and then update:
  • the relevant feature layer,
  • backend contract,
  • parity/runnable checks,
  • and docs.
• For release work, complete docs + contracts first, then implementation, then CI verification.