# ADR-0003: Environment Variable Validation at Startup

## Status
Accepted

## Context
The application was using environment variables without validation, leading to:
- Runtime errors when required variables were missing
- Security risks from weak or missing secrets
- Difficult debugging when misconfigured
- No clear error messages for configuration issues

## Decision
Implement environment variable validation that:
- Runs at application startup
- Validates all required variables
- Provides clear error messages
- Supports different validation rules per environment
- Fails fast if critical variables are missing or invalid

## Consequences

### Positive
- Early detection of configuration errors
- Clear error messages guide developers
- Prevents runtime failures from misconfiguration
- Security improvements (validates JWT secret strength, CORS config)
- Better developer experience

### Negative
- Application won't start if validation fails (by design)
- Requires maintaining validation schema
- Additional startup time (minimal)

### Risks
- Breaking changes if validation rules are too strict
- Need to keep validation in sync with actual usage

## Alternatives Considered

1. **Runtime Validation**: Validate when variables are used
   - Pros: More flexible
   - Cons: Errors discovered late, harder to debug

2. **Configuration File**: Use config file instead of env vars
   - Pros: Type-safe, validated
   - Cons: Doesn't work well with 12-factor app principles

3. **Startup Validation**: Chosen approach
   - Pros: Fail fast, clear errors, secure defaults
   - Cons: None significant

## Implementation
- Created `src/shared/config/env-validator.ts`
- Integrated into `src/index.ts` startup
- Validates: DATABASE_URL, JWT_SECRET, ALLOWED_ORIGINS, etc.

## References
- 12-Factor App: https://12factor.net/config
- Node.js Environment Variables: https://nodejs.org/en/learn/command-line/how-to-read-environment-variables-from-nodejs