{"repo": "aptx-health/ot-notes", "files": {"docs/environment-variables.md": {"9ceb81a0523845ac9ea12099c6cfd163568380dc": {"t": 1785674597.3696258, "n": 3870, "h": "7d4ad14160f71847", "c": "# Environment Variable Management\n\n## AI Provider Architecture\n\nThe application uses **separate API keys for different AI functions**:\n\n- **OPENAI_API_KEY**: Used exclusively for voice transcription via Whisper API\n- **DEEPINFRA_API_KEY**: Used for text generation and AI workflows (primary provider)\n- **LANGFUSE_SECRET_KEY/PUBLIC_KEY**: Used for AI observability and prompt management\n\n## Organization Management\n\nThe application uses **environment-based organization assignment** for different deployment environments:\n\n- **DEFAULT_ORG_ID**: UUID of default organization for user assignment\n- **DEFAULT_ORG_NAME**: Display name of the default organization\n\n### Environment-Based Behavior\n\n**Development Environment**:\n```bash\nDEFAULT_ORG_ID=\"550e8400-e29b-41d4-a716-446655440000\"\nDEFAULT_ORG_NAME=\"OT Notes Development\"\n```\n- All new users automatically assigned to shared development organization\n- Simplifies development workflow with consistent org context\n- Easy to reset and test with multiple dev accounts\n\n**Development Environment** (including dev branch deployments):\n```bash\nDEFAULT_ORG_ID=\"[generated-uuid]\"\nDEFAULT_ORG_NAME=\"Development Testing Organization\"  \n```\n- All test users assigned to shared development organization\n- Facilitates testing and collaborative feedback\n- Easier to manage test user data and permissions\n\n**Production Environment**:\n- No `DEFAULT_ORG_ID` set\n- Each user gets individual organization created during signup\n- Follows multi-tenant architecture for production use\n\n## Critical Configuration Issues\n\n### API Key Separation\n**Problem**: Early development mixed OpenAI and DeepInfra configurations, causing service conflicts.\n\n**Solution**: Clear separation of concerns:\n```bash\n# Voice transcription only\nOPENAI_API_KEY=\"sk-...\"\n\n# AI text generation and workflows  \nDEEPINFRA_API_KEY=\"your-deepinfra-key\"\nDEEPINFRA_API_URL=\"https://api.deepinfra.com/v1/openai\"\n\n# AI observability\nLANGFUSE_SECRET_KEY=\"sk-lf-...\"\nLANGFUSE_PUBLIC_KEY=\"pk-lf-...\"\n```\n\n### Provider Factory vs Direct Clients\n- **AI Workflows**: Use `createProviderClient()` from provider factory with Langfuse observability\n- **Voice Transcription**: Uses direct OpenAI client (no provider factory needed)\n- **Reason**: Transcription is a simple API call, workflows need complex provider management\n\n### Security Anti-Patterns\n❌ **Never use override mechanisms**: `OPENAI_API_KEY_OVERRIDE` was removed for security\n❌ **Don't log API keys**: Even partial keys can be reconstructed\n❌ **Avoid fallback key logic**: Use proper provider factory patterns instead\n\n## Environment File Structure\n```bash\n# .env.local (development)\nOPENAI_API_KEY=\"sk-...\"           # Real OpenAI key for transcription\nDEEPINFRA_API_KEY=\"your-key\"      # DeepInfra for AI workflows\nLANGFUSE_SECRET_KEY=\"sk-lf-...\"   # Langfuse for observability\nLANGFUSE_PUBLIC_KEY=\"pk-lf-...\"\nLANGFUSE_BASE_URL=\"http://localhost:3002\"\n\n# Organization Management\nDEFAULT_ORG_ID=\"550e8400-e29b-41d4-a716-446655440000\"\nDEFAULT_ORG_NAME=\"OT Notes Development\"\n```\n\n## Testing Considerations\n- Mock both OpenAI and DeepInfra clients separately in tests\n- Verify provider factory correctly selects API keys\n- Test fallback behavior when keys are missing\n- Ensure Langfuse observability doesn't break client functionality\n- Test organization assignment behavior with and without `DEFAULT_ORG_ID`\n- Verify signup flow creates individual orgs in production (no default ID)\n- Test user assignment to existing default organizations\n\n## Setup Scripts\nUse the provided scripts to manage organizations across environments:\n\n```bash\n# Create/verify default organization for current environment\nnpm run tsx scripts/setup-default-org.ts\n\n# Assign existing users to default organization\nnpm run tsx scripts/assign-users-to-default-org.ts\n\n# Check user organization assignments\nnpm run tsx scripts/check-user-org.ts\n```"}}}}