proxmox/docs/04-configuration/RECOMMENDATIONS_TTS_GITEA_PHOENIX.md

Recommendations: TTS, Gitea, Phoenix, and Operations

Last Updated: 2026-02-10
Scope: virtual-banker TTS, Phoenix deployment, Gitea, and related operations.

---

1. TTS and Phoenix

Implemented

• Configurable base URL — Use TTS_BASE_URL (or PHOENIX_TTS_BASE_URL with USE_PHOENIX_TTS=true) to point at Phoenix; no code change.
• Optional auth header — TTS_AUTH_HEADER_NAME / TTS_AUTH_HEADER_VALUE for Phoenix Bearer (or other) auth.
• Health check — tts.Service.Health(ctx) calls GET {baseURL}/../health when not using ElevenLabs; wire into readiness.
• Decision table — In the virtual-banker repo see backend/tts/README.md for which backend is used given env.
• Phoenix API contract — PHOENIX_TTS_API_CONTRACT.md defines required endpoints (sync, stream, health).

Additional recommendations

• Rate limiting / cost — When using ElevenLabs, track usage (chars or requests) and consider rate limiting in-app or in Phoenix to avoid cost overruns.
• Timeouts and resilience — Client already uses 30s timeout and retries for sync. Consider a circuit breaker (e.g. after N failures, stop calling TTS for a cooldown) to avoid cascading failures.
• Structured logging — Log TTS provider (ElevenLabs vs Phoenix), latency, and errors (without logging TTS_API_KEY or auth values) for debugging and monitoring.
• API versioning — Phoenix TTS should version the path (e.g. /v1/...) so you can add /v2 later without breaking existing clients.
• Fallback — Optional: if Phoenix is down, fall back to ElevenLabs when both are configured (e.g. try Phoenix first, on failure or health error use ElevenLabs). Requires explicit design (env flags, health checks).
• Secrets — Never log or expose TTS_API_KEY / ELEVENLABS_API_KEY / TTS_AUTH_HEADER_VALUE. In production use a secret manager (e.g. Phoenix env, Vault) and inject into env.

---

2. Gitea and repos

Implemented

• Push all projects — From proxmox root: bash scripts/dev-vm/push-all-projects-to-gitea.sh; includes virtual-banker. See EXPLORER_MONOREPO_GITEA_PUSH.md.
• Labels — apply-gitea-labels.sh creates project/virtual-banker (and others). Apply project/virtual-banker and domain/api to the virtual-banker repo in Gitea (Settings → Labels).
• virtual-banker CI — .gitea/workflows/ci.yml in virtual-banker runs go build and go test on push/PR.

Additional recommendations

• Branch protection — Enable branch protection for master/main on virtual-banker (and other key repos); require PR and passing CI. See GITEA_BRANCH_PROTECTION.md if present.
• Renovate / Dependabot — Consider Renovate or similar for virtual-banker (Go deps) so security and version updates are automated. See RENOVATE_GITEA_SETUP.md if present.

---

3. virtual-banker deployment and config

Implemented

• .env.example — virtual-banker root has .env.example with TTS_*, ELEVENLABS_*, USE_PHOENIX_TTS, DATABASE_URL, REDIS_URL, PORT. Copy to .env and set values; do not commit .env.
• Feature flag — USE_PHOENIX_TTS=true (or 1) forces Phoenix TTS; use TTS_BASE_URL or PHOENIX_TTS_BASE_URL.

Additional recommendations

• Readiness endpoint — Expose a /ready (or extend /health) that calls tts.Service.Health(ctx) when TTS is configured, so Kubernetes or load balancers only send traffic when TTS backend is up.
• Monitoring — Track TTS latency (e.g. existing RecordTTSLatency), error rate, and provider (ElevenLabs vs Phoenix) in metrics/dashboards so you can detect regressions and compare backends.

---

4. Reuse: TTS as a standalone module

Implemented

• Same interface, swap endpoint — Other projects can depend on virtual-banker’s backend/tts package and use NewElevenLabsTTSServiceWithOptions / NewElevenLabsTTSServiceWithOptionsFull with any base URL and auth.

Additional recommendations

• Standalone tts-client repo — If multiple repos (outside virtual-banker) will use this client, consider extracting the tts package into a small Go module (e.g. github.com/d-bis/tts-client). virtual-banker would then depend on that module, and others can use it without pulling in virtual-banker. Reduces coupling and clarifies ownership.
• Visemes — Current visemes are client-side approximation. For better lip-sync, add a Phoenix endpoint (or separate service) that returns phoneme/viseme timings and extend the client to call it when TTS_BASE_URL is set.

---

5. Quick reference

Topic	Doc / location
Which TTS backend?	virtual-banker backend/tts/README.md (decision table)
Phoenix TTS API contract	PHOENIX_TTS_API_CONTRACT.md
Push all projects to Gitea	EXPLORER_MONOREPO_GITEA_PUSH.md
Gitea labels and structure	GITEA_ORG_STRUCTURE.md
virtual-banker env vars	virtual-banker repo: .env.example
virtual-banker CI	virtual-banker repo: .gitea/workflows/ci.yml

---

6. Checklist (optional)

• Apply Gitea labels to virtual-banker (project/virtual-banker, domain/api) after running apply-gitea-labels.sh
• Configure Phoenix TTS to implement the contract in PHOENIX_TTS_API_CONTRACT.md and expose GET /health
• Set TTS env (or secrets) in Phoenix/deployment so virtual-banker uses Phoenix when desired
• Wire tts.Health() into readiness probe or /ready if you need TTS-up before accepting traffic
• Add monitoring for TTS latency and errors
• Consider extracting tts into a standalone Go module if multiple services will depend on it