SpeakTrue

SpeakTrue Repository Total Engineering Atlas

Last updated: 2026-06-29

This is the one-stop engineer reference for a complete first-contact understanding of the repository. It is designed so a new contributor can start from this file and make safe edits without searching outside docs/.

1) What this atlas is for

Use this document when you need:

If you need raw file-by-file descriptions, this atlas intentionally points to the canonical inventories:

For backend function contracts and behavior details, use:

2) Mandatory read order before edits

Before any behavior change, open in this exact order:

  1. README.md
  2. AGENTS.md
  3. docs/index.md
  4. docs/contracts/speech-workflow-contract.md
  5. docs/contracts/native-speech-parity-anchor.md
  6. docs/reference/repository-total-engineering-atlas.md (this file)
  7. all affected surface inventories (ios-file-inventory.md, android-file-inventory.md, web-file-inventory.md)
  8. any impacted backend function map (backend-functions-*)
  9. all affected runbooks in docs/ops/*

Then open the exact files you will edit.

3) Repository layout and ownership model

4) Golden source-of-truth map (file-level behavior ownership)

4.1 iOS: full file-level ownership path

Use docs/reference/ios-file-inventory.md whenever you need explicit ownership by path.

High-level map:

4.2 Android: full file-level ownership path

Use docs/reference/android-file-inventory.md whenever you need exact per-path behavior.

High-level map:

4.3 Web: full file-level ownership path

Use docs/reference/web-file-inventory.md for per-file ownership.

High-level map:

4.4 Backend: function and migration map (what to inspect)

Use:

Primary boundaries:

5) Backend function behavior matrix (all endpoints)

Function endpoints are available at /functions/v1/<directory-name>.

5.1 Auth, account, entitlement and billing

5.2 Settings, quotas, profile, BYOK

5.3 TTS catalog + generation behavior

5.4 STT / STS behavior

5.5 Soundboard

5.6 Voice clone

5.7 Support / platform health

6) Where to edit when asked “I need to change X / Y / Z?”

6.1 Change TTS text-to-speech behavior

Edit:

Validation:

6.2 Change STT / STS behavior

Edit:

Validation:

6.3 Change soundboard behavior (ordering, persistence, delete)

Edit:

6.4 Change voice clone flow

Edit:

6.5 Change account, auth, consents, or agreements

6.6 Add a new backend endpoint

  1. Create backend/supabase/functions/<new-name>/{index.ts,handler.ts,tests...}.
  2. Add migration changes if persistent schema is required.
  3. Add/adjust client callsites in all surfaces that consume endpoint.
  4. Add/update contract tests in each surface.
  5. Update this atlas + function maps and run regression scripts.

7) Deployment and verification map

7.1 iOS

7.2 Android

7.3 Backend

7.4 Legacy web runtime

7.5 Marketing site

8) High-signal development workflow

  1. Identify surface and behavior path (iOS/Android/Web/Backend).
  2. Use this atlas to open all affected files from inventories/maps.
  3. Edit backend contracts before or with client payload changes.
  4. Update tests in the same surface pass.
  5. Update docs where behavior or files changed.
  6. Run the smallest safe verification set for touched surfaces.
  7. Run git diff --check before handoff.

9) Command matrix

10) On-call / first-response triage for regressions