SpeakTrue

SpeakTrue Backend Function Operations Map (Comprehensive Engineering Guide)

Last updated: 2026-06-29

This document is the high-precision backend-reference for engineers who need to change any Supabase edge function and immediately understand blast radius.

1) What this map covers

• Every function directory in backend/supabase/functions (excluding _shared).
• The exact files under each function directory.
• What each function is currently responsible for.
• Where edits should be mirrored in iOS, Android, or legacy web.
• The required verification surfaces for regression-safe changes.

All backend routes are exposed via Supabase Function URLs in the form:

/functions/v1/<directory-name>

For any function change, read:

• backend/supabase/functions/_shared/*
• the relevant handler/tests under that function directory
• impacted client code under ios/, android/, and/or web/python-web-app/
• migration SQL if persisted shape changed

2) Shared backend modules that affect almost every function

The following modules often need review even when editing one function:

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

3) Function-by-function map

Format:

• Route — /<function-dir>
• Surface — the feature group that typically consumes this API
• Files — tracked implementation/test files
• Status — implemented or scaffolded
• What it does — contract-level behavior

Route	Surface	Files	Status	What it does
/account-delete	auth/account lifecycle	index.ts, handler.ts, handler_test.ts	Implemented	Removes authenticated user account and/or user-owned resources through server-side privileged operations.
/billing-apple-sync	billing	index.ts, logic.ts, logic_test.ts	Partial/legacy	Reconciles Apple receipt sync payloads; helper-based implementation path, verify runtime route entry and parity with Apple notification path.
/billing-apple-notifications	billing	index.ts, handler.ts, handler_test.ts, deno.json, .npmrc	Implemented	Validates Apple store notifications and applies entitlement changes with deterministic handling for known event types.
/billing-google-play-sync	billing	index.ts, handler.ts, google-play-verifier.ts, google-play-verifier_test.ts, handler_test.ts	Implemented	Verifies/unwraps Google Play payload and maps entitlement/payment state to app billing policy.
/billing-stripe-webhook	billing	index.ts, dispatch.ts, dispatch_test.ts, logic.ts, logic_test.ts, persistence.ts, persistence_test.ts, signature.ts, signature_test.ts, validation.ts, validation_test.ts	Implemented	Verifies Stripe signature + event schema, dispatches event-specific handlers, persists event/transition state where needed.
/bug-report-submit	support	index.ts, handler.ts, handler_test.ts	Implemented	Captures user bug reports into backend persistence/ingest path for triage.
/byok-resolve	settings/provider config	index.ts, handler.ts, handler_test.ts	Implemented	Returns bring-your-own-key configuration/status without revealing raw secrets in the response.
/byok-upsert	settings/provider config	index.ts, handler.ts, handler_test.ts	Implemented	Creates or updates BYOK provider configuration and enablement state for user sessions.
/clip-order-batch	soundboard ordering	index.ts, handler.ts, handler_test.ts	Implemented	Applies ordered clip ordering mutations, typically after drag/drop reorder in clients.
/language-recommend	STT/STT/STS quality UX	index.ts, handler.ts, handler_test.ts	Implemented	Provides language recommendation payloads based on user context and usage policy.
/models-list	voice/model catalog	index.ts, handler.ts, handler_test.ts	Implemented	Returns model catalog and provider/model visibility after entitlement and policy filtering.
/pronunciation-dictionary	pronunciation/tts accuracy	index.ts, handler.ts, handler_test.ts	Implemented	CRUD + retrieval for user pronunciation overrides with validation semantics.
/quota-status	usage gating	index.ts, handler.ts, handler_test.ts	Implemented	Returns quota snapshots used by usage-limit UI and policy gating.
/soundboard-save-generated	soundboard persistence	index.ts, handler.ts, handler_test.ts	Implemented	Persists generated clip metadata + storage metadata for generated artifacts and returns saved clip contract.
/soundboard-delete	soundboard lifecycle	index.ts, handler.ts, handler_test.ts, delete_storage_error.ts, delete_storage_error_test.ts	Implemented	Deletes soundboard assets with storage cleanup and typed deletion errors.
/soundboard-clip-ingest	migration/scaffold	(no function files)	Scaffold only	Placeholder function directory for future migration ingest path. Do not route production traffic here.
/sts-live-voice-tts-session	live STS/voice	index.ts, handler.ts, handler_test.ts	Implemented	Starts live voice-to-speech session semantics and returns provider contract required by clients.
/sts-near-realtime-session	near-realtime STS	index.ts, handler.ts, handler_test.ts	Implemented	Initializes near-realtime STS context with persisted state for finalize path.
/sts-realtime-session	realtime STS	index.ts, handler.ts, handler_test.ts	Implemented	Creates/returns active realtime STS session context.
/sts-realtime-finalize	realtime STS	index.ts, handler.ts, handler_test.ts	Implemented	Finalizes realtime/near-realtime session, merging transcript and artifact metadata and returning artifact contract.
/sts-live-interpreter-session	interpreter (next-gen)	index.ts only	Scaffold only	Reserved migration target; runtime behavior undefined until handler implementation added.
/sts-live-interpreter-tts-session	interpreter (next-gen)	index.ts only	Scaffold only	Reserved migration target; runtime behavior undefined until handler implementation added.
/stt-transcribe	STT	index.ts, capture.ts, capture_test.ts, validation.ts, validation_test.ts, handler.ts, handler_test.ts	Implemented	Validates non-streaming STT request + provider invocation + optional capture telemetry + standardized response envelope.
/style-presets	settings / presets	index.ts, handler.ts, handler_test.ts	Implemented	Fetches and stores style preset configuration consumed by speech generation features.
/tts-generate	TTS core	index.ts, handler.ts, pronunciation.ts, pronunciation_test.ts, policy.ts, policy_test.ts, handler_test.ts	Implemented	Core text-to-speech contract path: validation, policy enforcement, pronunciation normalization, provider call, and artifact persistence.
/user-settings-get	settings	index.ts, handler.ts, handler_test.ts	Implemented	Fetches user settings including migration-safe defaults and compatibility fallbacks.
/user-settings-update	settings	index.ts, handler.ts, handler_test.ts	Implemented	Applies patch-based user settings updates with payload validation and response normalization.
/voice-clone-preflight	voice clone	index.ts, validation.ts, validation_test.ts, handler.ts, handler_test.ts	Implemented	Prepares/validates readiness checks before clone creation (file length, account status, prior constraints).
/voice-clone-create	voice clone	index.ts, validation.ts, validation_test.ts, telemetry.ts, telemetry_test.ts, handler.ts, handler_test.ts	Implemented	Executes provider-side voice clone creation and returns stable clone metadata + audit telemetry.
/voice-clone-delete	voice clone	index.ts, validation.ts, validation_test.ts, handler.ts, handler_test.ts	Implemented	Deletes user-owned voice clone entry and related provider references.
/voices-list	voice/model catalog	index.ts, handler.ts, handler_test.ts	Implemented	Returns voice list with ownership/private-access filtering and deterministic fallback ordering.
/waitlist-signup	marketing ops	index.ts, handler.ts, handler_test.ts	Implemented	Stores waitlist entries, de-duplicates by key and persists minimal metadata.

4) Cross-surface change impact matrix

Use this matrix before editing a function; it identifies likely client callsites and test areas.

4.1 Speech generation / voices (TTS + model catalog)

• Functions: tts-generate, voices-list, models-list, pronunciation-dictionary
• iOS callsites:
  • ios/SpeakTrue/TTSViewModel.swift
  • ios/SpeakTrue/AIProxyService.swift
  • ios/SpeakTrue/VoiceModelSelectionView.swift
• Android callsites:
  • android/app/src/main/java/com/speaktrue/features/tts/data/*
  • android/app/src/main/java/com/speaktrue/features/tts/presentation/TTSViewModel.kt
  • android/app/src/main/java/com/speaktrue/features/tts/ui/TTSScreen.kt
• Web callsites:
  • web/python-web-app/src/services/* compatibility seam
• tests:
  • backend: function tests in touched directory
  • iOS: ios/SpeakTrueTests/*TTS*
  • Android: TTS/presets/voice contract tests

4.2 STT / STS / live transcription flow

• Functions: stt-transcribe, sts-near-realtime-session, sts-realtime-session, sts-realtime-finalize, sts-live-voice-tts-session
• iOS callsites:
  • ios/SpeakTrue/STTViewModel.swift
  • ios/SpeakTrue/STSViewModel.swift
  • ios/SpeakTrue/RealtimeSTTService.swift
  • ios/SpeakTrue/LiveVoiceSTSService.swift
  • ios/SpeakTrue/AIProxyService.swift
• Android callsites:
  • android/app/src/main/java/com/speaktrue/features/stt/*
  • android/app/src/main/java/com/speaktrue/features/sts/data/*
  • android/app/src/main/java/com/speaktrue/features/sts/presentation/STSViewModel.kt
• Web callsites:
  • web/python-web-app/src/routes/stt.py
  • web/python-web-app/src/services/*
  • web/python-web-app/static/js/index_stt.js
  • web/python-web-app/static/js/index_sts_live_voice.js
• tests:
  • backend tests in affected function directories
  • web/python-web-app/tests/js/sts_*.mjs

4.3 Soundboard

• Functions: soundboard-save-generated, soundboard-delete, clip-order-batch, soundboard-clip-ingest
• iOS callsites:
  • ios/SpeakTrue/SoundboardViewModel.swift
  • ios/SpeakTrue/SoundboardCacheManager.swift
  • ios/SpeakTrue/SoundboardCacheIndex.swift
  • ios/SpeakTrue/AIProxyService.swift
• Android callsites:
  • android/app/src/main/java/com/speaktrue/features/soundboard/data/*
  • android/app/src/main/java/com/speaktrue/features/soundboard/presentation/SoundboardViewModel.kt
• Web callsites:
  • 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

4.4 Settings and profile

• Functions: user-settings-get, user-settings-update, quota-status
• iOS callsites:
  • ios/SpeakTrue/UserSettingsSyncService.swift
  • ios/SpeakTrue/UserSettings.swift
  • ios/SpeakTrue/SettingsTabView.swift
  • ios/SpeakTrue/SettingsView.swift
• Android callsites:
  • android/app/src/main/java/com/speaktrue/features/settings/data/*
  • android/app/src/main/java/com/speaktrue/features/settings/presentation/SettingsViewModel.kt
• Web callsites:
  • web/python-web-app/src/services/user_settings_service.py
  • web/python-web-app/src/routes/settings.py

4.5 Billing and entitlements

• Functions: billing-apple-notifications, billing-apple-sync, billing-google-play-sync, billing-stripe-webhook, quota-status, byok-*
• iOS/Android/Web: all billing-sensitive feature surfaces; verify with feature flags and entitlements.
• required migrations:
  • backend/supabase/migrations/*
• required shared modules:
  • _shared/subscription-gating-config.ts
  • _shared/entitlements.ts
  • _shared/billing-entitlement-policy.ts

5) What to change when modifying one function

1. Update the function handler + tests in its directory.
2. Update any caller payload mapping in iOS/Android/web.
3. Update shared contract types if response shape changes.
4. Update migration SQL only when persisted schema changes.
5. Update parity tests and surface tests that validate affected fields.
6. Add/adjust negative-path tests for auth/validation/ownership failures.

6) Deployment and release gates

• Backend contracts:
  • bash scripts/coverage_backend_contracts.sh
  • bash scripts/regression_migration_paths.sh
  • platform-specific smoke checks in client repos
• DB migration updates:
  • add SQL migration file(s) under backend/supabase/migrations/
  • document why any default value behavior changed

7) Editing notes for scaffolded/new routes

If you create a new function or convert a scaffold into an implementation:

• Keep the directory shape as:
  • index.ts
  • handler.ts
  • handler_test.ts
• Add request/response helper tests for:
  • missing auth
  • invalid payload
  • permission/ownership failure
  • success path
• Run the backend contract gate and at least one client-side smoke test that consumes the function.