# Configuration

This document covers all configuration options for the Pediatric AI Scribe, including environment variables, database-backed settings, and the admin panel.

---

## Environment Variables

Environment variables are set in the `.env` file or passed to the Docker container. They are read at startup.

### AI Provider

| Variable | Description |
|----------|-------------|
| `AI_PROVIDER` | AI backend: `openrouter`, `bedrock`, `azure`, `vertex`, or `litellm`. |
| `OPENROUTER_API_KEY` | API key for OpenRouter. |
| `AWS_BEDROCK_REGION` | AWS region for Bedrock (e.g., `us-east-1`). |
| `AWS_ACCESS_KEY_ID` | AWS access key (shared by Bedrock and Transcribe). |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key (shared by Bedrock and Transcribe). |
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI resource endpoint URL. |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key. |
| `AZURE_DEPLOYMENT_NAME` | Azure OpenAI deployment/model name. |
| `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version string. |
| `GOOGLE_VERTEX_PROJECT` | Google Cloud project ID for Vertex AI. |
| `GOOGLE_VERTEX_LOCATION` | Google Cloud region for Vertex AI (e.g., `us-central1`). |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to the Google service account JSON key file. |
| `LITELLM_API_BASE` | Base URL of the LiteLLM proxy server. |
| `LITELLM_API_KEY` | API key for LiteLLM proxy authentication. |

### Transcription (Speech-to-Text)

| Variable | Description |
|----------|-------------|
| `TRANSCRIBE_PROVIDER` | STT backend: `google`, `aws`, `local`, `openai`, or `litellm`. Auto-detects if unset (google > aws > openai). |
| `OPENAI_API_KEY` | API key for OpenAI Whisper. |
| `GOOGLE_STT_MODEL` | Google Gemini model for transcription (default: `gemini-2.0-flash`). |
| `AWS_TRANSCRIBE_MEDICAL` | Enable Amazon Transcribe Medical mode (`true`/`false`). |
| `AWS_TRANSCRIBE_SPECIALTY` | Medical specialty: `PRIMARYCARE`, `CARDIOLOGY`, `NEUROLOGY`, `ONCOLOGY`, `RADIOLOGY`, `UROLOGY`. |
| `WHISPER_BINARY` | Path to the local whisper binary (`whisper.cpp` or `faster-whisper`). |
| `WHISPER_MODEL_SIZE` | Local Whisper model size: `tiny`, `base`, `small`, `medium`, `large`. |
| `WHISPER_MODEL_PATH` | Path to the local Whisper model file. |
| `WHISPER_LANGUAGE` | Language code for local Whisper (e.g., `en`). |
| `WHISPER_THREADS` | Number of CPU threads for local Whisper. |
| `LITELLM_STT_MODEL` | Model name for LiteLLM-routed transcription. |

### Text-to-Speech

| Variable | Description |
|----------|-------------|
| `GOOGLE_TTS_VOICE` | Google Cloud TTS voice name (e.g., `en-US-Journey-F`). |
| `ELEVENLABS_API_KEY` | API key for ElevenLabs TTS. |
| `LITELLM_TTS_MODEL` | Model name for LiteLLM-routed TTS. |
| `LITELLM_TTS_VOICE` | Voice name for LiteLLM-routed TTS. |

### Embeddings

| Variable | Description |
|----------|-------------|
| `EMBEDDING_MODEL` | Embedding model name (default: Vertex AI `text-embedding-005`). |
| `EMBEDDING_DIMENSIONS` | Embedding vector dimensions (default: `768`). |

### Application

| Variable | Description |
|----------|-------------|
| `PORT` | HTTP listen port (default: `3000`). |
| `APP_URL` | Public-facing base URL of the application. |
| `JWT_SECRET` | Secret key for signing JWT tokens. |
| `SESSION_SECRET` | Secret key for session cookies. |
| `DATABASE_URL` | Full PostgreSQL connection string. |
| `DB_PASSWORD` | Database password (used if `DATABASE_URL` is not set). |

### Email (SMTP)

| Variable | Description |
|----------|-------------|
| `SMTP_HOST` | SMTP server hostname. |
| `SMTP_PORT` | SMTP server port. |
| `SMTP_USER` | SMTP authentication username. |
| `SMTP_PASS` | SMTP authentication password. |
| `SMTP_FROM` | Sender address for outgoing emails. |

### Security

| Variable | Description |
|----------|-------------|
| `TURNSTILE_SITE_KEY` | Cloudflare Turnstile site key for bot protection. |
| `TURNSTILE_SECRET_KEY` | Cloudflare Turnstile server-side secret key. |

### Integrations

| Variable | Description |
|----------|-------------|
| `NEXTCLOUD_URL` | Nextcloud instance URL for WebDAV file access. |
| `S3_BUCKET` | S3 bucket name for file storage. |
| `S3_REGION` | S3 bucket region. |
| `S3_PREFIX` | Key prefix (folder) within the S3 bucket. |
| `S3_ENDPOINT` | Custom S3 endpoint URL (for S3-compatible storage like MinIO). |
| `S3_ACCESS_KEY_ID` | S3 access key. |
| `S3_SECRET_ACCESS_KEY` | S3 secret key. |
| `S3_FORCE_PATH_STYLE` | Use path-style S3 URLs instead of virtual-hosted (`true`/`false`). Required for most S3-compatible providers. |

---

## Database-Backed Settings

Runtime settings are stored in the `app_settings` table and can be modified through the admin panel without restarting the application.

### Caching

Settings are cached **in memory for 2 minutes**. The cache is **invalidated immediately on write**, so changes made through the admin panel take effect right away.

### Setting Keys

#### Registration and Site

| Key | Description |
|-----|-------------|
| `registration_enabled` | Allow new user registration (`true`/`false`). |
| `site.name` | Display name of the application. |
| `site.auto_delete_days` | Number of days after which encounter data is automatically deleted. |

#### Announcements

| Key | Description |
|-----|-------------|
| `announcement.text` | Banner message text displayed to all users. |
| `announcement.type` | Banner style: `info`, `warning`, `error`, or `success`. |

#### Feature Flags

| Key Pattern | Description |
|-------------|-------------|
| `feature.*` | Toggle individual features on or off. |

#### SMTP (Overrides Environment)

| Key Pattern | Description |
|-------------|-------------|
| `smtp.host`, `smtp.port`, `smtp.user`, `smtp.pass`, `smtp.from` | SMTP configuration. Overrides the corresponding environment variables when set. |

#### Email Templates

| Key Pattern | Description |
|-------------|-------------|
| `email.*.subject` | Email subject line template. |
| `email.*.body` | Email body template. |

#### OIDC / SSO

| Key | Description |
|-----|-------------|
| `oidc.enabled` | Enable OpenID Connect authentication (`true`/`false`). |
| `oidc.issuer` | OIDC provider issuer URL. |
| `oidc.clientId` | OIDC client ID. |
| `oidc.clientSecret` | OIDC client secret. |
| `oidc.buttonLabel` | Label for the SSO login button. |
| `oidc.disableLocalAuth` | Hide the local login form when SSO is enabled. |

#### AI and Model Configuration

| Key | Description |
|-----|-------------|
| `stt.model` | Default speech-to-text model. |
| `tts.model` | Default text-to-speech model. |
| `tts.voice` | Default text-to-speech voice. |
| `models.default` | Default AI model for note generation. |
| `prompt.*` | AI prompt overrides. Each key corresponds to a specific prompt template. |
| `embeddings.*` | Embedding model and dimension configuration. |

---

## Admin Panel Settings

The admin panel provides a web interface for managing the application without editing configuration files.

### User Management

- List all registered users.
- Verify unverified accounts.
- Disable or re-enable user accounts.
- View per-user usage statistics.

### Registration

- Enable or disable new user registration globally.

### Announcement Banner

- Set banner text displayed at the top of the application.
- Choose banner type: `info`, `warning`, `error`, or `success`.

### SMTP Configuration

- Configure SMTP settings through the UI.
- These settings override the corresponding `.env` values when set.

### OIDC / SSO Configuration

- Enable or disable OpenID Connect authentication.
- Configure issuer URL, client ID, client secret, and button label.
- Option to disable local authentication entirely when SSO is active.

### AI Prompts

- View the default prompt templates used for note generation.
- Override any prompt with custom text.
- Reset overridden prompts back to their defaults.

### Model Management

- Enable or disable available AI models.
- Set the default model for new users.
- Add custom models with cost and category metadata.

### TTS and STT Configuration

- Test TTS and STT providers from the admin panel.
- Configure default TTS voice and STT model for all users.