Runtime Configuration Reference

Use this page to document the local-development and deployment configuration contract.

Truth Sources

1. core/backend/.env.example
2. core/frontend/.env.example
3. docker-compose.yml
4. scripts/setup-workspace.mjs
5. workspace manifests and runtime scripts

Current Finance Variables

Backend

Variable	Default	Purpose
PORT	3001	Backend HTTP port
SERVICE_NAME	finance-backend	Logical service name for health responses
METRICS_PREFIX	finance_	Prefix for default Prometheus metrics
DATABASE_TYPE	postgres	Database driver, either postgres or local development sqljs
DATABASE_FILE	finance.local.sqlite	Local SQL.js file used when DATABASE_TYPE=sqljs
DATABASE_HOST	localhost	PostgreSQL host
DATABASE_PORT	5433	PostgreSQL host port
DATABASE_NAME	finance_app	PostgreSQL database name
DATABASE_USER	postgres	PostgreSQL user
DATABASE_PASSWORD	postgres	PostgreSQL password
TYPEORM_SYNCHRONIZE	true	Local development schema synchronization
TYPEORM_LOGGING	false	TypeORM SQL logging toggle
AUTH_JWT_SECRET	required outside local defaults	HMAC secret used to sign bearer sessions and Google OAuth state
AUTH_SESSION_TTL_SECONDS	604800	Bearer session lifetime in seconds
FRONTEND_APP_URL	http://localhost:5173	Frontend origin used by Google SSO redirects
GOOGLE_CLIENT_ID	empty	Google OAuth client ID
GOOGLE_CLIENT_SECRET	empty	Google OAuth client secret
GOOGLE_REDIRECT_URI	http://localhost:3001/auth/google/callback	OAuth redirect URI configured in Google Cloud
GEMINI_API_KEY	empty	Optional Gemini API key for async invoice classification; empty or disabled uses local-rule fallback
GEMINI_MODEL	gemini-2.5-flash	Gemini model used by async invoice classification jobs
GEMINI_PROVIDER	developer	Gemini provider, either developer for API-key calls or vertex for Google Cloud Vertex AI
GEMINI_VERTEX_PROJECT_ID	empty	Google Cloud project used when GEMINI_PROVIDER=vertex
GEMINI_VERTEX_LOCATION	us-central1	Vertex AI location used when GEMINI_PROVIDER=vertex
VOICE_COMMAND_GEMINI_MODEL	gemini-2.5-flash-lite	Low-cost Gemini model used to turn short voice transcripts into confirmable app actions
SPEECH_GOOGLE_PROJECT_ID	empty	Google Cloud project for Speech-to-Text V2; staging sets this to the same project as Vertex AI
SPEECH_GOOGLE_LOCATION	global	Speech-to-Text V2 recognizer location
SPEECH_RECOGNITION_MODEL	latest_long	Speech-to-Text model for natural mobile voice commands, including brief openings or pauses before the actual command
IMPORT_JOB_WORKER_ENABLED	true	Enables the backend worker that processes queued import classification jobs

Frontend

Variable	Default	Purpose
VITE_API_BASE_URL	http://localhost:3001	Backend API origin used by the finance frontend

Local Services

Service	Default	Purpose
PostgreSQL	localhost:5433	Finance relational database
Redis	localhost:6380	Support service for future cache/queue concerns

When Docker or PostgreSQL is unavailable, local feature testing can use DATABASE_TYPE=sqljs without starting npm run services:up. Production and shared environments should continue to use PostgreSQL.

GCP Staging

The staging environment is managed by Terraform under infra/gcp/ and deploys:

• Cloud Run backend
• Cloud Run static frontend
• Cloud Run static Docusaurus docs
• Cloud SQL PostgreSQL
• Secret Manager
• Artifact Registry
• GitHub Workload Identity Federation

Staging intentionally uses TYPEORM_SYNCHRONIZE=true until production-grade migrations are added.

Current staging service names:

Service	Purpose
financeapp-staging-web	React frontend
financeapp-staging-api	NestJS API
financeapp-staging-docs	Docusaurus docs

Runtime operator procedures are maintained in docs/STAGING_RUNBOOK.md.