SpeakTrue

SpeakTrue Complete Deep Reference (v3)

Scope: /Users/haddadios/Documents/Programming/SpeakTrue Audience: first-time engineer, release engineer, incident responder, API integrator Last refreshed: 2026-06-29 Format: repository map + responsibility tables + change/deployment playbooks Goal: answer “where does X live and what does it own” without opening files first.

1) How to use this reference

This document is organized for first-contact triage:

Quick owner lookup → use the file tables in sections 3-7.
Behavior question → follow the section for that surface (iOS/Android/Web/Backend).
Change request → use section 12 (change playbooks) to edit the minimal files in the correct surface.
Release activity → use section 13 (operations and deployment).

2) Ground rules and architecture contract

Boundary of privilege: Auth/admin-sensitive operations should remain in Supabase/functions or equivalent backend routes.
Source of truth for product behavior:
- README.md
- docs/index.md and domain docs under docs/contracts, docs/product, docs/ops
- Platform source files (iOS/Android) + backend functions
- Migration SQL in backend/supabase/migrations
Brownfield rule: keep iOS/Android/legacy-web marketing behavior stable unless a migration/deployment runbook explicitly says otherwise.
Generated/derived artifacts: web/python-web-app/static/soundboard/audio sample media and .coverage style artifacts are documentation inputs only.

3) Repository-level map

3.1 Top-level files

Path	Responsibility
`README.md`	Human-facing project orientation and quick start flow.
`ROADMAP.md`	Historical planning index (mostly archival).
`AGENTS.md`	Working instructions and repo-specific constraints.
`PRIVACY_POLICY.md`	Legal/privacy terms snapshot.
`deno.jsonc`	Deno lock/runtime behavior for backend functions.
`deno.lock`	Dependency lockfile for backend TS functions.
`supabase/`	Supabase local config + SQL functions (actual canonical backend behavior).
`web/marketing/`	Static marketing SPA and landing pages.
`web/python-web-app/`	Legacy/flavored web runtime and compatibility surface with Supabase migration seam.
`ios/`	SwiftUI app source and iOS launch/build surface.
`android/`	Android Compose app source and CI/build scripts.
`backend/supabase/`	All Edge functions, SQL migrations, helper modules, and tests.
`scripts/`	Regression, release, migration, and verification scripts.
`.github/workflows/`	CI and deployment workflows.
`docs/`	Contract + ops + product + architecture + this reference file.

3.2 Repo conventions and operational notes

Keep docs and docs index up-to-date when behavior changes:
- Add/update docs in docs/index.md
- Link canonical runbooks from docs/ops/
For large edits, validate only the relevant slice before changing broad behavior.
For deployment or release changes, always inspect/adjust:
- platform config files
- backend function contracts
- SQL grants/migrations when changing auth or storage/security behavior.

4) iOS repository map (`ios/`)

4.1 App shell and build metadata

File	Responsibility
`ios/SpeakTrue.xcodeproj/project.pbxproj`	Xcode project/targets/build settings/configuration graph.
`ios/SpeakTrue.xcodeproj/project.xcworkspace/contents.xcworkspacedata`	Workspace metadata.
`ios/SpeakTrue.xcproject/xcshareddata/xcschemes/SpeakTrue.xcscheme`	Shared scheme for build/test/archive.
`ios/SpeakTrue.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`	SwiftPM lock state.
`ios/SpeakTrue.xcodeproj/xcuserdata/haddadios.xcuserdatad/xcschemes/xcschememanagement.plist`	User-local scheme cache (not production logic).
`ios/Config/App.Debug.xcconfig`	Debug-time values for env keys and service endpoints.
`ios/Config/App.Release.xcconfig`	Release-time values.
`ios/Config/README.md`	iOS config guidance.
`ios/SpeakTrue.entitlements`	iOS entitlement declaration (APNs/Cloud etc. where needed).
`ios/SpeakTrue.entitlements`	iOS entitlement declaration.

File	Responsibility
`ios/SpeakTrue/SpeakTrueApp.swift`	Root app bootstrap, DI graph initialization, app-wide state stores.
`ios/SpeakTrue/ContentView.swift`	Root container deciding auth-vs-surface composition.
`ios/SpeakTrue/AuthGateView.swift`	Gate for authenticated flows.
`ios/SpeakTrue/SignInView.swift`	Sign-in UI + action wiring.
`ios/SpeakTrue/StartupLoadingView.swift`	App bootstrap loading state and startup visual blocking.
`ios/SpeakTrue/MainTabView.swift`	Primary tab host and feature-level route composition.
`ios/SpeakTrue/SettingsTabView.swift`	Settings tab entry/structure.
`ios/SpeakTrue/SettingsView.swift`	Settings screen content composition.
`ios/SpeakTrue/ShareSheet.swift`	Native share sheet integration for artifacts.
`ios/SpeakTrue/AppTour.swift`	Onboarding tour and discoverability scaffold.
`ios/SpeakTrue/AuthState.swift`	Authentication/session state contract.

4.3 App services and cross-cutting domain services

File	Responsibility
`ios/SpeakTrue/AuthService.swift`	Session lifecycle, OAuth/session restore, logout/auth state synchronization.
`ios/SpeakTrue/SupabaseConfig.swift`	Reads typed runtime configuration values for client bootstrap.
`ios/SpeakTrue/SupabaseClientProvider.swift`	Factory/provider for Supabase client instances.
`ios/SpeakTrue/AIProxyService.swift`	Unified API client for edge functions and backend request gateway logic.
`ios/SpeakTrue/CloudStorageService.swift`	Storage abstraction used by soundboard/asset flows.
`ios/SpeakTrue/StorageManager.swift`	Local cache path and file persistence helper.
`ios/SpeakTrue/UserSettings.swift`	App model for user settings.
`ios/SpeakTrue/AIDataSharingAgreementService.swift`	Contract and persistence for consent gating.
`ios/SpeakTrue/UserSettingsSyncService.swift`	Sync loop between local model and remote settings endpoints.
`ios/SpeakTrue/AIDataSharingAgreementService.swift`	AIs data-sharing agreement retrieval/persistence service.

4.4 TTS/STT/STS core

File	Responsibility
`ios/SpeakTrue/TTSViewModel.swift`	Text-to-speech request lifecycle and state machine.
`ios/SpeakTrue/TextToSpeechView.swift`	TTS user screen and action points for synthesis.
`ios/SpeakTrue/STTViewModel.swift`	Speech-to-text state and transcript aggregation.
`ios/SpeakTrue/SpeechToTextView.swift`	STT recording UI and control actions.
`ios/SpeakTrue/STSViewModel.swift`	Speech-to-speech orchestration model and session lifecycle state.
`ios/SpeakTrue/SpeechToSpeechView.swift`	STS screen and artifact flow entry points.
`ios/SpeakTrue/AudioRecorderService.swift`	Microphone recording service and encoding lifecycle.
`ios/SpeakTrue/AudioPlayerService.swift`	Playback abstraction for generated/recorded clips.
`ios/SpeakTrue/LiveVoiceAudioPlayer.swift`	Real-time voice output transport and playback glue.
`ios/SpeakTrue/LiveVoiceSTSService.swift`	Live STS transport helper.
`ios/SpeakTrue/RealtimeSTTService.swift`	Real-time STT session integration helper for STS paths.
`ios/SpeakTrue/TTSCatSelectView.swift`	UI path for selecting TTS categories/settings.
`ios/SpeakTrue/StorageTestView.swift`	Diagnostic view for storage checks and path debugging.

4.5 Provider and model plumbing

File	Responsibility
`ios/SpeakTrue/VoiceModelSelectionView.swift`	Voice/model picker surface.
`ios/SpeakTrue/ElevenLabsService.swift`	Legacy direct provider client for TTS/voice operations.
`ios/SpeakTrue/ElevenLabsSTTService.swift`	Legacy direct provider client for STT operations.

4.6 Soundboard domain

File	Responsibility
`ios/SpeakTrue/SoundboardView.swift`	Main soundboard browse/play interface.
`ios/SpeakTrue/SoundboardCategories.swift`	Category data model and grouping logic.
`ios/SpeakTrue/SoundboardCacheManager.swift`	Disk cache index/build and invalidation for clips.
`ios/SpeakTrue/SoundboardCacheIndex.swift`	Persisted cache index model for clip ordering/category lookups.
`ios/SpeakTrue/SoundboardViewModel.swift`	Soundboard state machine and actions.
`ios/SpeakTrue/SoundboardAudioClips.swift`	Static/dynamic clip collection helpers and models.
`ios/SpeakTrue/SBCategoryDetailView.swift`	Category drill-in UI for clips.

4.7 Voice clone and pronunciation

File	Responsibility
`ios/SpeakTrue/VoiceCloneViewModel.swift`	Voice-clone request state orchestration and validation.
`ios/SpeakTrue/VoiceCloneTabView.swift`	Voice clone tab shell and controls.
`ios/SpeakTrue/PronunciationGlossaryView.swift`	UI for pronunciation dictionary browsing.
`ios/SpeakTrue/PronunciationGlossaryViewModel.swift`	Model + orchestration for pronunciation glossary edits.
`ios/SpeakTrue/CategoryInfo.swift`	Shared category metadata for glossary/soundboard-like grouping semantics.

4.8 Settings and agreements

File	Responsibility
`ios/SpeakTrue/SettingsModels.swift`	Settings view/state domain models.
`ios/SpeakTrue/AIDataSharingConsent.swift`	Consent model used by agreement UI.
`ios/SpeakTrue/AIDataSharingConsentGateView.swift`	Consent gate wrapper shown before restricted features.
`ios/SpeakTrue/SettingsTabView.swift`	Settings section host and grouping.
`ios/SpeakTrue/SettingsView.swift`	Settings sections and feature toggles.

4.9 Shared UI and utility components

File	Responsibility
`ios/SpeakTrue/AppTheme.swift`	Theme constants and design tokens.
`ios/SpeakTrue/ColorExtension.swift`	Palette helper extensions.
`ios/SpeakTrue/BreakManager.swift`	Break timing / silence windows for UX behavior.
`ios/SpeakTrue/AsyncTimeout.swift`	Async timeout utility shared by network and audio operations.
`ios/SpeakTrue/AudioControlsView.swift`	Play/stop/reset control component.
`ios/SpeakTrue/WaveFormView.swift`	Visual waveform rendering component.
`ios/SpeakTrue/HeaderViewTTS.swift`	TTS section header component.
`ios/SpeakTrue/HeaderViewSTT.swift`	STT section header component.
`ios/SpeakTrue/TextInputView.swift`	Generic validated multiline/single-line input component.
`ios/SpeakTrue/GenerateButtonView.swift`	Generation primary action style.
`ios/SpeakTrue/ResetButtonView.swift`	Reset/cancel action component.

4.10 Logging / diagnostics and resources

File	Responsibility
`ios/SpeakTrue/DebugLogger.swift`	Debug print wrapper and log gating helpers.
`ios/SpeakTrue/Info.plist`	Runtime app metadata and plist-configured capabilities.
`ios/SpeakTrue/Assets.xcassets/Contents.json`	Asset catalog index.
`ios/Preview Assets.xcassets/Contents.json`	Preview-only asset catalog.
`ios/SpeakTrue/Info.plist`	iOS app metadata and required capabilities declarations.

4.11 Tests (`ios/SpeakTrueTests` and `ios/SpeakTrueUITests`)

File	Responsibility
`ios/SpeakTrueTests/SpeakTrueTests.swift`	Base test target bootstrapping.
`ios/SpeakTrueTests/AppContractsTests.swift`	Contract tests for shared app behavior.
`ios/SpeakTrueTests/STTAndSTSViewModelTests.swift`	STT/STS view model behavior tests.
`ios/SpeakTrueTests/AsyncTimeoutTests.swift`	Async timeout utility tests.
`ios/SpeakTrueTests/ConfigurationAndThemeTests.swift`	Theme/config behavior validations.
`ios/SpeakTrueTests/VoiceCloneViewModelValidationTests.swift`	Voice clone state validation tests.
`ios/SpeakTrueTests/SettingsContractsTests.swift`	Settings contract consistency tests.
`ios/SpeakTrueTests/SettingsDiffTests.swift`	Settings diff detection and equality checks.
`ios/SpeakTrueTests/AuthAndSessionTests.swift`	Auth/session lifecycle behavior tests.
`ios/SpeakTrueTests/CloudStorageModelCodingTests.swift`	Storage model serialization roundtrips.
`ios/SpeakTrueTests/SoundboardCacheManagerTests.swift`	Cache manager behavior tests.
`ios/SpeakTrueTests/TTSPlaybackModeBehaviorTests.swift`	TTS playback mode and state assertions.
`ios/SpeakTrueTests/ColorExtensionTests.swift`	Color utility and theme helper tests.
`ios/SpeakTrueTests/MainTabNavigationTests.swift`	Main tab nav behavior tests.
`ios/SpeakTrueUITests/SpeakTrueUITests.swift`	UI-level integration tests.
`ios/SpeakTrueUITests/SpeakTrueUITestsLaunchTests.swift`	App launch/entry smoke assertions.

4.12 Non-source files to treat as owned only

File path pattern	What to do
`ios/SpeakTrue.xcassets/**` (except Contents.json entries)	App assets; avoid changing without design/design.md references.
`ios/SpeakTrueUITests/` generated output files	Keep in sync with interaction tests, avoid production behavior edits here.

5) Android repository map (`android/`)

5.1 Project bootstrap and global build

File	Responsibility
`android/settings.gradle.kts`	Gradle project composition and module inclusion.
`android/build.gradle.kts`	Top-level Gradle plugins and project repositories.
`android/gradle.properties`	Gradle/JVM behavior and build flags.
`android/gradle/libs.versions.toml`	Version catalog for dependencies.
`android/gradle/wrapper/gradle-wrapper.properties`	Gradle wrapper version pin.
`android/gradle/gradle-daemon-jvm.properties`	JVM defaults for daemon.
`android/app/build.gradle.kts`	Android app target config, dependencies, flavors/proguard hooks.
`android/app/proguard-rules.pro`	Release obfuscation/strip rules.
`android/ci/android-ci.yml`	CI pipeline and checks.
`android/README.md`	Android-specific implementation notes and run instructions.

5.2 App composition and entry

File	Responsibility
`android/app/src/main/java/com/speaktrue/app/MainActivity.kt`	Android host activity and window/system UI integration.
`android/app/src/main/java/com/speaktrue/app/SpeakTrueApp.kt`	Compose app root and dependency graph initialization.
`android/app/src/main/java/com/speaktrue/ui/navigation/AppNavGraph.kt`	Primary navigation graph and route wiring.
`android/app/src/main/java/com/speaktrue/features/tutorial/AppTour.kt`	User onboarding tour flow.
`android/app/src/main/java/com/speaktrue/features/shared/AppScaffold.kt`	Shared scaffold wrapper with tabs/actions.
`android/app/src/main/java/com/speaktrue/features/shared/ScreenHeader.kt`	Shared screen headers.
`android/app/src/main/java/com/speaktrue/features/shared/GenerationUiComponents.kt`	Shared UI building blocks for generation statuses.
`android/app/src/main/java/com/speaktrue/features/shared/GeneratedAudioSharePayload.kt`	Share payload shaping for generated audio artifacts.

5.3 Core platform modules

File	Responsibility
`android/app/src/main/java/com/speaktrue/core/config/RuntimeConfig.kt`	Typed runtime config (env-backed flags and endpoint values).
`android/app/src/main/java/com/speaktrue/core/network/NetworkModule.kt`	Client/session network stack injection.
`android/app/src/main/java/com/speaktrue/core/network/OriginSecurity.kt`	Request origin validation and hardening.
`android/app/src/main/java/com/speaktrue/core/network/EdgeFunctionClient.kt`	Supabase edge caller abstraction.
`android/app/src/main/java/com/speaktrue/core/network/EdgeFunctionCaller.kt`	Lower-level callable contract and error mapping.
`android/app/src/main/java/com/speaktrue/core/auth/SessionStore.kt`	Local auth session persistence.
`android/app/src/main/java/com/speaktrue/core/auth/OAuthStateStore.kt`	OAuth callback state storage and validation.
`android/app/src/main/java/com/speaktrue/core/auth/AuthCallbackHandler.kt`	Callback decode/dispatch for web auth returns.
`android/app/src/main/java/com/speaktrue/core/auth/AuthState.kt`	Auth view-state model.
`android/app/src/main/java/com/speaktrue/core/auth/AuthRepository.kt`	Auth data operations and mapping.
`android/app/src/main/java/com/speaktrue/core/auth/AuthMappers.kt`	Auth payload model mapping.
`android/app/src/main/java/com/speaktrue/core/auth/AuthModels.kt`	Auth typed models.
`android/app/src/main/java/com/speaktrue/core/audio/AudioRecorderService.kt`	Runtime capture and recorder utilities.
`android/app/src/main/java/com/speaktrue/core/audio/AudioPlayerService.kt`	Audio playback service.
`android/app/src/main/java/com/speaktrue/core/audio/ClipPlaybackService.kt`	Clip-oriented playback orchestration.
`android/app/src/main/java/com/speaktrue/core/storage/StorageService.kt`	Storage abstraction interface.
`android/app/src/main/java/com/speaktrue/core/storage/StorageResult.kt`	Storage result sealed model.
`android/app/src/main/java/com/speaktrue/core/storage/RealSupabaseStorageService.kt`	Supabase-backed implementation.
`android/app/src/main/java/com/speaktrue/core/storage/StorageModule.kt`	Storage DI wiring.
`android/app/src/main/java/com/speaktrue/core/supabase/SupabaseModule.kt`	Supabase client bootstrap and runtime access.
`android/app/src/main/java/com/speaktrue/core/reliability/ReliabilityErrorMapper.kt`	Error normalization into UI-safe categories.
`android/app/src/main/java/com/speaktrue/core/reliability/BoundedRetryQueue.kt`	Retry queueing with bounded capacity behavior.
`android/app/src/main/java/com/speaktrue/core/di/CoroutineModule.kt`	Coroutine scope providers.
`android/app/src/main/java/com/speaktrue/core/permissions/PermissionHandler.kt`	Runtime permission abstraction.
`android/app/src/main/java/com/speaktrue/core/permissions/ui/RecordAudioPermissionEffect.kt`	Permission request and UX effect host.
`android/app/src/main/java/com/speaktrue/core/runtime/SharedTextBridge.kt`	Shared text bridge across tabs/features.

5.4 Theme and design system

File	Responsibility
`android/app/src/main/java/com/speaktrue/ui/theme/Theme.kt`	Compose theme wrappers.
`android/app/src/main/java/com/speaktrue/ui/theme/Color.kt`	App color palette.
`android/app/src/main/java/com/speaktrue/ui/theme/Shape.kt`	Shape tokens and defaults.
`android/app/src/main/java/com/speaktrue/ui/theme/Type.kt`	Typography styles.
`android/app/src/main/java/com/speaktrue/ui/theme/DesignTokens.kt`	Custom tokens for layout and spacing.

5.5 Feature modules: auth

File	Responsibility
`android/app/src/main/java/com/speaktrue/features/auth/presentation/AuthViewModel.kt`	Authentication UI state and events.
`android/app/src/main/java/com/speaktrue/features/auth/presentation/AuthState.kt`	Auth state model.
`android/app/src/main/java/com/speaktrue/features/auth/data/AuthRepository.kt`	Auth repository + session interactions.
`android/app/src/main/java/com/speaktrue/features/auth/data/AuthModels.kt`	Auth models used by backend/API.
`android/app/src/main/java/com/speaktrue/features/auth/data/AuthMappers.kt`	Auth DTO/model mapping.
`android/app/src/main/java/com/speaktrue/features/auth/ui/AuthScreen.kt`	Auth screen UI and event dispatch.

5.6 Feature modules: agreement

File	Responsibility
`android/app/src/main/java/com/speaktrue/features/agreement/data/AIDataSharingAgreementRepository.kt`	Agreement fetch/store orchestration.
`android/app/src/main/java/com/speaktrue/features/agreement/presentation/AIDataSharingAgreementViewModel.kt`	Agreement state and flow gating behavior.
`android/app/src/main/java/com/speaktrue/features/agreement/ui/AIDataSharingAgreementGate.kt`	Gate UI to enforce consent before sensitive features.

5.7 Feature modules: STT/STS/TTS/voice clone/soundboard/settings/dictionary/language/presets

File	Responsibility
`android/app/src/main/java/com/speaktrue/features/stt/data/SttLanguageOption.kt`	Language option domain model.
`android/app/src/main/java/com/speaktrue/features/stt/data/STTRepository.kt`	STT endpoints and data transformation.
`android/app/src/main/java/com/speaktrue/features/stt/presentation/STTViewModel.kt`	STT UI state orchestration.
`android/app/src/main/java/com/speaktrue/features/stt/ui/STTScreen.kt`	STT compose screen.
`android/app/src/main/java/com/speaktrue/features/sts/data/LiveVoiceSTSRepository.kt`	Live STS streaming repository.
`android/app/src/main/java/com/speaktrue/features/sts/data/STSOrchestrator.kt`	STS workflow orchestration by mode.
`android/app/src/main/java/com/speaktrue/features/sts/data/RealtimeSTSAudioStreamer.kt`	Audio streaming sink/source helper for live STS.
`android/app/src/main/java/com/speaktrue/features/sts/data/RealtimeSTSRepository.kt`	Realtime STS API calls and state transforms.
`android/app/src/main/java/com/speaktrue/features/sts/presentation/STSViewModel.kt`	STS feature state and orchestration.
`android/app/src/main/java/com/speaktrue/features/sts/ui/STSScreen.kt`	STS UI + mode controls.
`android/app/src/main/java/com/speaktrue/features/language/data/ElevenLabsLanguageOptions.kt`	Legacy provider language list definitions.
`android/app/src/main/java/com/speaktrue/features/language/data/LanguageOption.kt`	Shared language model.
`android/app/src/main/java/com/speaktrue/features/language/data/LanguageRecommendationRepository.kt`	Recommendation endpoint wrapper.
`android/app/src/main/java/com/speaktrue/features/tts/data/TTSRepository.kt`	TTS request orchestration and endpoint mapping.
`android/app/src/main/java/com/speaktrue/features/tts/data/VoiceCatalogRepository.kt`	Voice catalog retrieval.
`android/app/src/main/java/com/speaktrue/features/tts/data/ModelCatalogRepository.kt`	Model catalog retrieval.
`android/app/src/main/java/com/speaktrue/features/tts/presentation/TTSViewModel.kt`	TTS state + validation logic.
`android/app/src/main/java/com/speaktrue/features/tts/ui/TTSScreen.kt`	TTS screen composition.
`android/app/src/main/java/com/speaktrue/features/tts/ui/TTSScreen.kt`	Compose TTS screen and generation actions.
`android/app/src/main/java/com/speaktrue/features/dictionary/data/PronunciationRepository.kt`	Pronunciation dictionary persistence.
`android/app/src/main/java/com/speaktrue/features/dictionary/presentation/PronunciationDictionaryViewModel.kt`	Dictionary screen state.
`android/app/src/main/java/com/speaktrue/features/dictionary/ui/PronunciationDictionaryScreen.kt`	Pronunciation dictionary user screen.
`android/app/src/main/java/com/speaktrue/features/voiceclone/data/VoiceCloneRepository.kt`	Voice clone lifecycle and DTOs.
`android/app/src/main/java/com/speaktrue/features/voiceclone/data/VoiceCloneMappers.kt`	Voice clone DTO/model mapping.
`android/app/src/main/java/com/speaktrue/features/voiceclone/data/VoiceCloneDtos.kt`	Voice clone request/response DTOs.
`android/app/src/main/java/com/speaktrue/features/voiceclone/presentation/VoiceCloneViewModel.kt`	Voice clone state + validation flow.
`android/app/src/main/java/com/speaktrue/features/voiceclone/presentation/VoiceCloneState.kt`	Voice clone domain state model.
`android/app/src/main/java/com/speaktrue/features/voiceclone/ui/VoiceCloneScreen.kt`	Voice clone screen UI.
`android/app/src/main/java/com/speaktrue/features/voiceclone/ui/VoiceCloneComponents.kt`	Reusable voice-clone UI components.
`android/app/src/main/java/com/speaktrue/features/presets/data/StylePresetRepository.kt`	Preset CRUD and ordering APIs.
`android/app/src/main/java/com/speaktrue/features/presets/presentation/StylePresetViewModel.kt`	Preset UX behavior and mutation.
`android/app/src/main/java/com/speaktrue/features/presets/ui/StylePresetScreen.kt`	Preset settings UI.
`android/app/src/main/java/com/speaktrue/features/settings/data/SettingsStore.kt`	Local settings persistence abstraction.
`android/app/src/main/java/com/speaktrue/features/settings/data/SettingsRepository.kt`	Remote/local settings orchestration.
`android/app/src/main/java/com/speaktrue/features/settings/data/BugReportRepository.kt`	Bug report submission path and payload assembly.
`android/app/src/main/java/com/speaktrue/features/settings/presentation/SettingsViewModel.kt`	Global settings state and feature toggles.
`android/app/src/main/java/com/speaktrue/features/settings/ui/SettingsScreen.kt`	Settings screen shell.
`android/app/src/main/java/com/speaktrue/features/settings/ui/SettingsSections.kt`	Settings section builder and ordering.
`android/app/src/main/java/com/speaktrue/features/settings/ui/SoundboardSettingsSection.kt`	Soundboard-specific settings controls.
`android/app/src/main/java/com/speaktrue/features/soundboard/data/SoundboardDtos.kt`	Soundboard payload/DTO models.
`android/app/src/main/java/com/speaktrue/features/soundboard/data/SoundboardAudioCacheManager.kt`	Local soundboard cache lifecycle.
`android/app/src/main/java/com/speaktrue/features/soundboard/data/SoundboardMappers.kt`	Mapping/normalization between API and UI models.
`android/app/src/main/java/com/speaktrue/features/soundboard/data/SoundboardClipNaming.kt`	Clip naming strategy and fallback.
`android/app/src/main/java/com/speaktrue/features/soundboard/data/SoundboardErrorSanitizer.kt`	Error transformation for user-safe error text.
`android/app/src/main/java/com/speaktrue/features/soundboard/data/SoundboardRepository.kt`	Main soundboard repository for lists/reorder/save.
`android/app/src/main/java/com/speaktrue/features/soundboard/presentation/SoundboardViewModel.kt`	Soundboard state machine + orchestration.
`android/app/src/main/java/com/speaktrue/features/soundboard/ui/SoundboardScreen.kt`	Soundboard main screen.
`android/app/src/main/java/com/speaktrue/features/soundboard/ui/SoundboardComponents.kt`	Reusable UI building blocks for clip cards and list.

5.8 Android resources and manifest

File	Responsibility
`android/app/src/main/AndroidManifest.xml`	App manifest, permissions, activity/deep-link settings.
`android/app/src/main/res/values/strings.xml`	String resources.
`android/app/src/main/res/values/colors.xml`	Color resources.
`android/app/src/main/res/values/themes.xml`	Base theme styles.
`android/app/src/main/res/values-v31/themes.xml`	API 31+ theme variant.
`android/app/src/main/res/values/themes.xml`	Material/compose theme fallback.
`android/app/src/main/res/drawable/...`	Drawables and splash screen resources.
`android/app/src/main/res/mipmap-/`	App icon variants.
`android/app/src/main/res/xml/file_paths.xml`	FileProvider paths.
`android/app/src/main/res/values/themes.xml`	Theme style base for app shell.

5.9 Android tests (unit, UI, parity/contracts)

File	Responsibility
`android/app/src/test/java/com/speaktrue/core/config/RuntimeConfigTest.kt`	Runtime config parsing edge cases.
`android/app/src/test/java/com/speaktrue/contracts/SettingsContractParityTest.kt`	Cross-surface settings contract parity.
`android/app/src/test/java/com/speaktrue/contracts/GenerationContractParityTest.kt`	Parity checks for generation payloads.
`android/app/src/test/java/com/speaktrue/contracts/VoiceCloneContractParityTest.kt`	Voice clone parity contract checks.
`android/app/src/test/java/com/speaktrue/contracts/SoundboardContractParityTest.kt`	Soundboard contract parity checks.
`android/app/src/test/java/com/speaktrue/contracts/AndroidReleaseReadinessContractTest.kt`	Release readiness assertions.
`android/app/src/test/java/com/speaktrue/core/network/EdgeFunctionClientTest.kt`	Network adapter test harness.
`android/app/src/test/java/com/speaktrue/core/network/OriginSecurityTest.kt`	Request security policy behavior tests.
`android/app/src/test/java/com/speaktrue/core/reliability/BoundedRetryQueueTest.kt`	Retry queue behavior.
`android/app/src/test/java/com/speaktrue/core/auth/SessionStoreTest.kt`	Local auth persistence behavior.
`android/app/src/test/java/com/speaktrue/core/auth/AuthCallbackHandlerTest.kt`	OAuth callback handler tests.
`android/app/src/test/java/com/speaktrue/core/storage/StubStorageService.kt`	Test stub for storage service; not production logic.
`android/app/src/test/java/com/speaktrue/core/storage/StubStorageServiceTest.kt`	Storage stub contract.
`android/app/src/test/java/com/speaktrue/core/audio/AudioPlayerServiceTest.kt`	Audio playback tests.
`android/app/src/test/java/com/speaktrue/core/audio/ClipPlaybackServiceTest.kt`	Clip playback tests.
`android/app/src/test/java/com/speaktrue/features/settings/presentation/SettingsViewModelTest.kt`	Settings viewmodel behavior.
`android/app/src/test/java/com/speaktrue/features/settings/data/SettingsRepositoryTest.kt`	Settings repository behavior.
`android/app/src/test/java/com/speaktrue/features/settings/data/BugReportRepositoryTest.kt`	Bug report repository tests.
`android/app/src/test/java/com/speaktrue/features/language/data/LanguageRecommendationRepositoryTest.kt`	Language recommendation tests.
`android/app/src/test/java/com/speaktrue/features/stt/presentation/STTViewModelTest.kt`	STT VM behavior.
`android/app/src/test/java/com/speaktrue/features/stt/ui/STTScreenParityTest.kt`	STT parity with spec.
`android/app/src/test/java/com/speaktrue/features/tts/presentation/TTSViewModelTest.kt`	TTS VM behavior.
`android/app/src/test/java/com/speaktrue/features/tts/data/TTSRepositoryTest.kt`	TTS repository tests.
`android/app/src/test/java/com/speaktrue/features/tts/data/ModelCatalogRepositoryTest.kt`	Model catalog parsing and transform tests.
`android/app/src/test/java/com/speaktrue/features/tts/data/VoiceCatalogRepositoryTest.kt`	Voice catalog parsing tests.
`android/app/src/test/java/com/speaktrue/features/voiceclone/presentation/VoiceCloneViewModelTest.kt`	VoiceClone VM tests.
`android/app/src/test/java/com/speaktrue/features/voiceclone/data/VoiceCloneRepositoryTest.kt`	Repository tests.
`android/app/src/test/java/com/speaktrue/features/voiceclone/data/VoiceCloneMapperTest.kt`	Mapping tests.
`android/app/src/test/java/com/speaktrue/features/voiceclone/ui/VoiceCloneScreenParityTest.kt`	Voice-clone UI parity test.
`android/app/src/test/java/com/speaktrue/features/presets/data/StylePresetRepositoryTest.kt`	Preset persistence tests.
`android/app/src/test/java/com/speaktrue/features/presets/ui/StylePresetScreenParityTest.kt`	Preset screen parity.
`android/app/src/test/java/com/speaktrue/features/soundboard/data/SoundboardRepositoryTest.kt`	Soundboard repository tests.
`android/app/src/test/java/com/speaktrue/features/soundboard/data/SoundboardMappersTest.kt`	Soundboard mapping tests.
`android/app/src/test/java/com/speaktrue/features/soundboard/data/SoundboardAudioCacheManagerTest.kt`	Cache manager tests.
`android/app/src/test/java/com/speaktrue/features/soundboard/presentation/SoundboardViewModelTest.kt`	Soundboard VM behavior.
`android/app/src/test/java/com/speaktrue/features/soundboard/ui/SoundboardReorderHelpersTest.kt`	Reorder payload/helpers tests.
`android/app/src/test/java/com/speaktrue/features/soundboard/ui/SoundboardScreenParityTest.kt`	Soundboard parity assertions.
`android/app/src/test/java/com/speaktrue/features/soundboard/data/ClipReorderPayloadTest.kt`	Drag/drop reorder payload validity tests.
`android/app/src/test/java/com/speaktrue/features/soundboard/ui/SoundboardScreenParityTest.kt`	Soundboard parity tests duplicate path in listing.
`android/app/src/test/java/com/speaktrue/features/shared/BorderlessSectionHeadingTest.kt`	Shared UI style behavior.
`android/app/src/test/java/com/speaktrue/features/shared/AppScaffoldSettingsAccessTest.kt`	Scaffold settings access.
`android/app/src/test/java/com/speaktrue/features/shared/AppScaffoldPrimaryTabsTest.kt`	Primary tab composition.
`android/app/src/test/java/com/speaktrue/features/shared/ThemedPrimaryActionButtonTest.kt`	Common primary button style.
`android/app/src/test/java/com/speaktrue/features/dictionary/ui/PronunciationDictionaryScreenParityTest.kt`	Dictionary parity test.
`android/app/src/test/java/com/speaktrue/features/tts/ui/TTSScreenParityTest.kt`	TTS parity assertions.
`android/app/src/test/java/com/speaktrue/features/sts/ui/STSScreenParityTest.kt`	STS UI parity assertions.
`android/app/src/test/java/com/speaktrue/features/settings/ui/SettingsSectionsTest.kt`	Settings section behavior.
`android/app/src/test/java/com/speaktrue/features/settings/ui/SettingsNavigationContinuityTest.kt`	Settings nav chain tests.
`android/app/src/test/java/com/speaktrue/features/settings/ui/SettingsScreenParityTest.kt`	Settings parity test.
`android/app/src/test/java/com/speaktrue/features/voiceclone/ui/VoiceCloneScreenParityTest.kt`	Voice-clone parity assertions.
`android/app/src/test/java/com/speaktrue/features/presets/ui/StylePresetScreenParityTest.kt`	Preset parity assertions.
`android/app/src/test/java/com/speaktrue/navigation/AuthNavigationTest.kt`	Auth route navigation assertions.
`android/app/src/test/java/com/speaktrue/navigation/AppNavGraphTest.kt`	Full nav graph smoke tests.
`android/app/src/test/java/com/speaktrue/ui/navigation/AppNavGraphTest.kt`	Navigation graph tests.
`android/app/src/test/java/com/speaktrue/ui/navigation/SoundboardNavigationFlowTest.kt`	Soundboard route flow tests.
`android/app/src/test/java/com/speaktrue/ui/navigation/VoiceCloneNavigationFlowTest.kt`	Voice clone route flow tests.
`android/app/src/test/java/com/speaktrue/auth/AuthScreenTest.kt`	Auth screen behavior tests.
`android/app/src/test/java/com/speaktrue/auth/AuthScreenParityTest.kt`	Auth parity tests.
`android/app/src/test/java/com/speaktrue/voiceclone/VoiceCloneScreenTest.kt`	Voice clone integration test.
`android/app/src/test/java/com/speaktrue/soundboard/CategoryPickerDragReorderTest.kt`	Drag reorder and category pick flow tests.
`android/app/src/androidTest/java/com/speaktrue/stt/STTScreenTest.kt`	STT integration UI test.

5.10 Android scripts

File	Responsibility
`android/scripts/build-debug-apk.sh`	Build debug APK.
`android/scripts/build-release-apk.sh`	Build release APK workflow.
`android/scripts/build-release-bundle.sh`	Build AAB/bundle for store.
`android/scripts/install-debug-apk.sh`	Install debug APK.
`android/scripts/install-debug-apk-interactive.sh`	Interactive install flow.
`android/scripts/run-instrumented-smoke.sh`	Device smoke test execution.
`android/scripts/build-debug-apk.sh`	Debug artifact build.
`android/scripts/capture-play-screenshots.sh`	Play screenshot capture utility.
`android/scripts/verify_android_play_assets.py`	Play asset validation utility.
`android/scripts/verify_android_play_release_smoke.py`	Release smoke verification script.
`android/scripts/verify_android_release_bundle.py`	Bundle verification.
`android/scripts/verify_android_play_policy_urls.py`	Play policy URL assertion helper.
`android/scripts/verify_android_release_signing_plumbing.sh`	Signing-chain validation.
`android/scripts/verify_android_ios_parity_release.py`	Cross-platform parity verification helper.
`android/app/` (APK output e.g. `SpeakTrue-debug.apk`)	Build artifact; do not version as source baseline except for local install verification.

6) Marketing web (`web/marketing/`)

6.1 Static app

File	Responsibility
`web/marketing/index.html`	Marketing landing page entry and main UI shell.
`web/marketing/auth/callback/index.html`	OAuth callback landing page.
`web/marketing/assets/`	Icons/images/screenshots used by landing flow and store previews.
`web/marketing/styles/main.css`	Primary marketing CSS system.
`web/marketing/styles/tokens.css`	CSS variable token definitions.
`web/marketing/scripts/main.js`	Primary interactive behavior (scroll, CTA actions).
`web/marketing/scripts/waitlist.js`	Waitlist form submission behavior.
`web/marketing/scripts/theme_boot.js`	Theme bootstrapping script.
`web/marketing/scripts/deploy_refresh.js`	Cache-busting/deploy refresh utility.
`web/marketing/_headers`	Cloudflare headers file.
`web/marketing/_redirects`	Static host redirects.
`web/marketing/site.webmanifest`	PWA manifest config.
`web/marketing/deploy-version.json`	Deployment version marker.

6.2 Marketing deployment notes

Build system is static; usually deployed through Cloudflare Pages/route config (see docs/ops/CLOUDFLARE_PAGES_DEPLOY.md).
Update copy/assets in /assets and scripts under /scripts whenever campaign/feature copy changes.

7) Legacy web runtime (`web/python-web-app/`)

7.1 Runtime bootstrap and config

File	Responsibility
`web/python-web-app/wsgi.py`	WSGI app entrypoint.
`web/python-web-app/src/app.py`	Flask app factory and blueprint registration.
`web/python-web-app/src/__init__.py`	Package init for runtime imports.
`web/python-web-app/src/config.py`	Environment configuration loader and typed config keys.
`web/python-web-app/src/db_table_names.py`	Central table name constants.
`web/python-web-app/src/legacy_runtime.py`	Legacy runtime seam/orchestration.
`web/python-web-app/src/legacy_runtime_bootstrap_service.py`	Legacy startup bootstrap orchestration.
`web/python-web-app/src/legacy_runtime_state_service.py`	Legacy startup/state service wrapper.
`web/python-web-app/src/legacy_runtime_adapter.py`	Compatibility adapter bridging legacy and supabase-backed paths.
`web/python-web-app/src/services/legacy_route_dependencies.py`	Delegates legacy route dependencies to route and service boundaries.
`web/python-web-app/Procfile`	Process launch command.
`web/python-web-app/docker-compose.yml`	Local dev run topology (if used).
`web/python-web-app/docker-entrypoint.sh`	Container startup behavior.
`web/python-web-app/requirements.txt`	Runtime dependencies.
`web/python-web-app/requirements-dev.txt`	Development/test dependencies.
`web/python-web-app/pytest.ini`	pytest configuration.
`web/python-web-app/README.md`	Legacy runtime docs.
`web/python-web-app/README_CONTEXT.md`	Additional context notes.

7.2 Routes

File	Responsibility
`web/python-web-app/src/routes/__init__.py`	Route package registration.
`web/python-web-app/src/routes/health.py`	Health check endpoints.
`web/python-web-app/src/routes/tts.py`	TTS web request routes.
`web/python-web-app/src/routes/stt.py`	STT web request routes.
`web/python-web-app/src/routes/settings.py`	Settings-related endpoints.
`web/python-web-app/src/routes/soundboard.py`	Soundboard endpoints and CRUD routes.
`web/python-web-app/src/routes/categories.py`	Soundboard category routes.
`web/python-web-app/src/routes/voice_clone.py`	Voice-clone endpoints.
`web/python-web-app/src/routes/legacy.py`	Legacy catch-all compatibility routes.

7.3 Service layer (business logic)

File	Responsibility
`web/python-web-app/src/services/__init__.py`	Service package marker.
`web/python-web-app/src/services/page_bootstrap_service.py`	Bootstraps session and service contracts for each request.
`web/python-web-app/src/services/static_service.py`	Static page/service state helper for legacy UI assembly.
`web/python-web-app/src/services/auth_service.py`	Authentication/session helper for web flows.
`web/python-web-app/src/services/auth_bootstrap_service.py`	Auth bootstrap service initialization.
`web/python-web-app/src/services/supabase_edge_client.py`	Wrapper around Supabase Edge function invocation.
`web/python-web-app/src/services/storage_provider.py`	Abstract storage provider interface + provider selection.
`web/python-web-app/src/services/storage_config_service.py`	Storage provider config and behavior switch.
`web/python-web-app/src/services/soundboard_service.py`	Soundboard business logic and orchestration.
`web/python-web-app/src/services/combined_service.py`	Combined endpoint orchestration between service pieces.
`web/python-web-app/src/services/clips_service.py`	Clip object lifecycle support.
`web/python-web-app/src/services/category_service.py`	Category operations for soundboard categories.
`web/python-web-app/src/services/category_runtime_service.py`	Category runtime helper for route dependencies.
`web/python-web-app/src/services/category_route_dependencies.py`	Route dependency providers for category APIs.
`web/python-web-app/src/services/settings_service.py`	Settings read/write business logic.
`web/python-web-app/src/services/settings_route_dependencies.py`	Settings route dependency providers.
`web/python-web-app/src/services/theme_service.py`	Theme and style default handling.
`web/python-web-app/src/services/user_settings_service.py`	User settings domain logic.
`web/python-web-app/src/services/voices_service.py`	Voices and voice catalog operations.
`web/python-web-app/src/services/models_service.py`	Model catalog operations.
`web/python-web-app/src/services/pronunciation_service.py`	Pronunciation dictionary operations.
`web/python-web-app/src/services/soundboard_migration_service.py`	Soundboard migration control and feature flags.
`web/python-web-app/src/services/default_model_service.py`	default voice/model fallback logic.
`web/python-web-app/src/services/elevenlabs_key_resolution.py`	Provider key resolution and validation.
`web/python-web-app/src/services/api_key_service.py`	API-key resolution by surface.
`web/python-web-app/src/services/tts_service.py`	TTS orchestration and payload shaping for web runtime.
`web/python-web-app/src/services/stt_service.py`	STT orchestration.
`web/python-web-app/src/services/speech_service.py`	Combined speech request facade.
`web/python-web-app/src/services/speech_route_dependencies.py`	Route dependency providers for speech endpoints.
`web/python-web-app/src/services/soundboard_route_dependencies.py`	Route dependency providers for soundboard endpoints.
`web/python-web-app/src/services/voice_clone_route_dependencies.py`	Route dependency providers for voice clone.
`web/python-web-app/src/services/speech_runtime_service.py`	Runtime contract checks for speech operations.
`web/python-web-app/src/services/combined_route_service.py`	Cross-service combined request orchestration.
`web/python-web-app/src/services/draft_service.py`	Draft artifact persistence logic.
`web/python-web-app/src/services/cache_service.py`	In-memory/persistent caching helpers.
`web/python-web-app/src/services/cache_runtime_service.py`	Runtime cache helper used by request pipeline.
`web/python-web-app/src/services/job_status_service.py`	Background job status retrieval.
`web/python-web-app/src/services/persistent_job_service.py`	Persistent background job service.
`web/python-web-app/src/jobs/job_store.py`	Job persistence service.
`web/python-web-app/src/jobs/__init__.py`	Jobs package marker.
`web/python-web-app/src/services/regeneration_service.py`	Regeneration job orchestration.
`web/python-web-app/src/services/regeneration_route_service.py`	Regeneration route orchestration.
`web/python-web-app/src/services/soundboard_route_service.py`	Route-level wrapper for soundboard operations.
`web/python-web-app/src/services/legacy_route_dependencies.py`	Legacy runtime dependency wiring.
`web/python-web-app/src/services/legacy_runtime_adapter.py`	Adapter for old runtime path compatibility.
`web/python-web-app/src/services/legacy_runtime_service.py`	Legacy surface compatibility service.
`web/python-web-app/src/services/strict_soundboard_service.py`	Strict-mode soundboard policy enforcement.
`web/python-web-app/src/services/soundboard_migration_service.py`	Migration policy enforcement service.
`web/python-web-app/src/services/combined_route_service.py`	Cross-service combined request orchestration and dependency assembly.
`web/python-web-app/src/services/voice_clone_service.py`	Voice clone service logic.
`web/python-web-app/src/services/supabase_soundboard_categories_service.py`	Supabase-backed category persistence service.
`web/python-web-app/src/services/stt_input_capture_service.py`	STT input audio capture service and capture metadata.
`web/python-web-app/src/services/audio_preprocessing.py`	Audio preprocessing helper before STT/voice workflows.
`web/python-web-app/src/services/speech_route_dependencies.py`	Route dependencies for speech APIs.
`web/python-web-app/src/storage/gcs.py`	Legacy GCS storage provider.
`web/python-web-app/src/storage/postgres.py`	Legacy/bridge PostgreSQL storage provider.
`web/python-web-app/src/storage/__init__.py`	Storage provider package marker.

7.4 Templates and static

File	Responsibility
`web/python-web-app/templates/index_slow.html`	Legacy slow-loading entry page.
`web/python-web-app/templates/settings.html`	Settings page layout.
`web/python-web-app/templates/auth_callback.html`	Auth callback landing view.
`web/python-web-app/templates/soundboard/index.html`	Soundboard full HTML view.
`web/python-web-app/templates/soundboard/manage.html`	Soundboard management view.
`web/python-web-app/templates/soundboard/category.html`	Soundboard category-level view.
`web/python-web-app/templates/templates/index_slow.html`	Template wrapper file.
`web/python-web-app/templates/templates/soundboard/*.html`	Template fragments for soundboard views.
`web/python-web-app/templates/partials/index_slow/*.html`	Feature fragment includes for settings/sts/soundboard/etc.
`web/python-web-app/static/js/*.js`	Feature-specific JS for legacy runtime (speech, STS, soundboard, settings, auth).
`web/python-web-app/static/css/index_slow.css`	Main legacy CSS.
`web/python-web-app/static/js/theme_catalog.js`	Theme catalog bootstrap and caching.
`web/python-web-app/static/js/index_settings.js`	Settings UI bindings.
`web/python-web-app/static/js/index_sts_live_voice.js`	STS live-voice JS runtime.
`web/python-web-app/static/js/index_speech.js`	Speech runtime JS.
`web/python-web-app/static/js/index_stt.js`	STT page JS entrypoints.
`web/python-web-app/static/js/index_voice_cloning.js`	Voice cloning page JS.
`web/python-web-app/static/js/index_soundboard.js`	Soundboard JS interactions.
`web/python-web-app/static/soundboard/audio/**`	Seed and sample MP3 assets and metadata.

7.5 DB bootstrap SQL files

File	Responsibility
`web/python-web-app/src/create_user_settings_table.sql`	Legacy user settings table bootstrap SQL.
`web/python-web-app/src/create_drafts_table.sql`	Draft persistence table bootstrap SQL.
`web/python-web-app/src/create_table.sql`	Core legacy tables bootstrap SQL.
`web/python-web-app/src/create_background_jobs_table.sql`	Background jobs schema.
`web/python-web-app/src/create_voice_samples_table.sql`	Voice sample metadata table.
`web/python-web-app/src/create_custom_voices_table.sql`	Custom voices table bootstrap.
`web/python-web-app/src/create_soundboard_categories_table.sql`	Legacy soundboard categories schema.

7.6 Tests

7.6.1 Python tests

File	Responsibility
`web/python-web-app/tests/conftest.py`	Test fixtures and app bootstrap for unit/API tests.
`web/python-web-app/tests/test_app_factory.py`	App creation and config wiring checks.
`web/python-web-app/tests/test_settings_*`	Settings surface and contract tests (multiple files).
`web/python-web-app/tests/test_tts.py` / `test_stt.py` / `test_sts.py`	Speech API contracts.
`web/python-web-app/tests/test_web_defaults_race.py`	Race/sequence behavior for defaults.
`web/python-web-app/tests/test_soundboard_*`	Soundboard behavior and contract tests.
`web/python-web-app/tests/api/*.py`	API-level endpoint contract suite.
`web/python-web-app/tests/unit/*.py`	Unit suites for service and route dependencies.
`web/python-web-app/tests/js/*.mjs`	Browser runtime checks for JS flow compatibility.
`web/python-web-app/tests/test_browser_auth_bootstrap.py`	Browser auth bootstrap check.

7.7 Legacy media and static test assets

web/python-web-app/static/soundboard/audio/* contain seeded sample audio and demo clip folders.
web/python-web-app/static/uploads/* contains user-supplied voice sample fixtures.
Treat these as test/media data, not behavior surface.

8) Backend edge/reference (`backend/supabase/`)

8.1 Core backend infrastructure

File	Responsibility
`backend/supabase/config.toml`	Supabase local/dev configuration.
`backend/supabase/README*`	Backend-specific docs if present.
`backend/supabase/tests/test_public_data_api_grants.py`	DB grants contract checks.
`backend/supabase/tests/test_auth_user_trigger_contract.py`	Auth-trigger contract checks.

8.2 Shared helper modules (`backend/supabase/functions/_shared/`)

File	Responsibility
`backend/supabase/functions/_shared/cors.ts`	CORS helper for function responses.
`backend/supabase/functions/_shared/types.ts`	Shared types for request/response contexts.
`backend/supabase/functions/_shared/auth-context.ts`	Request auth context extraction and user lookup helpers.
`backend/supabase/functions/_shared/user_defaults.ts`	Default values and user defaults utility.
`backend/supabase/functions/_shared/usage.ts`	Usage tracking interfaces/logic.
`backend/supabase/functions/_shared/quotas.ts`	Quota computation/normalization helpers.
`backend/supabase/functions/_shared/quotas_test.ts`	Quota helper tests.
`backend/supabase/functions/_shared/entitlements.ts`	Entitlement model helpers.
`backend/supabase/functions/_shared/billing-entitlement-policy.ts`	Billing entitlement policy rules.
`backend/supabase/functions/_shared/subscription-gating-config.ts`	Subscription gating config constants.
`backend/supabase/functions/_shared/byok.ts`	Bring-your-own-key utility helpers.
`backend/supabase/functions/_shared/theme.ts`	Theme utility shared across functions.
`backend/supabase/functions/_shared/private-voice-access.ts`	Private voice entitlement/access checks.

8.3 Edge functions by contract

Function	Request path (convention)	Responsibility
`account-delete`	`/account-delete`	Delete Supabase user + related artifacts where policy allows; harden auth checks and cleanup semantics.
`billing-apple-sync`	`/billing-apple-sync`	Receive/sync Apple App Store Billing updates to internal entitlement state.
`billing-apple-notifications`	`/billing-apple-notifications`	Parse Apple server webhook callbacks and persist entitlement mutation events.
`billing-google-play-sync`	`/billing-google-play-sync`	Validate Google Play payloads and sync subscription/entitlement state.
`billing-stripe-webhook`	`/billing-stripe-webhook`	Process Stripe webhook event dispatch/persistence and user entitlement update.
`byok-resolve`	`/byok-resolve`	Resolve BYOK credential for provider operations.
`byok-upsert`	`/byok-upsert`	Upsert BYOK material/metadata for a user.
`bug-report-submit`	`/bug-report-submit`	Store/forward bug report payload with minimal PII handling.
`clip-order-batch`	`/clip-order-batch`	Apply batch reordering of soundboard clips/categories using RPC.
`language-recommend`	`/language-recommend`	Recommend supported languages for STT/STS contexts.
`quota-status`	`/quota-status`	Return quota counters/usage and status summary.
`models-list`	`/models-list`	Return available model catalog.
`pronunciation-dictionary`	`/pronunciation-dictionary`	Read/write pronunciation dictionary entries and validation.
`soundboard-save-generated`	`/soundboard-save-generated`	Persist generated clip metadata and place into soundboard.
`soundboard-delete`	`/soundboard-delete`	Delete soundboard clip metadata and related storage rows.
`stt-transcribe`	`/stt-transcribe`	Convert audio input into transcript with capture metadata.
`style-presets`	`/style-presets`	Fetch/update style preset metadata for generation UX.
`tts-generate`	`/tts-generate`	Primary TTS generation function (validation -> ElevenLabs call or backend provider path -> artifact path).
`user-settings-get`	`/user-settings-get`	Return persisted settings payload with defaults.
`user-settings-update`	`/user-settings-update`	Apply partial update for user settings and optional sync validation.
`voice-clone-preflight`	`/voice-clone-preflight`	Validate voice clone creation preconditions.
`voice-clone-create`	`/voice-clone-create`	Create new voice clone with provider and DB persistence.
`voice-clone-delete`	`/voice-clone-delete`	Remove voice clone data and provider references.
`voices-list`	`/voices-list`	Return available voices respecting private/public entitlements.
`waitlist-signup`	`/waitlist-signup`	Register waitlist capture data.
`sts-live-voice-tts-session`	`/sts-live-voice-tts-session`	Live STS voice streaming orchestration for TTS style playback.
`sts-live-interpreter-session` (untracked)	`/sts-live-interpreter-session`	New live interpreter STS mode session bootstrap (migration surface).
`sts-live-interpreter-tts-session` (untracked)	`/sts-live-interpreter-tts-session`	New interpreter-to-TTS relay live path (session+stream handoff).
`sts-near-realtime-session`	`/sts-near-realtime-session`	Near-realtime translation session bootstrap with artifact snapshot points.
`sts-realtime-session`	`/sts-realtime-session`	Realtime STS session state orchestration.
`sts-realtime-finalize`	`/sts-realtime-finalize`	Finalize realtime artifact (tail stitching + final transcript consolidation).

8.4 Function file conventions and where behavior lives

For each function directory in backend/supabase/functions/<fn>/:

index.ts → HTTP binding, route registration, dependency creation.
handler.ts (where present) → pure validation/business orchestration.
validation.ts / validation_test.ts → request schema guard.
*_test.ts → unit tests.
extra files (e.g. pronunciation.ts, logic.ts, dispatch.ts, signature.ts) → helper logic/normalization.

8.5 Migrations and schema lifecycle

Migration	Responsibility
`001_core_schema.sql`	Baseline schema + startup tables.
`002_storage_bucket_and_policies.sql`	Storage bucket and RLS policy foundation.
`003_add_transcript_path_to_clips.sql`	Adds transcript path columns for clip metadata.
`004_category_limits_and_default_saved_tts.sql`	Category limits and default saved TTS settings.
`005_allow_transcript_text_mime.sql`	MIME/config for transcript text workflows.
`006_add_category_sort_order.sql`	Ordering support for category lists.
`007_harden_function_search_path.sql`	Harden postgres function search path behavior.
`008_entitlements_and_usage.sql`	Introduce entitlements + usage accounting.
`009_developer_account_allowlist.sql`	Allowlist mechanism for developer accounts.
`010_seed_developer_admin_account.sql`	Seed known admin/developer account metadata.
`011_atomic_usage_counter_increment.sql`	Atomic usage counter operations to reduce race.
`012_apple_billing_sync.sql`	Apple billing sync support objects.
`013_billing_webhook_foundation.sql`	Webhook persistence foundation.
`014_byok_credentials.sql`	BYOK credentials schema.
`015_voice_clone_ownership.sql`	Voice clone ownership constraints and metadata.
`016_voice_clone_sample_count_relax.sql`	Relaxation rules for sample-count restrictions.
`017_private_voice_access_controls.sql`	Access control for private voices.
`018_default_voice_public.sql`	Default public voice settings.
`019_developer_private_voice_access.sql`	Developer private voice access grants.
`020_voice_style_presets.sql`	Preset persistence schema.
`021_pronunciation_dictionary.sql`	Pronunciation dictionary table(s).
`022_batch_clip_order_update.sql`	Batch update semantics for clip ordering.
`023_pronunciation_dictionary_defaults.sql`	Seed/default dictionary values.
`024_seed_pronunciation_defaults_from_csv.sql`	Seed DB from CSV default pronunciations.
`025_waitlist_signups.sql`	Waitlist schema migration.
`026_billing_entitlement_mutation_log.sql`	Audit log for entitlement mutations.
`027_add_user_id_to_waitlist_signups.sql`	Adds user_id link on waitlist entries.
`028_soundboard_delete_atomicity.sql`	Soundboard delete atomic behavior hardening.
`029_soundboard_hard_delete_model.sql`	Hard delete model migration for sounds/clips.
`030_ai_data_sharing_agreement.sql`	Persistence of agreement/canary records.
`031_soundboard_clip_order_snapshots.sql`	Clip ordering snapshots for recovery/history.
`20260320054212_manual_test_subscription_override_users.sql`	Temporary/manual override migration.
`20260320054328_revert_manual_test_subscription_override_users.sql`	Revert manual override migration.
`20260320054551_reapply_manual_test_subscription_override_users.sql`	Reapply override migration.
`20260425223600_category_limits_by_entitlement.sql`	Entitlement-based category constraints.
`20260426153600_harden_category_limit_trigger.sql`	Trigger hardening around category limit mutation.
`20260501171000_subscription_gating_disablement.sql`	Temporary disablement and gating behavior.
`20260509000_grant_unrestricted_elevenlabs_access_user_37c4937d.sql`	Targeted feature entitlement grant.
`20260509120000_grant_unrestricted_elevenlabs_access_user_37c4937d.sql`	Grant variation; ensure one-time migration semantics.
`20260509121000_grant_gbpro_voice_access_user_37c4937d.sql`	GBPro access grant for target user.
`20260513150737_explicit_public_data_api_grants.sql`	Public API grants explicitness.
`20260514053144_harden_public_data_api_default_privileges.sql`	Tighten default API privilege behavior.
`20260517141816_keep_voice_clone_paid_tier_open.sql`	Paid-tier policy override for voice clone.
`20260517153725_app_bug_reports.sql`	Bug report tracking table migration.
`20260521051142_soundboard_one_level_hierarchy.sql`	Soundboard hierarchy simplification.
`20260521054500_relax_storage_path_user_uuid_versions.sql`	Storage path compatibility for versioning.
`20260521065428_grant_storage_path_user_id_execute.sql`	Storage permission for user-id path execution.
`20260522051142_soundboard_one_level_hierarchy.sql`	Duplicate entry in listing; verify idempotency.
`20260524030000_add_tts_defaults_to_user_settings.sql`	New defaults for TTS settings fields.
`20260526090000_soundboard_soft_delete_retention.sql`	Soft-delete retention policy.
`20260526090050_drop_soundboard_delete_functions_for_soft_delete.sql`	Remove function path incompatible with soft-delete flow.
`20260526090100_delete_soundboard_category_soft_function.sql`	Soft-delete category helper function migration.
`20260526090200_delete_soundboard_clip_soft_function.sql`	Soft-delete clip helper function migration.
`20260526090300_restore_soundboard_clip_function.sql`	Restore function for soft-deleted clips.
`20260526090400_restore_soundboard_category_function.sql`	Restore function for soft-deleted categories.
`20260526090500_purge_soundboard_trash_function.sql`	Trash cleanup function.
`20260526090600_soundboard_trash_function_grants.sql`	Permissions for trash management.
`20260526091000_add_soundboard_settings_to_user_settings.sql`	Add soundboard settings fields.
`20260526120000_add_sts_workflow_mode.sql`	Add workflow-mode setting for STS migration.
`20260527120000_add_near_realtime_sts.sql`	Near real-time STS metadata in schema.
`20260528180000_add_live_interpreter_sts.sql`	New live interpreter STS schema objects.
`20260601090000_soundboard_clip_generation_metadata.sql`	Clip generation metadata columns.
`20260620090000_keep_user_37c4937d_unlimited.sql`	Temporary unlimited quota for a target user.
`20260623090000_add_sts_workflow_mode.sql`	Additional STS workflow mode migration.
`20260623090100_create_sts_realtime_sessions.sql`	Realtime session table(s).
`20260623120000_add_sts_settings_overrides.sql`	STS settings override fields.
`20260627120000_add_near_realtime_sts.sql`	Additional near-realtime STS migration.
`20260627143000_add_sts_settings_overrides.sql`	Duplicate entry in listing; verify whether already applied.
`20260628180000_add_live_interpreter_sts.sql`	Companion migration for new live interpreter paths.
`20260628143000_add_sts_settings_overrides.sql`	Duplicate naming collision; check migration state.

For migration files with seemingly duplicate names in this repo snapshot, check DB history before editing (idempotency + ordering matters).

8.6 Backend tests and validation

Function-level unit tests exist in each function folder with _test.ts suffix.
Shared helper tests are in _shared.
End-to-end contracts for DB/public API appear in backend/supabase/tests/.
The web backend test files often import DB contracts to validate trigger/permission changes.

9) Shared docs and contract map (`docs/`)

Folder	What is here
`docs/contracts/`	Behavioral contracts used by parity checks and cross-surface expectations.
`docs/product/`	Feature plan docs and product-level target behavior.
`docs/ops/`	Release playbooks, deployment scripts, infra plans.
`docs/architecture/`	Data flow and layer diagrams.
`docs/design/`	Design references (e.g., Android visual references).
`docs/reference/`	This reference document and any adjacent deep references.

10) Change playbooks (where to edit)

10.1 iOS feature behavior change

Change iOS TTS defaults: ios/SpeakTrue/TTSViewModel.swift, ios/SpeakTrue/TextToSpeechView.swift, and backend default migration (20260524030000_add_tts_defaults_to_user_settings.sql).
Change iOS audio transport: ios/SpeakTrue/AudioRecorderService.swift, LiveVoiceAudioPlayer.swift, RealtimeSTTService.swift.
Change iOS agreement copy/flow: ios/SpeakTrue/AIDataSharingConsent*.swift and web parity docs under docs/contracts.

10.2 Android feature behavior change

Change Android STS behavior: android/app/src/main/java/com/speaktrue/features/sts/... + contracts in backend/supabase/functions/sts-* + docs/contracts parity assertions.
Change auth/session behavior: android/.../core/auth/*, features/auth/*, plus function/contract tests.
Change settings defaults: core/config/RuntimeConfig.kt, features/settings, and backend/.../user-settings-*..

10.3 Web runtime behavior change

Update legacy web endpoint behavior:
- route layer in web/python-web-app/src/routes
- service layer in web/python-web-app/src/services
- templates/js in web/python-web-app/templates and static
- tests in web/python-web-app/tests
Change JS compatibility path: web/python-web-app/static/js and runtime compatibility tests under tests/js.

10.4 Backend function behavior change

Quota logic: backend/supabase/functions/_shared/quotas.ts, usage.ts, corresponding migration for counters, and function-level consumers.
Voice catalog/provider access changes: voices-list, voice-clone-*, _shared/private-voice-access.ts, 019... / 018... migration files.
STS workflow additions: add new backend function under backend/supabase/functions, add migration for schema if needed, then parity update iOS/Android/web.
Contract updates: ensure matching docs in docs/contracts and UI tests update.

10.5 Migration-sensitive changes

Add migration file in backend/supabase/migrations with timestamp prefix.
Update any dependent backend function tests.
Update cross-surface setting defaults and feature toggles.
Update docs: docs/index.md + relevant contract/ops pages.

11) Deployment and runbook matrix

11.1 iOS

Open Xcode workspace (ios/SpeakTrue.xcodeproj), choose config, build on simulator/device.
Use signing/profile settings from project config and ensure config values in ios/Config/*.xcconfig are aligned.
For release verification: run parity-critical iOS tests and smoke signoff.

11.2 Android

Standard tasks from android/ scripts:
- build, install, screenshot, and smoke checks from android/scripts/.
CI uses .github/workflows/android-ci.yml.
Release path uses artifact generation scripts (build-release-apk.sh, build-release-bundle.sh, verify_android_release_bundle.py).

11.3 Backend (Supabase)

Local: start Supabase stack, run functions locally, run TS tests.
Migrations: apply SQL files in timestamped order with Supabase tooling.
Edge deployment: deploy function directories explicitly and confirm auth/claims policies.

11.4 Legacy web runtime

Local app startup: run via WSGI entrypoint and env injection.
Smoke flow: browser runtime tests in web/python-web-app/tests/js/*.mjs and API suites under web/python-web-app/tests/api.
Deploy target historically uses gunicorn/WSGI path from wsgi.py.
Static marketing pages use separate deploy path under web/marketing/.

11.5 CI and release scripts

GitHub workflows in .github/workflows include Android CI and deploy workflows.
Regression scripts under scripts/ correspond to checkpoints (verify_*.) and should be run for staged changes.

12) What to inspect first for common incidents

Auth breakage: AuthService.swift, AuthViewModel.kt, AuthService.kt, legacy_runtime_bootstrap_service and shared auth scripts.
Missing clip in soundboard: SoundboardService, SoundboardRepository, clip-order-batch, clip migration SQL.
STS tail/repeat bug: iOS STSVM + Android STSOrchestrator + backend sts-* finalize/session handlers.
Voice list not matching parity: voices-list function + language-recommend + Android/iOS voice catalog repos.
Subscription mismatch: shared entitlement helpers + billing webhook/sync functions + settings gates.

13) File governance and maintenance rules

Keep docs/index.md updated before major behavior changes.
Do not edit generated directories (android/SpeakTrue-debug.apk, media fixture sets) unless intentionally regenerating.
For any backend contract change:
1. Update migration (if needed).
2. Update function logic/tests.
3. Update web and native callers.
4. Update docs and contract tests.

14) Open questions and future extension areas

This document intentionally tracks source behavior, but does not enumerate every binary asset individually.
Add a dedicated subpage for every large directory when source churn exceeds this document’s update cadence.