SpeakTrue

SpeakTrue Repository: Ultimate Engineering Bible

Last updated: 2026-06-29

This document is the one-stop onboarding and operations reference for this repository for engineers joining the project or taking ownership of a specific feature area.

It is written to answer:

• What each surface (iOS, Android, Web, Backend) does
• What each code surface owns
• What each file path is responsible for
• How to change behavior safely without breaking parity
• Which deployment and verification commands to run

1) Start here before editing anything

1. README.md
2. docs/architecture/overview.md
3. docs/contracts/native-speech-parity-anchor.md
4. docs/contracts/speech-workflow-contract.md
5. The surface inventory for the files you plan to touch:
   • docs/reference/ios-file-inventory.md
   • docs/reference/android-file-inventory.md
   • docs/reference/web-file-inventory.md
6. Backend function behavior map:
   • docs/reference/backend-functions-detailed-map.md
   • docs/reference/backend-functions-deep-dive.md
7. Deployment/runbook checks in docs/ops/* (especially migration and release gates)

If you are changing behavior across surfaces, do not proceed until all relevant inventories and contracts above are open.

2) System map and architectural boundaries

• iOS and Android are thin orchestration/UI clients; provider and policy-sensitive operations are implemented in Supabase edge functions.
• web/marketing is a production-facing static site, not a speech API execution surface.
• web/python-web-app is a legacy/compatibility runtime in transition; it currently bridges older routes through adapter layers and selected compatibility seams.
• backend/supabase/functions is the canonical speech/data action boundary:
  • policy
  • quotas
  • entitlements
  • billing
  • usage
  • media metadata persistence
• backend/supabase/migrations owns schema behavior, storage grants, RPCs, and entitlement/state defaults.

3) Golden docs and source-of-truth files

For any behavioral edit, these files are the canonical sources:

• Repository behavior and conventions: README.md, AGENTS.md, docs/architecture.md (if regenerated), docs/contracts/*, docs/ops/*
• Cross-surface file ownership: docs/reference/ios-file-inventory.md, docs/reference/android-file-inventory.md, docs/reference/web-file-inventory.md
• Backend contract map: docs/reference/backend-functions-detailed-map.md
• Top-level operator guides:
  • docs/reference/repository-full-deep-reference.md
  • docs/reference/repository-onboarding-reference.md
  • docs/reference/repository-operator-manual.md
  • docs/reference/engineer-change-cookbook.md

4) iOS app: complete surface map and edit guidance

4.1 iOS architecture map

• ios/SpeakTrue/SpeakTrueApp.swift / ios/SpeakTrue/ContentView.swift
  • App startup, root composition, auth gate entry.
• ios/SpeakTrue/AuthService.swift, ios/SpeakTrue/AuthState.swift, ios/SpeakTrue/SupabaseClientProvider.swift, ios/SpeakTrue/SupabaseConfig.swift
  • Auth/session contract and client bootstrap.
• ios/SpeakTrue/AIProxyService.swift
  • Unified edge-function call client used by TTS/STT/STS/voice clone/soundboard/settings flows.
• ios/SpeakTrue/CloudStorageService.swift, ios/SpeakTrue/StorageManager.swift
  • Storage-backed persistence + local cache file lifecycle.
• ios/SpeakTrue/SoundboardView.swift, SoundboardViewModel.swift, SoundboardCacheManager.swift, SoundboardCacheIndex.swift
  • Soundboard read, playback entry, ordering, metadata persistence.
• ios/SpeakTrue/TTSViewModel.swift, TextToSpeechView.swift, TTSCatSelectView.swift
  • TTS model, voice/model/category selection, and API request shaping.
• ios/SpeakTrue/STTViewModel.swift, SpeechToTextView.swift
  • Non-live STT request orchestration and transcript state.
• ios/SpeakTrue/STSViewModel.swift, SpeechToSpeechView.swift, RealtimeSTTService.swift, LiveVoiceSTSService.swift, LiveVoiceAudioPlayer.swift
  • Realtime/near-realtime STS session creation, finalize, playback flows.
• ios/SpeakTrue/VoiceCloneViewModel.swift, VoiceCloneTabView.swift
  • Voice-clone request validation and flow.
• ios/SpeakTrue/SettingsView.swift, SettingsTabView.swift, UserSettings.swift, UserSettingsSyncService.swift
  • Settings and persisted user profile/state.
• ios/SpeakTrue/PronunciationGlossaryView.swift, PronunciationGlossaryViewModel.swift
  • Pronunciation dictionary editing and state.
• ios/SpeakTrue/AppTheme.swift, ColorExtension.swift, WaveFormView.swift, AudioControlsView.swift
  • Shared UI tokens, controls, and visual components.
• ios/SpeakTrueTests/*, ios/SpeakTrueUITests/*
  • Unit, contract, and smoke behavior tests.

4.2 iOS config/deploy-sensitive files

• ios/Config/App.Debug.xcconfig
• ios/Config/App.Release.xcconfig
• ios/SpeakTrue.entitlements
• ios/SpeakTrue.xcodeproj/project.pbxproj

4.3 iOS change recipe (minimum required edits)

If you change	Edit at minimum
TTS model/voice defaults, playback mode	ios/SpeakTrue/TTSViewModel.swift, ios/SpeakTrue/TextToSpeechView.swift, ios/SpeakTrue/AIProxyService.swift, plus backend models-list, voices-list, tts-generate if payload changes
STT/STS flow behavior	ios/SpeakTrue/STTViewModel.swift, ios/SpeakTrue/STSViewModel.swift, ios/SpeakTrue/SpeechToSpeechView.swift, RealtimeSTTService.swift, LiveVoiceSTSService.swift, plus backend stt-transcribe, sts-* as needed
Soundboard flow	ios/SpeakTrue/SoundboardViewModel.swift, SoundboardCacheManager.swift, SoundboardCacheIndex.swift, plus backend soundboard-save-generated, soundboard-delete, clip-order-batch
Voice-clone flow	ios/SpeakTrue/VoiceCloneViewModel.swift, AIDataSharingAgreementService.swift, AIDataSharingConsent* files
Settings/consent/quotas	ios/SpeakTrue/UserSettings.swift, UserSettingsSyncService.swift, SettingsView.swift, SettingsTabView.swift

4.4 iOS per-file ownership references

• Use docs/reference/ios-file-inventory.md for a complete file-by-file list with path/category/ownership/behavior summary.
• For build/runtime entry points and app lifecycle, include at least a manual pass through SpeakTrueApp.swift, MainTabView.swift, AuthGateView.swift, StartupLoadingView.swift, and Info.plist before shipping any startup/auth change.

5) Android app: complete surface map and edit guidance

5.1 Android architecture map

• android/app/src/main/java/com/speaktrue/app/SpeakTrueApp.kt, MainActivity.kt
  • App shell, startup graph, DI bootstrap.
• android/app/src/main/java/com/speaktrue/ui/navigation/AppNavGraph.kt
  • Route graph and navigation wiring.
• android/app/src/main/java/com/speaktrue/core/*
  • Config, auth, network, permissions, storage, audio, reliability, and DI foundation.
• android/app/src/main/java/com/speaktrue/features/tts/*
  • TTS screens/state/data for voice generation.
• android/app/src/main/java/com/speaktrue/features/stt/*
  • STT screens/state/data, transcript behavior.
• android/app/src/main/java/com/speaktrue/features/sts/*
  • Realtime and live STS orchestration + finalize behavior.
• android/app/src/main/java/com/speaktrue/features/soundboard/*
  • Soundboard persistence, caches, ordering, and UI.
• android/app/src/main/java/com/speaktrue/features/voiceclone/*
  • Voice-clone request, DTOs, mapping, UI.
• android/app/src/main/java/com/speaktrue/features/settings/*
  • Settings persistence and navigation.
• android/app/src/main/java/com/speaktrue/features/agreement/*
  • AI-data sharing gate and legal flow.
• android/app/src/main/java/com/speaktrue/features/shared/* and ui/theme/*
  • Shared layout primitives, theme, tokens.
• android/app/src/test/java/com/speaktrue/** and android/app/src/androidTest/java/com/speaktrue/**
  • Parity and contract tests.

5.2 Android change recipe

If you change	Edit at minimum
TTS models/voices/presets	features/tts/data/*, features/tts/presentation/TTSViewModel.kt, features/tts/ui/TTSScreen.kt, backend functions voices-list, models-list, tts-generate, style-presets if contract changes
STT/STS flow	features/stt/*, features/sts/*, backend functions stt-transcribe, sts-near-realtime-session, sts-realtime-session, sts-realtime-finalize, sts-live-voice-tts-session
Soundboard reorder / cache	features/soundboard/data/*, features/soundboard/presentation/SoundboardViewModel.kt, features/soundboard/ui/SoundboardScreen.kt and backend soundboard-delete, soundboard-save-generated, clip-order-batch
Settings or agreement change	features/settings/data/*, features/settings/presentation/*, features/settings/ui/*, features/agreement/*, backend user-settings-get, user-settings-update, quota-status if usage semantics changed
Billing/entitlement behavior	billing-sensitive checks in core + feature screens plus backend billing functions

5.3 Android per-file ownership references

• docs/reference/android-file-inventory.md contains the complete file-by-file registry.

5.4 Android build/runtime sensitivity

• android/build.gradle.kts, android/settings.gradle.kts, android/gradle/libs.versions.toml, android/app/build.gradle.kts, and android/gradle.properties all affect build behavior.

6) Web surface map

6.1 Marketing static site (web/marketing)

• web/marketing/index.html: main static marketing surface
• web/marketing/auth/callback/index.html: OAuth callback handoff page
• web/marketing/scripts/*.js: nav/callback waitlist and theme interactions
• web/marketing/styles/*.css: tokenized layout/theme and responsive behavior
• web/marketing/_headers, web/marketing/_redirects, web/marketing/site.webmanifest, deploy-version.json: Cloudflare Pages deployment and cache behavior

Runbook: docs/ops/CLOUDFLARE_PAGES_DEPLOY.md

6.2 Legacy web runtime (web/python-web-app)

• web/python-web-app/wsgi.py, src/app.py, src/config.py, src/legacy_runtime.py, src/legacy_runtime_adapter.py
  • App bootstrap and compatibility seam.
• web/python-web-app/src/routes/*.py
  • Route definitions for legacy/stable web behavior.
• web/python-web-app/src/services/*.py
  • Service orchestration, migration seams, storage provider bridge.
• web/python-web-app/src/storage/*.py and SQL bootstrap files under src/
  • Legacy persistence and storage operations.
• web/python-web-app/tests/** and JS test bundles under web/python-web-app/tests/js
  • Regression and speech compatibility verification.
• Deployment files: web/python-web-app/Dockerfile, Procfile, docker-compose.yml, docker-entrypoint.sh.

6.3 Web change recipe

If you change	Edit at minimum
STT/sts/tts service behavior in web parity surface	web/python-web-app/src/routes/stt.py, src/routes/tts.py, relevant src/services/*, plus compatibility seam docs in src/legacy_runtime_adapter.py and src/services/storage_provider.py
Soundboard behavior	web/python-web-app/src/routes/soundboard.py, src/services/soundboard_service.py, JS audio cards/interaction JS
User settings	web/python-web-app/src/routes/settings.py, src/services/user_settings_service.py, templates and JS that renders user state
Waitlist/onboarding entrypoints	web/python-web-app/src/routes/voice_clone.py, src/routes/tts.py, src/services/ compatibility seam, web/marketing form scripts

6.4 Web per-file ownership references

• docs/reference/web-file-inventory.md contains the complete file registry for all web runtime and marketing artifacts.

7) Backend + SQL + migrations: what each function and migration layer does

7.1 Edge function map (critical)

Route	Surface	Files	What it does
/account-delete	auth/account lifecycle	backend/supabase/functions/account-delete/*	Deletes user account and server-owned resources using auth-gated contract checks.
/billing-apple-sync	billing	billing-apple-sync/*	Sync Apple transactions into entitlement state transitions.
/billing-apple-notifications	billing	billing-apple-notifications/*	Processes webhook payloads and applies entitlement mutation policy.
/billing-google-play-sync	billing	billing-google-play-sync/*	Validates Play payloads and applies entitlement state updates.
/billing-stripe-webhook	billing	billing-stripe-webhook/*	Stripe signature validation + event dispatch + persistence + policy mapping.
/bug-report-submit	support	bug-report-submit/*	Records bug reports.
/byok-resolve, /byok-upsert	settings/provider security	byok-*/*	BYOK config query and write APIs.
/clip-order-batch	soundboard	clip-order-batch/*	Applies batch ordering changes with ownership checks.
/language-recommend	STT/STS	language-recommend/*	Suggests/returns language recommendation payload.
/models-list	TTS	models-list/*	Model catalog with policy filtering.
/voices-list	TTS	voices-list/*	Voice catalog with entitlement/private access filtering.
/pronunciation-dictionary	generation quality	pronunciation-dictionary/*	Pronunciation CRUD + validation.
/quota-status	usage gating	quota-status/*	Returns quota and usage state used by clients.
/soundboard-save-generated	soundboard	soundboard-save-generated/*	Persists generated clip metadata, bucket/key mapping, idempotence behavior.
/soundboard-delete	soundboard	soundboard-delete/*	Deletes one or more soundboard clips with storage cleanup semantics.
/soundboard-clip-ingest	migration placeholder	directory scaffold	Not yet implemented (routing should remain guarded until handler exists).
/stt-transcribe	STT	stt-transcribe/*	Non-streaming transcribe request validation + capture + provider call + response normalization.
/sts-live-voice-tts-session	STS	sts-live-voice-tts-session/*	Starts live STS voice-to-speech session contract.
/sts-near-realtime-session	STS	sts-near-realtime-session/*	Boots near-realtime STS session context for finalization.
/sts-realtime-session	STS	sts-realtime-session/*	Starts active real-time STS session and returns provider contract.
/sts-realtime-finalize	STS	sts-realtime-finalize/*	Merges transcript/artifacts, finalizes metadata and artifact contract.
/sts-live-interpreter-session	live interpreter scaffold	index.ts only	Scaffold function only.
/sts-live-interpreter-tts-session	live interpreter scaffold	index.ts only	Scaffold function only.
/style-presets	settings	style-presets/*	Read/update style preset data and defaults.
/tts-generate	TTS	tts-generate/*	Core TTS validation, policy, pronunciation, provider invocation, response contract.
/user-settings-get	settings	user-settings-get/*	Fetches settings with migration-safe defaults.
/user-settings-update	settings	user-settings-update/*	Patch-update settings with validation and normalized response.
/voice-clone-preflight	voice clone	voice-clone-preflight/*	Readiness and validation pass before clone creation.
/voice-clone-create	voice clone	voice-clone-create/*	Create clone, apply provider call, persist metadata, return result.
/voice-clone-delete	voice clone	voice-clone-delete/*	Delete user clone and provider references.
/waitlist-signup	marketing ops	waitlist-signup/*	Stores waitlist contacts and deduplicates identity keys.

7.2 Shared backend helper modules to inspect for almost any backend edit

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

7.3 Backend migration inventory overview

backend/supabase/migrations includes schema/core setup through production-alignment updates:

• 001_* through 031_*: base schema, entitlement/usage/billing foundations, byok, voice clone, soundboard ordering, waitlist, quotas, data-sharing agreement, etc.
• timestamp-prefixed (2026*) files: hardened entitlement behavior, speech mode expansions, quotas, storage grants/paths, STS/STT workflow migrations, soft-delete and restore operations, live interpreter scaffolding.

When schema shape changes, always create/modify migration SQL and keep function contract tests and client callsite payload tests in sync.

8) Feature change matrix (what to edit across surfaces)

8.1 TTS / Voices / Models

• Backend: tts-generate, voices-list, models-list, style-presets, _shared policy modules
• iOS: AIProxyService, TTSViewModel, TextToSpeechView, TTSCatSelectView, VoiceModelSelectionView
• Android: features/tts/*, Feature/voice/model repositories
• Web: web/python-web-app/src/routes/tts.py, src/services/tts_service.py, related JS entrypoints if any
• Tests: backend handler tests, ios/SpeakTrueTests/TTSPlaybackModeBehaviorTests.swift, Android TTS contract tests

8.2 STT / STS

• Backend: stt-transcribe, sts-near-realtime-session, sts-realtime-session, sts-live-voice-tts-session, sts-realtime-finalize, _shared/quotas.ts, _shared/usage.ts
• iOS: STTViewModel, STSViewModel, SpeechToSpeechView, LiveVoiceSTSService, RealtimeSTTService
• Android: features/stt/*, features/sts/*, STSOrchestrator
• Web: web/python-web-app/src/routes/stt.py, web/python-web-app/static/js/index_stt.js, index_sts_live_voice.js
• Tests: backend STT/STS tests, Android/iOS STS parity tests

8.3 Soundboard

• Backend: soundboard-save-generated, soundboard-delete, clip-order-batch, soundboard-clip-ingest (if activated)
• iOS: SoundboardViewModel, SoundboardCacheManager, SoundboardCacheIndex, AIProxyService
• Android: features/soundboard/data/*, features/soundboard/presentation/SoundboardViewModel.kt
• Web: web/python-web-app/src/routes/soundboard.py, src/services/soundboard_service.py
• Tests: backend function tests + platform soundboard contract tests

8.4 Voice clone

• Backend: voice-clone-preflight, voice-clone-create, voice-clone-delete, byok-resolve, byok-upsert
• iOS: VoiceCloneTabView, VoiceCloneViewModel, agreement gate files
• Android: features/voiceclone/data/*, features/voiceclone/presentation/*, features/voiceclone/ui/*
• Web: web/python-web-app/src/routes/voice_clone.py, src/services/voice_clone_service.py

8.5 Settings, quotas, agreements

• Backend: user-settings-get, user-settings-update, quota-status, byok-*, pronunciation and language recommendation as needed
• iOS: UserSettings, UserSettingsSyncService, Settings* screens, agreement files
• Android: features/settings/*, features/agreement/*
• Web: web/python-web-app/src/routes/settings.py, src/services/user_settings_service.py

8.6 Billing / entitlements

• Backend: billing-apple-notifications, billing-apple-sync, billing-google-play-sync, billing-stripe-webhook, _shared/subscription-gating-config.ts, _shared/entitlements.ts, _shared/billing-entitlement-policy.ts
• Mobile and web: usage-gated UI, entitlements checks, feature visibility
• Migrations: entitlement/policy SQL and grants where behavior changes

9) Deployment and verification map

9.1 Backend gates

• bash scripts/coverage_backend_contracts.sh
• bash scripts/regression_migration_paths.sh
• Backend function tests in touched directories (.deno tests)

9.2 Android gates

• ./gradlew -p android :app:compileDebugKotlin
• ./gradlew -p android :app:testDebugUnitTest
• ./gradlew -p android :app:lintDebug
• ./gradlew -p android :app:bundleRelease (release path)
• Use docs/ops/ANDROID_PLAY_RELEASE_CHECKLIST.md before production submission

9.3 iOS gates

• Xcode build + local smoke for changed surfaces
• Confirm config in ios/Config/App*.xcconfig
• Re-verify entitlements and plist for capability-sensitive changes

9.4 Web gates

• Marketing: validate HTML/CSS/JS behavior, then deploy via Cloudflare Pages path and checklist
• Legacy runtime: python3 -m pytest web/python-web-app/tests and smoke run of app entrypoint; see web/python-web-app/pytest.ini and run_regression_gate.sh

10) Incident and support operations

When an engineer receives a behavior regression report, this is the quickest triage sequence:

1. Identify surface from report (iOS/Android/Web/Backend).
2. Identify changed API/function in backend map or route in web runtime.
3. Check matching function handler and tests.
4. Check corresponding caller files in iOS/Android inventory row.
5. Confirm if migration touched and compare to backend/supabase/migrations and migration docs in docs/ops/MIGRATION_REGRESSION_GATES.md.
6. Re-run focused local gate(s) before root-cause changes.

11) One-line command matrix (quick reference)

• rg --files ios → iOS file inventory check.
• rg --files android/app/src/main/java → Android entrypoints and feature modules.
• rg --files web/python-web-app/src → legacy web route/service list.
• find backend/supabase/functions -maxdepth 2 -type d | sort → function directories.
• bash scripts/regression_migration_paths.sh → migration-sensitive backend + parity smoke gate.
• git status --short before/after docs edits to keep the repository diff clean.

12) Canonical references

Use this as your canonical map index:

• 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
• docs/reference/repository-extremely-detailed-engineer-guide.md
• docs/reference/repository-full-deep-reference.md
• docs/reference/repository-onboarding-reference.md
• docs/reference/repository-operator-manual.md
• docs/reference/engineer-change-cookbook.md