feat: centralize config management with validation and defaults

[Jayking40]

feat: Config Management Refactor

Summary

This PR implements a centralized configuration management system for the TalentTrust Backend. Previously, environment variables were read directly via process.env scattered across the codebase with no validation or type safety. This refactor consolidates all config parsing into a single typed module that validates required variables at startup, applies safe defaults, and fails fast with a clear error message if the environment is misconfigured.

This improves security (no silent misconfigurations), developer experience (one place to find all config), and maintainability (typed config object instead of raw string reads).

---

Changes

New Configuration Module

• src/config/env.ts — Low-level environment variable parsing utilities with comprehensive validation:

  • getEnv() — Reads raw env vars, treating empty/whitespace strings as undefined
  • requireEnv() — Enforces required variables with descriptive error messages
  • optionalEnv() — Provides safe defaults for optional variables
  • parseIntEnv() — Type-safe integer parsing with validation
  • parseBoolEnv() — Boolean parsing supporting "true"/"false"/"1"/"0" (case-insensitive)

• src/config/index.ts — Centralized configuration with typed interfaces:

  • ServerConfig — HTTP port, Node environment, production flag
  • StellarConfig — Horizon URL, network passphrase
  • SorobanConfig — RPC URL, contract ID
  • loadConfig() — Factory function for creating config snapshots (useful in tests)
  • config — Frozen singleton loaded once at startup

Startup Validation

All environment variables are validated at boot time:

• Missing required variables throw descriptive errors immediately
• Invalid types (non-numeric PORT, invalid boolean values) fail fast
• Empty strings and whitespace-only values are treated as missing
• Numeric and boolean env vars are parsed and validated as the correct type

Refactored Entry Point

• src/index.ts — Replaced direct process.env.PORT usage with config.server.port from the centralized config module

Comprehensive Test Coverage

• src/config/config.test.ts — 43 tests covering:
  • Valid configuration loading with all required vars present
  • Missing/empty/whitespace variable handling
  • Invalid numeric and boolean value parsing errors
  • Default values applied correctly for optional vars
  • Frozen config object immutability
  • Independent config snapshots for test isolation
• Test coverage: 100% statements, branches, functions, and lines for the config module
• All existing tests continue to pass without modification

Documentation

• .env.example — Template file with all environment variables, defaults, and comments
• docs/backend/config.md — Comprehensive configuration guide including:
  • Complete environment variable reference table
  • Validation rules and behavior
  • Usage examples for application code and tests
  • Instructions for adding new configuration variables
  • Security best practices
• README.md — Added Environment Variables section with quick reference table

Development Tooling

• .eslintrc.json — Added ESLint configuration (was missing, causing npm run lint to fail)
• package.json — Added ESLint and TypeScript ESLint dependencies to support the existing lint script

---

Testing

• ✅ All existing tests continue to pass without modification
• ✅ 43 new tests for the config module covering all validation paths
• ✅ 100% test coverage for src/config/env.ts and src/config/index.ts
• ✅ npm run build — Clean TypeScript compilation with zero errors
• ✅ npm test — 44 tests passed (2 suites)
• ✅ npm run lint — Zero linting errors
• ✅ npx tsc --noEmit — Zero type errors
• ✅ CI/CD pipeline passes on this branch

---

Migration Notes

No breaking changes. The existing PORT environment variable continues to work exactly as before, now with added validation. New optional variables have safe defaults and do not require immediate configuration.

---

Closes #72

[drips-wave]

@Jayking40 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits