SpeakTrue

SpeakTrue Engineer Change Cookbook (Single-Source for First-Contact Edits)

Last updated: 2026-06-29

Use this file when you need to do real work quickly without re-deriving the blast radius. If this guide says “edit here,” treat it as a mandatory minimum set unless your specific change is isolated to one file.

1) Golden edit sequence (always start here)

For every change:

1. Open the relevant section in:
   • docs/reference/repository-extremely-detailed-engineer-guide.md
   • docs/reference/repository-full-deep-reference.md
   • docs/reference/repository-operator-manual.md
2. Confirm current contract/docs state in:
   • docs/contracts/native-speech-parity-anchor.md
   • docs/contracts/speech-workflow-contract.md
3. Make code change + caller updates.
4. Update/extend tests adjacent to the touched feature.
5. Run the smallest valid command sequence for that surface.
6. Update affected docs in docs/reference or docs/contracts if behavior or contract changed.

2) Source-of-truth file maps (required reading before editing)

• iOS files and ownership:
  • docs/reference/ios-file-inventory.md
• Android files and ownership:
  • docs/reference/android-file-inventory.md
• Web files and ownership:
  • docs/reference/web-file-inventory.md
• Backend contracts:
  • docs/reference/backend-functions-deep-dive.md
  • docs/reference/backend-functions-detailed-map.md

These inventories are the authoritative per-file maps for this repo.

3) Deployment gates (what to run by area)

• iOS changes:
  • App build + feature smoke checks in Xcode.
  • Related parity and contract tests in ios/SpeakTrueTests.
• Android changes:
  • ./gradlew -p android :app:compileDebugKotlin
  • ./gradlew -p android :app:testDebugUnitTest
  • ./gradlew -p android :app:lintDebug
  • ./gradlew -p android :app:bundleRelease when preparing release.
• Backend contract changes:
  • function tests for touched directory
  • bash scripts/coverage_backend_contracts.sh
  • bash scripts/regression_migration_paths.sh
  • local function serve smoke.
• Legacy web changes:
  • python3 -m pytest web/python-web-app/tests
  • web/python-web-app/venv/bin/gunicorn --chdir web/python-web-app --bind 127.0.0.1:5055 wsgi:app
• Marketing/static changes:
  • verify through web/marketing render path (waitlist + OAuth callback flows) and deploy via Cloudflare Pages checklist.

4) Feature-level change matrix

Use this as your first edit map for common “I need to change X” tasks.

4.1 Text-to-Speech (voices/models/style presets)

• Primary backends:
  • backend/supabase/functions/voices-list
  • backend/supabase/functions/models-list
  • backend/supabase/functions/tts-generate
  • backend/supabase/functions/style-presets
• iOS:
  • ios/SpeakTrue/TTSViewModel.swift
  • ios/SpeakTrue/TextToSpeechView.swift
  • ios/SpeakTrue/AIProxyService.swift
  • ios/SpeakTrue/TTSCatSelectView.swift
  • ios/SpeakTrue/VoiceModelSelectionView.swift
• Android:
  • 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
• Web:
  • web/python-web-app/src/services/tts_service.py
  • web/python-web-app/src/services/speech_service.py
  • web/python-web-app/src/routes/tts.py
• Tests:
  • backend function tests, iOS TTS tests, Android contract tests.

4.2 STT and transcription workflows

• Primary backends:
  • backend/supabase/functions/stt-transcribe
  • backend/supabase/functions/sts-realtime-session
  • backend/supabase/functions/sts-near-realtime-session
  • backend/supabase/functions/sts-realtime-finalize
  • backend/supabase/functions/sts-live-voice-tts-session
• iOS:
  • ios/SpeakTrue/STTViewModel.swift
  • ios/SpeakTrue/STSViewModel.swift
  • ios/SpeakTrue/SpeechToSpeechView.swift
  • ios/SpeakTrue/RealtimeSTTService.swift
  • ios/SpeakTrue/LiveVoiceSTSService.swift
• Android:
  • android/app/src/main/java/com/speaktrue/features/stt/*
  • android/app/src/main/java/com/speaktrue/features/sts/data/*
  • android/app/src/main/java/com/speaktrue/features/sts/presentation/STSViewModel.kt
• Web:
  • web/python-web-app/src/routes/stt.py
  • web/python-web-app/static/js/index_stt.js
  • web/python-web-app/static/js/index_sts_live_voice.js
• Tests:
  • backend STS/STT function tests
  • web/python-web-app/tests/js/sts_*.mjs
  • ios/SpeakTrueTests/*STS*, Android STS contract tests.

4.3 Soundboard changes

• Primary backends:
  • backend/supabase/functions/soundboard-save-generated
  • backend/supabase/functions/soundboard-delete
  • backend/supabase/functions/clip-order-batch
  • (plus DB migrations)
• iOS:
  • ios/SpeakTrue/SoundboardView.swift
  • ios/SpeakTrue/SoundboardViewModel.swift
  • ios/SpeakTrue/SoundboardCacheManager.swift
  • ios/SpeakTrue/SoundboardCacheIndex.swift
• Android:
  • android/app/src/main/java/com/speaktrue/features/soundboard/ui/SoundboardScreen.kt
  • android/app/src/main/java/com/speaktrue/features/soundboard/presentation/SoundboardViewModel.kt
  • android/app/src/main/java/com/speaktrue/features/soundboard/data/*
• Web:
  • 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
• Tests:
  • backend soundboard function tests
  • mobile soundboard tests.

4.4 Voice-clone path

• Primary backends:
  • backend/supabase/functions/voice-clone-preflight
  • backend/supabase/functions/voice-clone-create
  • backend/supabase/functions/voice-clone-delete
  • backend/supabase/functions/byok-resolve
  • backend/supabase/functions/byok-upsert
• iOS:
  • ios/SpeakTrue/VoiceCloneTabView.swift
  • ios/SpeakTrue/VoiceCloneViewModel.swift
  • ios/SpeakTrue/AIDataSharingAgreementService.swift
  • ios/SpeakTrue/AIDataSharingConsentGateView.swift
• Android:
  • android/app/src/main/java/com/speaktrue/features/voiceclone/presentation/VoiceCloneViewModel.kt
  • android/app/src/main/java/com/speaktrue/features/voiceclone/ui/VoiceCloneScreen.kt
  • android/app/src/main/java/com/speaktrue/features/voiceclone/data/VoiceCloneRepository.kt
• Web:
  • web/python-web-app/src/routes/voice_clone.py
  • web/python-web-app/src/services/voice_clone_service.py
• Tests:
  • backend voice-clone tests
  • iOS/Android voice-clone settings tests.

4.5 User settings + agreement + quotas

• Primary backends:
  • backend/supabase/functions/user-settings-get
  • backend/supabase/functions/user-settings-update
  • backend/supabase/functions/quota-status
  • backend/supabase/functions/pronunciation-dictionary (pronunciation settings in some payloads)
  • relevant migration files in backend/supabase/migrations
• iOS:
  • ios/SpeakTrue/UserSettings.swift
  • ios/SpeakTrue/UserSettingsSyncService.swift
  • ios/SpeakTrue/SettingsTabView.swift
  • ios/SpeakTrue/SettingsView.swift
• Android:
  • android/app/src/main/java/com/speaktrue/features/settings/data/SettingsStore.kt
  • android/app/src/main/java/com/speaktrue/features/settings/data/SettingsRepository.kt
  • android/app/src/main/java/com/speaktrue/features/settings/presentation/SettingsViewModel.kt
  • android/app/src/main/java/com/speaktrue/features/settings/ui/SettingsScreen.kt
• Web:
  • web/python-web-app/src/routes/settings.py
  • web/python-web-app/src/services/user_settings_service.py
  • web/python-web-app/templates/partials/index_slow/settings.html
• Tests:
  • backend function tests
  • mobile settings tests.

4.6 Billing and entitlement changes

• Primary backends:
  • backend/supabase/functions/billing-apple-sync
  • backend/supabase/functions/billing-apple-notifications
  • backend/supabase/functions/billing-google-play-sync
  • backend/supabase/functions/billing-stripe-webhook
  • backend/supabase/functions/_shared/subscription-gating-config.ts
  • backend/supabase/functions/_shared/entitlements.ts
  • backend/supabase/functions/_shared/billing-entitlement-policy.ts
• Shared surfaces:
  • iOS entitlement-sensitive checks in app runtime and settings.
  • Android entitlement checks in repositories and feature gating.
  • Legal/consent changes in agreement files and settings screens.
• Tests:
  • backend billing tests, quota tests, and platform-specific feature gating tests.

4.7 Auth/session and app bootstrap

• iOS:
  • ios/SpeakTrue/AuthService.swift
  • ios/SpeakTrue/AuthState.swift
  • ios/SpeakTrue/SupabaseClientProvider.swift
  • ios/SpeakTrue/SpeakTrueApp.swift
• Android:
  • android/app/src/main/java/com/speaktrue/core/auth/*
  • android/app/src/main/java/com/speaktrue/app/SpeakTrueApp.kt
  • android/app/src/main/java/com/speaktrue/app/MainActivity.kt
• Web:
  • web/python-web-app/src/legacy_runtime.py
  • web/python-web-app/src/routes/legacy.py and web/python-web-app/src/services/auth_service.py
  • web/python-web-app/src/services/supabase_edge_client.py

4.8 Pronunciation dictionary and language recommendations

• Primary backends:
  • backend/supabase/functions/pronunciation-dictionary
  • backend/supabase/functions/language-recommend
• iOS:
  • ios/SpeakTrue/PronunciationGlossaryView.swift
  • ios/SpeakTrue/PronunciationGlossaryViewModel.swift
• Android:
  • android/app/src/main/java/com/speaktrue/features/dictionary/ui/PronunciationDictionaryScreen.kt
  • android/app/src/main/java/com/speaktrue/features/dictionary/presentation/PronunciationDictionaryViewModel.kt
  • android/app/src/main/java/com/speaktrue/features/dictionary/data/PronunciationRepository.kt
• Web:
  • Pronunciation-related service paths under web/python-web-app/src/routes/stt.py and web/python-web-app/src/services/speech_service.py when used in UI parity.

5) When contract changes, always edit these four layers together

1. Contract code (endpoint handler, validation, or response shaping).
2. Calling clients (iOS/Android/Web).
3. Persisted shape (migrations / SQL / stored defaults).
4. Tests + docs.

If any one layer is skipped, the project will regress on one surface even when local tests pass.

6) Deployment and release workflow map (high precision)

iOS

• Config/runtime changes should be validated against:
  • ios/Config/App.Debug.xcconfig
  • ios/Config/App.Release.xcconfig
  • app startup wiring in ios/SpeakTrue/SpeakTrueApp.swift
• Build and run checks done from Xcode as above.

Android

• Build/dependencies:
  • android/build.gradle.kts
  • android/settings.gradle.kts
  • android/app/build.gradle.kts
  • android/gradle/libs.versions.toml
• Release:
  • follow docs/ops/ANDROID_PLAY_RELEASE_CHECKLIST.md

Backend

• Function change and migration touchpoints:
  • backend/supabase/config.toml
  • function directory under backend/supabase/functions/<name>/
  • migrations under backend/supabase/migrations/
• Validation:
  • local test + scripted contract gates.

Web

• Legacy runtime environment changes:
  • web/python-web-app/src/app.py, wsgi.py, requirements.txt
  • startup/compose files and Gunicorn invocation.
• Marketing static updates:
  • web/marketing/index.html, scripts/styles, deploy notes.

7) Exact file lookup for “where to change Y”

When uncertain, use this quick method:

1. Find the business area in this file.
2. Open inventory for that surface:
   • docs/reference/ios-file-inventory.md
   • docs/reference/android-file-inventory.md
   • docs/reference/web-file-inventory.md
3. Confirm function contract in:
   • backend/supabase/functions/<function>/
   • docs/reference/backend-functions-detailed-map.md
4. Apply edits in all three surfaces if response schema changes.

8) Final checklist before merging any cross-surface change

• Surface ownership verified from inventories.
• Backend contract tests updated.
• Relevant mobile/web callers updated.
• Migration impact checked (if DB-backed behavior changed).
• Device or browser smoke path validated.
• docs/index and contract docs updated.