Environment Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Environment configuration in the MoodTune backend is managed through a centralized settings system that leverages pydantic-settings. This system ensures that all necessary credentials for third-party integrations—specifically Supabase for data storage and Spotify for music metadata—are properly validated and accessible across the application. The configuration architecture supports multiple deployment stages, including local development, staging, and production on the Railway platform.
The configuration serves as the single source of truth for the application's operational parameters, including security settings, API timeouts, and file upload constraints. By using environment-specific .env files, the system maintains a clear separation between local development needs and production security requirements.
Sources: app/core/config.py:1-85, README.md:4-10, CLAUDE.md:1-25
Configuration Management Architecture
The backend uses a Settings class inheriting from Pydantic's BaseSettings. This class automatically reads environment variables and maps them to Python attributes with type validation. A helper function, _select_env_file, determines which file to load based on the ENVIRONMENT variable.
The diagram shows the logic flow where the ENVIRONMENT variable dictates which .env file is loaded into the Pydantic Settings singleton.
Sources: app/core/config.py:12-23, app/core/config.py:85
Environment File Mapping
The system identifies environment files based on a predefined map:
| Environment | Target File | Usage |
|---|---|---|
development | dev.env | Local development and testing |
staging | staging.env | Pre-production testing |
production | .env | Production deployment (Railway) |
| Sources: app/core/config.py:12-16 |
Core Configuration Categories
Authentication and Security
The application uses JWT-based authentication, primarily integrating with Supabase. Security parameters define how tokens are signed and their lifespan.
- SECRET_KEY: Used for cryptographic signing.
- ALGORITHM: Defaults to
HS256. - Token Expiry: Configured for both Access Tokens (1440 minutes) and Refresh Tokens (7 days).
Sources: app/core/config.py:41-45
Third-Party Integrations
The backend requires specific keys to communicate with Supabase (Database/Auth) and Spotify (Audio Features/Metadata).
| Key | Purpose | Source |
|---|---|---|
SUPABASE_URL | API URL for Supabase project | TEST_PLAN.md:15 |
SUPABASE_SERVICE_KEY | Backend bypass for RLS | README.md:20 |
SPOTIFY_CLIENT_ID | Spotify Application ID | app/core/config.py:54 |
SPOTIFY_REDIRECT_URI | OAuth callback endpoint | app/core/config.py:56 |
Audio Analysis Settings
Specific limits are placed on audio processing to prevent resource exhaustion during the mood analysis phase.
- MAX_UPLOAD_SIZE_MB: Set to 15MB by default.
- AUDIO_ANALYSIS_TIMEOUT: 30 seconds limit for Librosa processing.
- TEMP_AUDIO_DIR:
/tmp/moodtune-audiofor transient file storage.
Sources: app/core/config.py:65-72, app/services/audio_analysis_service.py:270-280
Deployment Configuration
Railway Integration
For production, the railway.toml file defines the build and start commands, ensuring the environment is correctly provisioned on the Railway platform.
The diagram illustrates how the Railway platform utilizes the backend configuration to build and start the service.
Sources: railway.toml:1-5, README.md:12-17
CORS and Networking
The BACKEND_CORS_ORIGINS setting is critical for frontend-backend communication. It accepts a comma-separated string or a list and validates them as valid URLs.
Sources: app/core/config.py:30-39
Implementation Example
The following snippet demonstrates how the Settings class is initialized and how it picks the environment file.
# app/core/config.py:76-85
class Settings(BaseSettings):
# ... variables defined above ...
ENVIRONMENT: str = "development"
DEBUG: bool = True
model_config = SettingsConfigDict(
case_sensitive=True,
env_file=_select_env_file()
)
settings = Settings()
Sources: app/core/config.py:76-85
Summary
The Environment Configuration system provides a robust framework for managing the sensitive credentials and operational limits of the MoodTune Backend. By utilizing Pydantic's validation and environment-specific file loading, it ensures that the application behaves predictably across local, staging, and production environments while maintaining security through strict variable typing and mandatory setting requirements.