SpeakTrue

SpeakTrue Extreme Technical Atlas

Purpose: single source for a first-time engineer who needs to understand the entire repository and make safe, cross-surface edits.

Last updated: 2026-06-29

This document is not a replacement for the existing deep references. It is an operations-oriented atlas that tells you:

1. What each platform owns.
2. Which files are affected for a given change.
3. Which backend contract + migration + test surfaces must be touched.
4. What to run to deploy or validate changes.

1) Before editing: required read set

Open these files before making behavior changes:

1. README.md
2. AGENTS.md
3. docs/contracts/speech-workflow-contract.md
4. docs/contracts/native-speech-parity-anchor.md
5. One full surface inventory
   • docs/reference/ios-file-inventory.md
   • docs/reference/android-file-inventory.md
6. Backend contracts:
   • docs/reference/backend-functions-deep-dive.md
   • docs/reference/backend-functions-detailed-map.md
7. Any affected operation docs in docs/ops/* if you are touching deployment, billing, or migrations.

If the request spans backend + one client surface, treat both inventories and the same backend contract docs as required.

2) Repository map (first-pass mental model)

1. Clients are thin orchestrators:
   • iOS (ios/) composes screen state, local settings, and service calls.
   • Android (android/) follows feature modules with ui/presentation/data.
   • Legacy web (web/python-web-app/) is a compatibility runtime and parity bridge; web/marketing/ is the public static site.
2. Backend policy and privileged operations are in backend/supabase/functions/ and backend/supabase/migrations/.
3. Storage migration seam for legacy web is currently adapter-backed; changes should keep legacy_runtime_adapter and seam boundaries intact unless a migration contract update is required.

3) Complete file-level ownership anchors

These files are authoritative per-file responsibility lists:

1. docs/reference/ios-file-inventory.md
2. docs/reference/android-file-inventory.md
3. docs/reference/web-file-inventory.md

Use these when you need explicit “what each file does.” Treat generated artifacts (build outputs, cache assets, coverage artifacts) as regenerate-only, not manual edit targets.

4) iOS editing guide (what to change where)

4.1 iOS startup + lifecycle edits

• ios/SpeakTrueApp.swift
• ios/SpeakTrue/ContentView.swift
• ios/SpeakTrue/AuthGateView.swift
• ios/SpeakTrue/StartupLoadingView.swift
• ios/SpeakTrue/AuthService.swift
• ios/SpeakTrue/SupabaseClientProvider.swift
• ios/SpeakTrue/AuthState.swift

Use these files when touching startup flow, session bootstrap, app shell routing, or auth gating.

4.2 iOS feature edits

• TTS / voices / models: TTSViewModel.swift, TextToSpeechView.swift, TTSCatSelectView.swift, VoiceModelSelectionView.swift, AIProxyService.swift.
• STT / STS: STTViewModel.swift, STSViewModel.swift, SpeechToSpeechView.swift, SpeechToTextView.swift, RealtimeSTTService.swift, LiveVoiceSTSService.swift, AudioRecorderService.swift, LiveVoiceAudioPlayer.swift.
• Soundboard: SoundboardView.swift, SoundboardViewModel.swift, SoundboardCacheManager.swift, SoundboardCacheIndex.swift, SoundboardAudioClips.swift, SBCategoryDetailView.swift, SoundboardCategories.swift.
• Voice clone + pronunciation: VoiceCloneViewModel.swift, VoiceCloneTabView.swift, AIDataSharingAgreementService.swift, AIDataSharingConsent*, PronunciationGlossaryView.swift, PronunciationGlossaryViewModel.swift.
• Settings / agreements / quotas: SettingsView.swift, SettingsTabView.swift, SettingsModels.swift, UserSettings.swift, UserSettingsSyncService.swift, AIDataSharingConsentGateView.swift.
• Shared services / utilities: AIProxyService.swift, CloudStorageService.swift, StorageManager.swift, AudioPlayerService.swift, DebugLogger.swift, AsyncTimeout.swift.

4.3 iOS configuration and tests

• Build config: ios/Config/App.Debug.xcconfig, ios/Config/App.Release.xcconfig
• Entitlements/capabilities: ios/SpeakTrue.xcconfig? (if present in local branch), ios/SpeakTrue.entitlements, ios/Info.plist
• Tests: files in ios/SpeakTrueTests/* and ios/SpeakTrueUITests/*
• If config or startup changed, run at least targeted compilation + related unit tests and manual app launch smoke.

5) Android editing guide (what to change where)

5.1 Android foundation

• App shell/config: android/app/src/main/java/com/speaktrue/app/SpeakTrueApp.kt, MainActivity.kt, ui/navigation/AppNavGraph.kt
• Global config/build: android/settings.gradle.kts, android/build.gradle.kts, android/app/build.gradle.kts, android/gradle/libs.versions.toml
• Core cross-cutting: android/app/src/main/java/com/speaktrue/core/*

5.2 Android feature edits

• TTS / voices / presets: features/tts/data/*, features/tts/presentation/TTSViewModel.kt, features/tts/ui/TTSScreen.kt, plus voice/model/state mapping modules.
• STT / STS: features/stt/*, features/sts/*, features/sts/presentation/STSViewModel.kt.
• Soundboard: features/soundboard/data/*, features/soundboard/presentation/SoundboardViewModel.kt, features/soundboard/ui/SoundboardScreen.kt.
• Voice clone: features/voiceclone/data/*, features/voiceclone/presentation/*, features/voiceclone/ui/*.
• Settings + agreement: features/settings/*, features/agreement/*.
• Tests: features/**/*Test*, android/app/src/test, android/app/src/androidTest.

6) Web editing guide (what to change where)

6.1 Marketing static site

• web/marketing/index.html, web/marketing/auth/callback/index.html
• web/marketing/scripts/*.js
• web/marketing/styles/*.css
• Static config and deploy: _headers, _redirects, site.webmanifest, deploy-version.json

6.2 Legacy web runtime (compatibility seam)

• App bootstrap and routes:
  • web/python-web-app/wsgi.py, src/app.py, src/config.py, src/legacy_runtime.py, src/legacy_runtime_adapter.py
  • web/python-web-app/src/routes/*.py
• Service and persistence seams:
  • web/python-web-app/src/services/*.py
  • web/python-web-app/src/storage/*.py
  • web/python-web-app/src/storage_provider.py
• JS parity/runtime scripts:
  • web/python-web-app/static/js/*
  • web/python-web-app/templates/**/*.html
• Runtime/deploy: web/python-web-app/Dockerfile, Procfile, docker-compose.yml, docker-entrypoint.sh.

7) Backend function atlas (complete list)

For each function, edit the directory and the linked shared modules when contract changes occur.

1. /account-delete Folder: backend/supabase/functions/account-delete Purpose: delete auth + user-owned runtime resources under authenticated control.

2. /billing-apple-sync Folder: backend/supabase/functions/billing-apple-sync Purpose: import and normalize Apple transaction updates into entitlement state.

3. /billing-apple-notifications Folder: backend/supabase/functions/billing-apple-notifications Purpose: process webhook events and map transaction state to entitlement transitions.

4. /billing-google-play-sync Folder: backend/supabase/functions/billing-google-play-sync Purpose: validate Play billing payloads and apply entitlement updates.

5. /billing-stripe-webhook Folder: backend/supabase/functions/billing-stripe-webhook Purpose: verify Stripe signatures, process events, persist usage/billing outcomes.

6. /bug-report-submit Folder: backend/supabase/functions/bug-report-submit Purpose: accept and persist client-side bug reports.

7. /byok-resolve, /byok-upsert Folders: backend/supabase/functions/byok-resolve, backend/supabase/functions/byok-upsert Purpose: fetch/store BYOK credential metadata for provider calls.

8. /clip-order-batch Folder: backend/supabase/functions/clip-order-batch Purpose: persist ordered clip arrays with ownership checks.

9. /language-recommend Folder: backend/supabase/functions/language-recommend Purpose: provide recommended language suggestions for STT/STS.

10. /models-list Folder: backend/supabase/functions/models-list Purpose: return available TTS model list with entitlement/contract filtering.

11. /voices-list Folder: backend/supabase/functions/voices-list Purpose: return available voice list by entitlement and policy rules.

12. /pronunciation-dictionary Folder: backend/supabase/functions/pronunciation-dictionary Purpose: read/write pronunciation hints used by speech flows.

13. /quota-status Folder: backend/supabase/functions/quota-status Purpose: expose quota/usage state used by mobile and web clients.

14. /soundboard-save-generated Folder: backend/supabase/functions/soundboard-save-generated Purpose: persist generated clip metadata and storage linkage.

15. /soundboard-delete Folder: backend/supabase/functions/soundboard-delete Purpose: remove generated clip records plus storage objects.

16. /soundboard-clip-ingest Folder: backend/supabase/functions/soundboard-clip-ingest Purpose: scaffold for future ingestion contract; keep guarded until implementation is complete.

17. /stt-transcribe Folder: backend/supabase/functions/stt-transcribe Purpose: non-streaming STT conversion with provider calls + policy + persistence.

18. /sts-live-voice-tts-session Folder: backend/supabase/functions/sts-live-voice-tts-session Purpose: start low-latency live STS voice-to-speech session.

19. /sts-near-realtime-session Folder: backend/supabase/functions/sts-near-realtime-session Purpose: create near-real-time STS session envelope.

20. /sts-realtime-session Folder: backend/supabase/functions/sts-realtime-session Purpose: create realtime STS session and return connection metadata.

21. /sts-realtime-finalize Folder: backend/supabase/functions/sts-realtime-finalize Purpose: finalize STS artifacts (transcript + audio + metadata) on completion.

22. /sts-live-interpreter-session Folder: backend/supabase/functions/sts-live-interpreter-session Purpose: scaffold-only live interpreter session entrypoint.

23. /sts-live-interpreter-tts-session Folder: backend/supabase/functions/sts-live-interpreter-tts-session Purpose: scaffold-only live interpreter TTS session contract.

24. /style-presets Folder: backend/supabase/functions/style-presets Purpose: manage style preset data used by speech generation.

25. /tts-generate Folder: backend/supabase/functions/tts-generate Purpose: core TTS validation, usage checks, provider invocation, contract response.

26. /user-settings-get Folder: backend/supabase/functions/user-settings-get Purpose: return user settings with migration-safe defaults.

27. /user-settings-update Folder: backend/supabase/functions/user-settings-update Purpose: patch user settings changes with validation.

28. /voice-clone-preflight Folder: backend/supabase/functions/voice-clone-preflight Purpose: validate clone eligibility and preconditions.

29. /voice-clone-create Folder: backend/supabase/functions/voice-clone-create Purpose: create backend voice clone and register provider metadata.

30. /voice-clone-delete Folder: backend/supabase/functions/voice-clone-delete Purpose: delete a user clone and clean provider-side references.

31. /waitlist-signup Folder: backend/supabase/functions/waitlist-signup Purpose: capture waitlist leads with dedupe and schema guarantees.

For shared backend contract behavior that affects many functions, inspect:

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

8) Feature-to-file + tests + deploy checklist

8.1 TTS / voices / models

1. Edit backend: tts-generate, voices-list, models-list, optional style-presets.
2. Edit callers: ios/SpeakTrue/*TTS* + AIProxyService, Android features/tts, web web/python-web-app/src/routes/tts.py and service path.
3. Update shared/shared tests: backend handler tests, ios/SpeakTrueTests/TTS*, Android contract tests.
4. Run at minimum: backend function tests + touched Android/iOS targeted tests.

8.2 STT / STS

1. Edit backend: stt-transcribe, sts-near-realtime-session, sts-realtime-session, sts-realtime-finalize, sts-live-voice-tts-session.
2. Edit callers: STS/STT view models/services on each client and web parity routes/services.
3. Validate with migration-aware scripted gates and platform-specific STS suites.

8.3 Soundboard

1. Edit backend: soundboard-save-generated, soundboard-delete, clip-order-batch.
2. Update callers:
   • iOS soundboard UI + cache manager + AI proxy
   • Android soundboard feature + cache/persistence
   • web routes + JS components
3. Validate ordering/idempotence and metadata persistence.

8.4 Voice clone

1. Edit backend: voice-clone-preflight, voice-clone-create, voice-clone-delete, BYOK functions if needed.
2. Edit callers on each client and agreement gates.
3. Reconfirm provider contract and storage/privacy surface from settings docs.

8.5 Settings + quotas + agreements

1. Edit backend: user-settings-get, user-settings-update, quota-status, and optional BYOK/pronunciation/language endpoints.
2. Edit clients: settings and agreement screens/services per platform.
3. Ensure migration defaults and entitlement semantics are preserved in SQL/functions.

8.6 Billing / entitlements

1. Edit backend: billing-* functions + _shared/* entitlement modules + migrations.
2. Edit client gating points in each surface’s billing/settings checks.
3. Validate webhook/handoff paths and feature visibility with contract tests.

9) Deployment and validation matrix

9.1 Backend

1. bash scripts/coverage_backend_contracts.sh
2. bash scripts/regression_migration_paths.sh
3. Function-level handler tests in modified function folders.
4. Review docs/ops/ migration smoke and gates as applicable.

9.2 Android

1. ./gradlew -p android :app:compileDebugKotlin
2. ./gradlew -p android :app:testDebugUnitTest
3. ./gradlew -p android :app:lintDebug
4. ./gradlew -p android :app:bundleRelease for release output
5. docs/ops/ANDROID_PLAY_RELEASE_CHECKLIST.md and evidence templates before publish.

9.3 iOS

1. Build in Xcode with matching scheme/config.
2. Run targeted iOS tests around touched view models/features.
3. Confirm xcconfig/entitlement/Info.plist consistency for auth, storage, and provider integrations.

9.4 Web

1. Marketing: validate page flows and run through Cloudflare deployment runbook.
2. Legacy runtime: python3 -m pytest web/python-web-app/tests and app entrypoint smoke.
3. Confirm route/service compatibility seams if changes touch legacy_runtime* or adapters.

10) Migration and schema edit rule

Any change that touches entitlement, usage, voice clones, soundboard schema, or settings shape must include matching migration work:

1. Edit backend/supabase/migrations (additive when possible).
2. Keep DB grant/policy changes aligned with function behavior.
3. Run backend contract + migration regression scripts before asking for production rollout.

11) Where to go for exact file-level detail

If your immediate task is “what does file X do”, this is the canonical path:

1. Determine surface: ios, android, web, or backend.
2. Open corresponding inventory file in section 3.
3. Open the targeted contract doc in section 1.
4. Open the feature change matrix for the behavior in section 8.

This file is intentionally cross-referenced so that no behavior change starts from guessing.