SpeakTrue

SpeakTrue Canonical Onboarding Atlas

For a first-time software engineer inheriting this repository

Last updated: 2026-06-29

This file is the one-stop reading path for understanding the entire repository and making safe edits.

If you need exhaustive file-by-file ownership, use the inventories in section 2. If you need exact backend endpoint behavior, use section 4 and section 5.

1) Start here (before editing any code)

Read in this exact order:

1. README.md
2. AGENTS.md
3. docs/reference/repository-ultimate-engineering-bible.md
4. docs/contracts/native-speech-parity-anchor.md
5. docs/contracts/speech-workflow-contract.md
6. one of:
   • docs/reference/ios-file-inventory.md
   • docs/reference/android-file-inventory.md
   • docs/reference/web-file-inventory.md

Then open the files that match your target surface and feature (sections 2–4).

2) File-level ownership truth (every file, complete)

The following files are your canonical file-level indices. Use these when you need to know what any file owns:

• iOS: docs/reference/ios-file-inventory.md
• Android: docs/reference/android-file-inventory.md
• Web: docs/reference/web-file-inventory.md

Important: these inventories are complete by design and include generated artifacts, support scripts, tests, and resources. Do not edit generated artifacts manually (coverage outputs, build artifacts); regenerate instead.

2.1 What to do when you need “what does this file do?”

• Start in the inventory table and use the row containing the file.
• Then open the surface map for that feature in this file (next section).
• Then open the corresponding client-side caller and backend contract docs for behavior details.

3) Surface architecture in one page

3.1 iOS (ios/)

Responsibility:

• SwiftUI feature orchestration
• Auth/session startup
• Calls backend functions through AIProxyService
• Local caches and playback/storage adapters

Primary subsystems:

• Startup/app shell: SpeakTrueApp.swift, ContentView.swift, AuthGateView.swift, MainTabView.swift
• Speech surface:
  • TTS: TTSViewModel.swift, TextToSpeechView.swift, TTSCatSelectView.swift, VoiceModelSelectionView.swift
  • STT: STTViewModel.swift, SpeechToTextView.swift
  • STS: STSViewModel.swift, SpeechToSpeechView.swift, LiveVoiceSTSService.swift, RealtimeSTTService.swift
• Soundboard: SoundboardView.swift, SoundboardViewModel.swift, SoundboardCacheManager.swift, SoundboardCacheIndex.swift
• Voice clone and pronunciation: VoiceCloneViewModel.swift, VoiceCloneTabView.swift, PronunciationGlossary*
• Settings and agreements: SettingsView.swift, SettingsTabView.swift, UserSettings.swift, UserSettingsSyncService.swift, AIDataSharingAgreementService.swift
• Cross-cutting services: AuthService.swift, SupabaseClientProvider.swift, CloudStorageService.swift, StorageManager.swift, AudioPlayerService.swift, AudioRecorderService.swift

3.2 Android (android/)

Responsibility:

• Compose app shell
• Feature modules under features/* with strict boundaries (ui, presentation, data)
• Shared services in core/*
• Calls backend functions through core/network and repository layers

Primary subsystems:

• Startup/app shell: app/SpeakTrueApp.kt, app/MainActivity.kt, ui/navigation/AppNavGraph.kt
• Speech surface:
  • TTS: features/tts/*
  • STT: features/stt/*
  • STS: features/sts/data/*, features/sts/presentation/STSViewModel.kt, features/sts/ui/STSScreen.kt
• Soundboard: features/soundboard/*
• Voice clone: features/voiceclone/*
• Settings/consent: features/settings/*, features/agreement/*
• Shared runtime: core/audio, core/auth, core/network, core/storage, core/config, core/reliability

3.3 Web (web/)

Responsibility:

• Public marketing site
• Legacy Python runtime with compatibility surface
• Compatibility bridge to edge function contracts

Primary subsystems:

• Marketing static: web/marketing/index.html, web/marketing/scripts/*, web/marketing/styles/*, deployment metadata (_headers, _redirects, site.webmanifest)
• Legacy web app runtime: web/python-web-app/src/app.py, src/config.py, src/legacy_runtime.py, src/legacy_runtime_adapter.py, wsgi.py
• Routes/services: web/python-web-app/src/routes/*.py, web/python-web-app/src/services/*.py
• Templates/assets/tests: web/python-web-app/templates, static, tests

4) Backend function atlas (by responsibility)

All edge endpoints are under backend/supabase/functions.

4.1 Authentication + account

• account-delete: delete user and user-owned resources in controlled server-side flow.

4.2 Billing/entitlement

• billing-apple-sync
• billing-apple-notifications
• billing-google-play-sync
• billing-stripe-webhook

Shared billing policy logic: _shared/entitlements.ts, _shared/billing-entitlement-policy.ts, _shared/subscription-gating-config.ts, _shared/quotas.ts.

4.3 Usage and settings

• quota-status: read quota/usage envelope.
• user-settings-get: fetch settings + compatibility defaults.
• user-settings-update: patch-write settings.
• byok-resolve: fetch BYOK state.
• byok-upsert: persist BYOK state.

4.4 Generation and model catalogs

• tts-generate: core TTS contract validation, policy, provider execution, artifact return.
• voices-list: voice catalog with private/public filtering.
• models-list: model catalog and provider mapping.
• style-presets: style preset CRUD/read.
• pronunciation-dictionary: pronunciation rule CRUD.
• language-recommend: language recommendation payload.

4.5 STT / STS

• stt-transcribe: non-streaming STT endpoint.
• sts-near-realtime-session: opens near-realtime session.
• sts-realtime-session: opens real-time STS session.
• sts-live-voice-tts-session: live voice-to-speech STS session.
• sts-realtime-finalize: finalizes active or near-real-time STS session and returns final artifact.
• sts-live-interpreter-session: scaffold only.
• sts-live-interpreter-tts-session: scaffold only.

4.6 Soundboard

• soundboard-save-generated: persist generated clip metadata and storage links.
• soundboard-delete: delete clips + storage cleanup.
• clip-order-batch: persist drag/drop ordering and category placement.
• soundboard-clip-ingest: scaffold only.

4.7 Voice clone

• voice-clone-preflight: readiness validation before create.
• voice-clone-create: creates clone + provider metadata persistence.
• voice-clone-delete: delete clone + provider cleanup.

4.8 Bug / utility

• bug-report-submit: ingest bug report payload.
• waitlist-signup: write-only waitlist capture with dedupe.

For a machine-dense map of all files per function and test expectations, open:

• docs/reference/backend-functions-deep-dive.md
• docs/reference/backend-functions-detailed-map.md

5) “Where do I change X / Y / Z?” matrix

Use this before any pull request.

5.1 Change core TTS behavior (models, voices, style, output contract)

Change these files:

1. backend/supabase/functions/tts-generate/*
2. backend/supabase/functions/voices-list/*
3. backend/supabase/functions/models-list/*
4. backend/supabase/functions/style-presets/* if style defaults changed
5. ios/SpeakTrue/{TTSViewModel.swift,TextToSpeechView.swift,AIProxyService.swift,TTSCatSelectView.swift,VoiceModelSelectionView.swift}
6. android/app/src/main/java/com/speaktrue/features/tts/{data,presentation,ui}/*
7. web/python-web-app/src/services/tts_service.py, src/routes/tts.py, web templates if used in parity mode

5.2 Change STT/STS behavior (recording, session start/finalize, transcript shaping)

1. Backend:
   • backend/supabase/functions/stt-transcribe/*
   • backend/supabase/functions/sts-near-realtime-session/*
   • backend/supabase/functions/sts-realtime-session/*
   • backend/supabase/functions/sts-live-voice-tts-session/*
   • backend/supabase/functions/sts-realtime-finalize/*
2. iOS:
   • ios/SpeakTrue/{STTViewModel.swift,STSViewModel.swift,SpeechToSpeechView.swift,SpeechToTextView.swift,RealtimeSTTService.swift,LiveVoiceSTSService.swift,AIProxyService.swift}
3. 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
4. Legacy web:
   • web/python-web-app/src/routes/stt.py
   • web/python-web-app/src/services/speech_service.py
   • web/python-web-app/static/js/index_stt.js
   • web/python-web-app/static/js/index_sts_live_voice.js

5.3 Change soundboard behavior (ordering, persistence, delete semantics)

1. Backend:
   • backend/supabase/functions/soundboard-save-generated/*
   • backend/supabase/functions/soundboard-delete/*
   • backend/supabase/functions/clip-order-batch/*
2. iOS:
   • ios/SpeakTrue/{SoundboardView.swift,SoundboardViewModel.swift,SoundboardCacheManager.swift,SoundboardCacheIndex.swift,AIProxyService.swift}
3. Android:
   • android/app/src/main/java/com/speaktrue/features/soundboard/*
4. 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

5.4 Change voice clone flow (create/delete/preflight/agreement)

1. Backend:
   • backend/supabase/functions/voice-clone-preflight/*
   • backend/supabase/functions/voice-clone-create/*
   • backend/supabase/functions/voice-clone-delete/*
   • backend/supabase/functions/byok-* if BYOK influences gating
2. iOS:
   • ios/SpeakTrue/{VoiceCloneTabView.swift,VoiceCloneViewModel.swift,AIDataSharingAgreementService.swift,AIDataSharingConsent*}
3. Android:
   • android/app/src/main/java/com/speaktrue/features/voiceclone/*
4. Web:
   • web/python-web-app/src/routes/voice_clone.py
   • web/python-web-app/src/services/voice_clone_service.py

5.5 Change settings/quotas/agreements

1. Backend:
   • backend/supabase/functions/user-settings-get/*
   • backend/supabase/functions/user-settings-update/*
   • backend/supabase/functions/quota-status/*
   • backend/supabase/migrations/* if schema or default changes
2. iOS:
   • ios/SpeakTrue/{UserSettings.swift,UserSettingsSyncService.swift,SettingsView.swift,SettingsTabView.swift,AIDataSharing*}
3. Android:
   • android/app/src/main/java/com/speaktrue/features/settings/*
4. Web:
   • web/python-web-app/src/routes/settings.py
   • web/python-web-app/src/services/user_settings_service.py

5.6 Add new backend endpoint

1. Create function directory in backend/supabase/functions/<new_name>/.
2. Add:
   • index.ts
   • handler.ts
   • tests (handler_test.ts, validation tests where applicable)
3. Add any SQL grants/defaults in backend/supabase/migrations.
4. Add client callsites on all surfaces that consume the contract.
5. Add/adjust parity tests for each impacted surface.

6) Deployment and verification matrix by target

6.1 Backend-only change

1. bash scripts/coverage_backend_contracts.sh
2. bash scripts/regression_migration_paths.sh
3. Focused function handler tests in changed directories.
4. If schema changed: run migration + check gates in docs/ops/*.

6.2 iOS change

1. Run targeted Xcode build for changed scheme.
2. Run affected UI/persistence unit tests in ios/SpeakTrueTests.
3. For auth/startup or entitlements changes validate:
   • ios/Config/App.Debug.xcconfig
   • ios/Config/App.Release.xcconfig
   • ios/SpeakTrue.entitlements
   • ios/SpeakTrue/Info.plist

6.3 Android change

1. ./gradlew -p android :app:compileDebugKotlin
2. ./gradlew -p android :app:testDebugUnitTest
3. ./gradlew -p android :app:lintDebug
4. For release prep: ./gradlew -p android :app:bundleRelease
5. Follow and collect evidence with docs/ops/ANDROID_PLAY_RELEASE_CHECKLIST.md.

6.4 Marketing deployment

1. Validate marketing page flow locally or via staging path.
2. Deploy via Cloudflare Pages process in docs/ops/CLOUDFLARE_PAGES_DEPLOY.md.

6.5 Legacy web deployment

1. python3 -m pytest web/python-web-app/tests
2. Smoke run using python-web-app entrypoint (wsgi:app / gunicorn)
3. Verify route/service compatibility in web/python-web-app/src/legacy_runtime_adapter.py and impacted src/routes/*, src/services/*.

7) Incident triage playbook

When a bug report arrives:

1. Identify surface: iOS, Android, web, backend, or migration/supabase.
2. Identify user action and flow (TTS/STT/Soundboard/Settings/Voice clone/STS).
3. Trace through:
   • backend contract (docs/reference/backend-functions-deep-dive.md + function handler + tests)
   • caller files in iOS/Android/web inventories
4. Compare with migration layer in backend/supabase/migrations.
5. Reproduce and validate in a minimum focused test slice:
   • backend function tests in touched endpoint
   • surface tests for specific feature
6. Patch all surfaces that share the contract.

8) Change hygiene and documentation hygiene

When editing behavior:

• Update docs you touched first in the same pull to keep source-of-truth aligned.
• If behavior affects startup/auth/entitlement/quotas/storage contracts, update:
  • one surface implementation doc
  • one operator/doc runbook if deployment changes
  • any migration notes or contract docs
• Keep generated artifacts and scratch outputs out of final commits.

9) Canonical links (where to continue reading)

You do not need to open every file manually if you stay in these ordered links:

1. docs/reference/repository-extreme-technical-atlas.md
2. docs/reference/repository-ultimate-engineering-bible.md
3. docs/reference/repository-full-deep-reference.md
4. docs/reference/repository-onboarding-reference.md
5. docs/reference/repository-operator-manual.md
6. docs/reference/ios-file-inventory.md
7. docs/reference/android-file-inventory.md
8. docs/reference/web-file-inventory.md
9. docs/reference/backend-functions-detailed-map.md
10. docs/reference/backend-functions-deep-dive.md