Initial commit

docs/adr/0003-environment-validation.md

@@ -0,0 +1,61 @@
+# 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
+