stage 1

src/config/env.js

@@ -4,12 +4,23 @@ dotenv.config();
 
 const requiredKeys = ['DB_HOST', 'DB_PORT', 'DB_NAME', 'DB_USER', 'DB_PASSWORD'];
 
+/*
+ * Environment validation happens at module load time so configuration mistakes
+ * are discovered immediately. That is intentional because this service is small
+ * enough that there is no benefit in deferring a misconfiguration error until a
+ * later database call or request handler.
+ */
 for (const key of requiredKeys) {
   if (!process.env[key]) {
     throw new Error(`Missing required environment variable: ${key}`);
   }
 }
 
+/*
+ * The exported env object becomes the single place where raw process variables
+ * are normalized into application-friendly types such as numbers. That keeps the
+ * rest of the codebase from repeating string-to-number conversion logic.
+ */
 export const env = {
   port: Number(process.env.PORT || 3000),
   db: {