Document the Deployment-Time vs Runtime Config Split Between config/env.ts and config/startupValidation.ts

[Emmyt24]

Description

config/env.ts and config/startupValidation.ts both concern environment configuration but serve different purposes — env.ts appears to be the typed, parsed config object used throughout the app, while startupValidation.ts performs a separate zod-schema-based required-vars check and live network reachability probes — yet neither file states its relationship to the other, whether startupValidation.ts's zod schemas are meant to be the single source of truth for which vars are required (superseding any implicit requirements in env.ts), or the order they're expected to run in during boot.

Requirements and Context

• Documentation should describe the existing, actual behavior rather than proposing a redesign
• Should note any deliberate exceptions to the described convention so contributors know when it doesn't apply

Suggested Execution

Branch: docs/document-the-deployment-time-vs-runtime-config-split-between

Implement Changes

• Add doc comments to both files cross-referencing each other and stating the intended call order at startup (per startupValidation.ts's own doc: "Call validateEnvVars() first ... then runStartupValidation() after validateEnv()") and which file is the authoritative source for "is this env var required"

Test and Commit

Run npx vitest run src/config/__tests__/env.spec.ts src/config/__tests__/startupValidation.spec.ts to confirm nothing behavioral broke while updating the doc comments.

Example Commit Message

docs(backend): clarify the relationship and call order between env.ts and startupValidation.ts

Closes #<issue>

Guidelines

• Branch from main, open a PR back to main
• All new code must have corresponding tests
• Run npm run lint and npm run test before pushing
• Follow existing naming conventions and file structure
• PR description must reference this issue number (e.g., Closes #<issue>)
• Keep commits atomic and use conventional commit format