SpeakTrue

SpeakTrue Repository Operator Manual (2026-06-29)

This is the master first-contact reference for new engineers, on-call responders, and release operators.

1) What this manual is for

It is designed to answer:

It is intentionally verbose and concrete. It is also intended to be updated every time behavior changes.

2) System architecture at a glance

3) Repository quick map

.
├── ios/                     # native SwiftUI app (iOS surface)
├── android/                 # native Compose app (Android surface)
├── web/
│   ├── marketing/           # static marketing + callbacks
│   └── python-web-app/      # legacy Flask web app runtime
├── backend/supabase/        # edge function contracts + migrations
├── scripts/                 # regression and release evidence scripts
├── .github/workflows/       # CI/deploy/workflow automation
└── docs/                    # architecture, contracts, operations

4) Canonical per-file inventories to keep open

The following files already enumerate every tracked file in those trees:

Use this operator manual for intent and change flow.

Use the inventories when you need exact ownership + file-by-file description. Use the onboarding reference for first-contact workflows, deployment-first change planning, and where-to-change guidance.

5) Configuration and environment boundaries

5.1 iOS

5.2 Android

5.3 Legacy web runtime

5.4 Backend (Supabase)

6) iOS: what does each major layer own?

6.1 Core startup and app shell

6.2 Services and cross-cutting modules

6.3 Feature-specific layers

TTS

STT / STS

Soundboard

Voice clone / pronunciation

6.4 iOS settings and UI foundation

6.5 iOS test boundaries

6.6 iOS change recipes

1) Change TTS UX defaults (speed/quality/voice/model defaults):

2) Add/remove an iOS speech workflow mode:

3) Fix or change account deletion path:

7) Android: major ownership and behavior split

7.1 Core startup and app graph

7.2 Core modules

7.3 Feature modules

7.4 Android change recipes

1) Add a backend field to user settings:

2) Change voice list behavior or sorting rules:

3) Update STS workflow path handling:

4) Change soundboard ordering rules:

7.5 Android test boundaries

8) Web surface (legacy Flask + marketing)

8.1 Surface split

8.2 Marketing ownership

8.3 Python web entry + bootstrap ownership

8.4 Service route boundaries

Routes

Services

8.5 Web change recipes

1) Add a new user route or payload field:

2) Move behavior out of compatibility shim:

3) Adjust marketing-only content/copy:

9) Backend functions: complete contract-oriented map

All function directories are under backend/supabase/functions/.

9.1 Shared backend helpers

9.2 Edge function behavior matrix

The table below is the canonical high-level behavior map:

Function directory Responsibility
account-delete Delete user account + related dependent records in DB/storage through backend-guarded logic.
billing-apple-sync Process Apple Billing sync payloads; update entitlement state.
billing-apple-notifications Handle Apple server notifications and mutate entitlement/log trails.
billing-google-play-sync Process Google Play subscription events and entitlement updates.
billing-stripe-webhook Process Stripe webhook events and map to internal entitlement state.
bug-report-submit Accept and persist bug telemetry payloads for support triage.
byok-resolve Resolve BYOK credential material path/metadata for a user.
byok-upsert Upsert BYOK material and persist metadata.
clip-order-batch Apply atomic batch updates to soundboard ordering metadata.
language-recommend Recommend supported language list for speech flows.
models-list Return available model list (tts/stt/etc. as surfaced by clients).
pronunciation-dictionary Read/update dictionary entries and normalization behavior.
quota-status Return current user usage and quota summary.
soundboard-save-generated Persist generated clip metadata and artifact references for soundboard.
soundboard-delete Delete soundboard entries and associated storage/metadata safely.
soundboard-clip-ingest Currently present but no implementation files in this snapshot.
stt-transcribe Convert audio payloads to transcript and return normalized result envelope.
style-presets Read/write style preset metadata.
tts-generate Core synthesis function: input validation, provider invocation, artifact persistence/paths.
user-settings-get Read user settings with defaults and compatibility fallback.
user-settings-update Patch and persist user settings and setting diffs.
voice-clone-preflight Validate prerequisites and permissions before voice-clone creation.
voice-clone-create Create new user voice clone and persist metadata + provider link.
voice-clone-delete Delete voice clone and clean provider metadata.
voices-list Return voice catalog entries allowed by entitlement and platform restrictions.
waitlist-signup Store waitlist interest records.
sts-live-voice-tts-session Live STS session orchestration for direct speech-to-voice path.
sts-live-interpreter-session Live interpreter session bootstrap (newer migration path).
sts-live-interpreter-tts-session Interpreter-to-tts relay endpoint for live interpreter STS mode.
sts-near-realtime-session Near-realtime STS path bootstrap and session metadata lifecycle.
sts-realtime-session Realtime STS session orchestration and state transitions.
sts-realtime-finalize Finalize realtime STS artifact, dedupe tail/repeat behavior, and finalize transcript/artifact output.

9.3 Suggested file path rules per function

For each function directory:

9.4 Function-caller map (non-exhaustive but practical)

Use existing tests to confirm payload schema before editing:

10) Database and migration map

10.1 Migration structure

10.2 Safe migration-edit protocol

  1. Add numbered migration file.
  2. Ensure function callers and DB functions still align with payloads.
  3. Update test fixtures if RLS/trigger contracts changed.
  4. Run contract gates from section 11 before merge.

11) Verification and command playbook

Use the smallest set that covers your change surface.

11.1 iOS

11.2 Android

11.3 Backend + migrations

11.4 Legacy web runtime

11.5 Marketing site

12) CI and deployment matrix

12.1 GitHub workflows

12.2 Deployment decision matrix

13) Where to edit for common requests

This section is the practical “what file changes when” guide.

1) Change a UI flow in iOS

2) Change a UI flow in Android

3) Change backend API contract

4) Add or modify a migration

5) Fix cross-surface parity issue

6) Debug auth/session issues

14) Incident triage checklist

  1. Auth broken:
    • iOS: AuthService + AuthState
    • Android: core/auth/*
    • Backend: _shared/auth-context.ts and related user settings functions.
  2. Clip missing in soundboard:
    • iOS: CloudStorageService + Soundboard* files.
    • Android: features/soundboard/*Repository.kt.
    • Web: services/soundboard_service.py, routes/soundboard.py, migration history for soft delete/trash.
    • Backend: clip-order-batch, soundboard-save-generated, soundboard-delete.
  3. STS tail/repeat mismatch:
    • Android: features/sts/* and tests.
    • iOS: STSViewModel and RealtimeSTTService.
    • Backend: sts-* functions and quota/auth state around session lifecycle.
  4. Voice list mismatch:
    • Check entitlements + private voice logic and voices-list contract.

15) Appended operational references

Keep this manual current by updating it whenever any file in this list is changed.