Staging Runbook
Finance App staging runs in Google Cloud project finance-app-499623.
Services
| Service | Purpose |
|---|---|
financeapp-staging-web | React frontend |
financeapp-staging-api | NestJS backend |
financeapp-staging-docs | Docusaurus docs |
The Deploy Staging workflow prints the current public custom-domain URLs, fallback run.app URLs, and required DNS records after Terraform applies.
Public URLs
| Surface | URL |
|---|---|
| Frontend | https://luvi.solutions |
| Backend | https://api.luvi.solutions |
| Docs | https://docs.luvi.solutions |
Staging also uses Vertex AI Gemini for invoice classification and short voice-command interpretation, plus Speech-to-Text V2 latest_long for natural voice transcription. The runtime service account has roles/aiplatform.user and roles/speech.client.
Deploy
Push to main or run the Deploy Staging workflow manually. The workflow validates the repo, applies Terraform, writes Secret Manager versions from GitHub Actions secrets, builds images, deploys Cloud Run services, and prints URLs.
OAuth
Use Google OAuth client ID:
383429529163-s7cmatr4uhd4il898a9iujptk06n44vm.apps.googleusercontent.com
Authorized JavaScript origin:
https://luvi.solutions
Authorized redirect URI:
https://api.luvi.solutions/auth/google/callback
Custom Domain DNS
Cloud Run domain mappings are configured for luvi.solutions, api.luvi.solutions, and docs.luvi.solutions. The deploy workflow prints the DNS records to copy into GoDaddy after Terraform creates the mappings.
Secrets
Secret payloads live in GitHub Actions secrets and are written to Secret Manager during deployment. Do not commit secret values.
Staging secret names include STAGING_DB_PASSWORD, STAGING_AUTH_JWT_SECRET, STAGING_GOOGLE_CLIENT_SECRET, and optional STAGING_GEMINI_API_KEY. Staging defaults to Vertex AI through the Cloud Run service account, so the Gemini API key is only needed if the provider is switched to Developer API mode.
Observability
Use /health for smoke checks and /ops/metrics for Prometheus-compatible metrics. Backend responses include x-request-id, and normalized error responses include requestId for log correlation.
Async invoice/PDF import classification emits structured lifecycle logs for queued, started, completed, and fallback-completed jobs without logging invoice row contents, extracted PDF text, prompts, model payloads, or user financial data.
Voice commands emit VoiceCommandInterpreted and VoiceCommandConfirmed lifecycle logs with metadata only. Do not log raw audio, transcripts, prompts, descriptions, category names, merchant names, or generated finance details.
The full operator runbook is maintained in root docs at docs/STAGING_RUNBOOK.md.