perf: dependency updates 20260418

.github/workflows/lint.yml

@@ -13,10 +13,10 @@ jobs:
       - name: Checkout the repository
         uses: actions/checkout@v4
 
-      - name: Use NodeJS v22.14.0
+      - name: Use NodeJS v24.11.0
         uses: actions/setup-node@v4
         with:
-          node-version: 22.14.0
+          node-version: 24.11.0
           registry-url: https://registry.npmjs.org/
 
       - name: Install Dependencies

.github/workflows/release.yml

@@ -22,10 +22,10 @@ jobs:
         with:
           ref: ${{ github.event.release.tag_name }}
 
-      - name: Use NodeJS v22.14.0
+      - name: Use NodeJS v24.11.0
         uses: actions/setup-node@v4
         with:
-          node-version: 22.14.0
+          node-version: 24.11.0
 
       - name: Install Vercel CLI
         run: npm install --global vercel@47.0.6

CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**ph-regions** is a RESTful API serving hierarchical Philippine location data (islands → regions → provinces → municipalities → barangays). It supports testing/simulating RESTful API requests from client applications, with deployment targets for both regular Node.js and Vercel serverless.
+
+The codebase lives in `/server` — all development work happens there.
+
+## Commands
+
+Run these from the `/server` directory:
+
+```bash
+# Development
+npm run dev           # Start with nodemon (tsx, no compilation needed)
+npm run watch         # Watch TypeScript files (tsc --watch)
+
+# Type checking & linting
+npm run transpile:noemit   # Type-check without emitting files
+npm run lint               # Lint TypeScript files
+npm run lint:fix           # Auto-fix lint errors
+
+# Build (full pipeline: transpile + docs)
+npm run build         # Compile TypeScript + build all API docs
+npm run transpile     # Compile TypeScript only (tsc-alias for path rewrites)
+
+# Database seeding
+npm run seed          # Seed MongoDB with Philippine location data
+
+# API documentation
+npm run docs:gen      # Generate OpenAPI YAML/JSON from Zod schemas
+npm run docs:build    # Build Redocly HTML documentation
+npm run docs:swagger  # Copy Swagger UI assets + generate docs
+```
+
+Docker (run from repo root):
+```bash
+docker compose up     # Start app + MongoDB (development mode)
+```
+
+## Architecture
+
+### Request Lifecycle
+```
+HTTP Request → CORS → Body Parser → Zod Validation Middleware → Controller → MongoCrudClass → Mongoose → MongoDB
+```
+
+### Key Abstractions
+
+**`server/src/classes/mongo.class.ts`** — `MongoCrudClass` provides reusable `find`, `findOne`, `create`, `update`, `delete` methods used by all controllers. Controllers instantiate it with a Mongoose model.
+
+**`server/src/middleware/validate.ts`** — Generic validation middleware that takes a Zod schema and validates `req.query` or `req.body`. Throws `ServerError` on failure.
+
+**`server/src/middleware/connectServerless.ts`** — Wraps controllers for Vercel serverless, re-establishing MongoDB connections per request (stateless environment).
+
+**`server/src/utils/error.ts`** — `ServerError extends Error` with a `status` property. The global error handler in `app.ts` catches these and formats the error response.
+
+### Data Model (Hierarchical)
+```
+Island (1) → Region (many) → Province (many) → Municipality (many) → Barangays (Stats collection)
+```
+Mongoose models use virtual population for nested queries. `Stats` holds barangay counts per municipality.
+
+### Zod as Single Source of Truth
+Zod schemas in `server/src/schemas/` drive both:
+1. **Runtime validation** — query parameter and payload validation via middleware
+2. **OpenAPI documentation** — `@asteasolutions/zod-to-openapi` generates the spec from the same schemas
+
+When adding or modifying endpoints, update the corresponding Zod schema, the OpenAPI doc file in `server/src/scripts/openapi/docs/`, and run `npm run docs:gen`.
+
+### API Response Shape
+All successful responses follow this structure:
+```json
+{
+  "success": true,
+  "total": 17,
+  "metadata": { "version": "...", "author": "...", "url": "...", "description": "..." },
+  "data": []
+}
+```
+Error responses:
+```json
+{ "success": false, "error": "...", "message": ["..."], "status": 400 }
+```
+
+### Deployment Platform Branching
+The `DEPLOYMENT_PLATFORM` env var (`"regular"` | `"vercel"`) controls:
+- Route mounting in `app.ts` (serverless wrapper applied only on Vercel)
+- MongoDB connection strategy (`server.ts` vs `connectServerless.ts`)
+
+### Module System
+The project uses ESM (`"type": "module"`). TypeScript targets `NodeNext` modules. Path alias `@/*` maps to `src/*` — `tsc-alias` rewrites these after compilation.
+
+## Environment Setup
+
+Copy `server/.env.example` to `server/.env` and set:
+- `MONGO_URI` — MongoDB connection string
+- `DEPLOYMENT_PLATFORM` — `regular` for local dev
+- `ALLOW_CORS=1` and `ALLOW_ALL_ORIGINS=1` for local dev
+- `BASE_API_URL` — e.g. `http://localhost:3001`
+
+## Code Style
+
+ESLint enforces: single quotes, no semicolons, 2-space indent, Unix line endings, no trailing commas. Run `npm run lint:fix` before committing. TypeScript strict mode is on — no implicit `any`, strict null checks.

README.md

@@ -54,7 +54,12 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu
 
 ## 📋 Requirements
 
-1. NodeJS LTS >= v22
+1. NodeJS LTS >= v24
+   ```text
+   Recommended:
+   node: 24.11.0
+   npm: 11.6.1
+   ```
 2. Docker
 
 ### 📦 Core Libraries/Frameworks
@@ -64,15 +69,15 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu
 
 | Library | Version | Description |
 | --- | --- | --- |
-| Express | `5.1.0` |  Node.js web framework for building APIs and web servers. |
-| Mongoose | `8.16.5` | ODM for MongoDB that provides schema-based modeling and data interaction. |
-| Zod | `4.0.10` | TypeScript-first schema validation for request payloads and query parameters. |
-| Nodemon | `3.1.10` | Development tool that automatically restarts the server on file changes. |
-| tsx | `4.20.3` | Executes TypeScript and TSX files directly, ideal for dev and script running. |
+| Express | `5.2.1` |  Node.js web framework for building APIs and web servers. |
+| Mongoose | `9.4.1` | ODM for MongoDB that provides schema-based modeling and data interaction. |
+| Zod | `4.3.6` | TypeScript-first schema validation for request payloads and query parameters. |
+| Nodemon | `3.1.14` | Development tool that automatically restarts the server on file changes. |
+| tsx | `4.21.0` | Executes TypeScript and TSX files directly, ideal for dev and script running. |
 | tsc-alias | `1.8.16` | Rewrites path aliases in compiled TypeScript output (`tsconfig` paths). |
-| ESlint | `9.32.0` | Linting tool that enforces code style, quality, and formatting rules. |
-| @asteasolutions/zod-to-openapi | `8.1.0` | Generates OpenAPI YAML and JSON files from Zod schemas. |
-| @redocly/cli | `2.1.0` | Generates an API documentation using an OpenAPI YAML input. |
+| ESlint | `10.2.1` | Linting tool that enforces code style, quality, and formatting rules. |
+| @asteasolutions/zod-to-openapi | `8.5.0` | Generates OpenAPI YAML and JSON files from Zod schemas. |
+| @redocly/cli | `2.28.1` | Generates an API documentation using an OpenAPI YAML input. |
 | swagger-ui-express | `4.1.8` | Generates a Swagger UI API documentation using an OpenAPI JSON input. |
 
 </details>

server/.nvmrc

@@ -1 +1 @@
-22.14.0
+24.11.0

server/Dockerfile

@@ -1,5 +1,5 @@
 # BASE PROFILE
-FROM node:22.14.0-alpine AS base
+FROM node:24.11.0-alpine AS base
 RUN mkdir -p /opt/server
 WORKDIR /opt/server
 RUN chown -R node:node /opt/server