stage 1

src/db/pool.js

@@ -2,6 +2,11 @@ import * as mariadb from 'mariadb';
 
 import { env } from '../config/env.js';
 
+/*
+ * One shared pool is enough for the current backend because the service is read-
+ * heavy and low volume. Centralizing pool creation here prevents each route or
+ * service module from opening its own connections and makes shutdown predictable.
+ */
 const pool = mariadb.createPool({
   host: env.db.host,
   port: env.db.port,
@@ -16,6 +21,11 @@ export async function query(sql, params = []) {
   let connection;
 
   try {
+    /*
+     * The helper deliberately exposes a low-level query primitive instead of a
+     * custom repository abstraction. For the PoC that keeps SQL visible and easy
+     * to reason about while still ensuring every query uses the same pool.
+     */
     connection = await pool.getConnection();
     return await connection.query(sql, params);
   } finally {