{"id":39827597,"url":"https://github.com/weaponsforge/ph-regions","last_synced_at":"2026-01-18T13:06:44.325Z","repository":{"id":313568199,"uuid":"1017784249","full_name":"weaponsforge/ph-regions","owner":"weaponsforge","description":"A RESTful API that serves hierarchical (regions, provinces municipalities) location test data of the Philippines","archived":false,"fork":false,"pushed_at":"2025-09-22T06:11:41.000Z","size":1100,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-09-22T08:23:27.102Z","etag":null,"topics":["api-documentation","mongodb","mongoose","openapi3","rest-api","tools"],"latest_commit_sha":null,"homepage":"https://ph-regions.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weaponsforge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-11T05:12:52.000Z","updated_at":"2025-09-22T06:09:17.000Z","dependencies_parsed_at":"2025-09-07T00:24:14.203Z","dependency_job_id":"2ac436f2-4e1a-4351-8eb7-a2d2c1961cef","html_url":"https://github.com/weaponsforge/ph-regions","commit_stats":null,"previous_names":["weaponsforge/ph-regions"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/weaponsforge/ph-regions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaponsforge%2Fph-regions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaponsforge%2Fph-regions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaponsforge%2Fph-regions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaponsforge%2Fph-regions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weaponsforge","download_url":"https://codeload.github.com/weaponsforge/ph-regions/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaponsforge%2Fph-regions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28536693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T13:04:05.990Z","status":"ssl_error","status_checked_at":"2026-01-18T13:01:44.092Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-documentation","mongodb","mongoose","openapi3","rest-api","tools"],"created_at":"2026-01-18T13:06:40.945Z","updated_at":"2026-01-18T13:06:44.318Z","avatar_url":"https://github.com/weaponsforge.png","language":"TypeScript","readme":"## ph-regions\r\n\r\nA RESTful API that serves **hierarchical location data** of the Philippines — including regions, provinces, municipalities, and a **randomly generated number of barangays** per municipality.\r\n\r\n\u003e [!IMPORTANT]\r\n\u003e This API is intended **for testing and simulating RESTful API requests** from client applications.\u003cbr\u003e\r\n\u003e **Note:** The location data may be outdated and does **not** reflect the most current official records.\r\n\r\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-weaponsforge%2Fph--regions-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/weaponsforge/ph-regions)\r\n\u003c!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ --\u003e\r\n\r\n### Online Demo\r\n\r\n- REST API: \u003chttps://ph-regions.vercel.app/api\u003e\r\n- API documentation\r\n  - Static: \u003chttps://ph-regions.vercel.app\u003e\r\n  - Interactive: \u003chttps://ph-regions.vercel.app/docs\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n![architecture](assets/architecture.png)\r\n\r\n\u003c/div\u003e\r\n\u003cbr\u003e\r\n\r\n### Local Development Screenshots\r\n\r\n\u003cp align=\"center\"\u003e\r\n   \u003cimg src=\"assets/ph_regions_ss_01.png\" width=\"45%\" loading=\"lazy\" alt=\"Static API docs screenshot\" /\u003e\r\n   \u003cimg src=\"assets/ph_regions_ss_02.png\" width=\"45%\" loading=\"lazy\" alt=\"Interactive API docs screenshot\" /\u003e\r\n\u003c/p\u003e\r\n\r\n### Table of Contents\r\n\r\n- [Requirements](#-requirements)\r\n- [Core Libraries/Frameworks](#-core-librariesframeworks)\r\n- [Project Folder Structure](#-project-folder-structure)\r\n- [Quickstart](#-quickstart)\r\n- [Installation](#️-installation)\r\n- [Usage](#-usage)\r\n   - [Using Docker](#-using-docker)\r\n   - [Alternate Usage Using Node](#-alternate-usage-using-node)\r\n- [Available Scripts](#-available-scripts)\r\n- [Docker Scripts](#-docker-scripts)\r\n- [Adding New Endpoints](#️-adding-new-endpoints)\r\n- [Usage with GitHub Actions](#usage-with-github-actions)\r\n- [References](#references)\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\r\n\r\n## 📋 Requirements\r\n\r\n1. NodeJS LTS \u003e= v22\r\n2. Docker\r\n\r\n### 📦 Core Libraries/Frameworks\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e👉 The server app uses the following core libraries and frameworks.\u003c/summary\u003e\r\n\r\n| Library | Version | Description |\r\n| --- | --- | --- |\r\n| Express | `5.1.0` |  Node.js web framework for building APIs and web servers. |\r\n| Mongoose | `8.16.5` | ODM for MongoDB that provides schema-based modeling and data interaction. |\r\n| Zod | `4.0.10` | TypeScript-first schema validation for request payloads and query parameters. |\r\n| Nodemon | `3.1.10` | Development tool that automatically restarts the server on file changes. |\r\n| tsx | `4.20.3` | Executes TypeScript and TSX files directly, ideal for dev and script running. |\r\n| tsc-alias | `1.8.16` | Rewrites path aliases in compiled TypeScript output (`tsconfig` paths). |\r\n| ESlint | `9.32.0` | Linting tool that enforces code style, quality, and formatting rules. |\r\n| @asteasolutions/zod-to-openapi | `8.1.0` | Generates OpenAPI YAML and JSON files from Zod schemas. |\r\n| @redocly/cli | `2.1.0` | Generates an API documentation using an OpenAPI YAML input. |\r\n| swagger-ui-express | `4.1.8` | Generates a Swagger UI API documentation using an OpenAPI JSON input. |\r\n\r\n\u003c/details\u003e\r\n\u003cbr\u003e\r\n\r\n## 📚 Project Folder Structure\r\n\r\nThe main app is inside the `📂 server/src` folder.\r\n\r\n- 📂 **dist** - Contains the compiled JavaScript output from TypeScript.\r\n- 🧩 **classes** - Contains reusable class-based logic and services.\r\n- ⚙️ **controllers** - Contains scripts for handling incoming HTTP requests and responses.\r\n- 🔗 **middleware** - Contains functions that process HTTP requests before controllers.\r\n- 🧊 **models** - Contains MongoDB database models and schema definitions using Mongoose.\r\n- 🪧 **routes** - Contains API endpoint definitions and route bindings.\r\n- 📐 **schemas** - Contains Zod validation schemas.\r\n- 📜 **scripts** - Contains utility scripts for setup and maintenance tasks.\r\n- 🌐 **openapi** - Contains OpenAPI definitions using Zod schemas (folder: `/scripts/openapi/docs`)\r\n- 🧾 **types** - Contains shared TypeScript types and interfaces\r\n- 🛠️ **utils** - Contains general-purpose helper functions.\r\n- 📱 `app.ts` - Sets up the Express app and middleware.\r\n- 🖥️ `server.ts` - Starts the server and listens for requests\r\n\r\n\u003cbr\u003e\r\n\r\n## 🆕 Quickstart\r\n\r\nFollow these steps to set up and use the code repository easily. Read the [Installation](#️-installation) section for detailed setup and usage instructions.\r\n\r\n1. Create a `.env` file in the `/server` directory, copying the contents of the `.env.example` file.\r\n\r\n2. Build the development images.\u003cbr\u003e\r\n`docker compose build`\r\n\r\n3. Run the development containers.\u003cbr\u003e\r\n`docker compose up`\r\n\r\n4. Create initial data.\u003cbr\u003e\r\n`docker exec -it weaponsforge-ph-regions npm run seed`\r\n\r\n5. Access the available resources:\r\n   - REST API documentation: http://localhost:3001\r\n   - REST API endpoints: http://localhost:3001/api\r\n\r\n## 🛠️ Installation\r\n\r\n1. Clone the repository.\u003cbr\u003e\r\n`git clone https://github.com/weaponsforge/ph-regions.git`\r\n\r\n2. This repository promotes the use of Docker (See [Using Docker](#-using-docker)) to run the local app. Install dependencies only when proceeding to use the [**\"Alternate Usage Using Node\"**](#-alternate-usage-using-node) option.\u003cbr\u003e\r\n   ```sh\r\n   cd server\r\n   npm install\r\n   ```\r\n\r\n3. Create a `.env` file from the `.env.example` file using its default values in the `/server` directory. Edit the variables and values as needed.\r\n\r\n   \u003cdetails\u003e\r\n   \u003csummary\u003e👉 List of Environment Variables\u003c/summary\u003e\r\n\r\n   | Variable Name | Description |\r\n   | --- | --- |\r\n   | ALLOW_ALL_ORIGINS | Flag to allow HTTP requests from all origins (domains). When set to `1` (default), enables CORS for all domains. When set to `0`, restricts access to domains specified in `ALLOWED_ORIGINS`. |\r\n   | ALLOW_CORS | Enable Cross-Origin Resource Sharing (CORS) on the API endpoints from whitelisted domains, if `ALLOW_ALL_ORIGINS=0`.\u003cbr\u003e\u003cbr\u003e`ALLOW_CORS=1` enables CORS for specified `ALLOWED_ORIGINS` and restricts access to those domains.\u003cbr\u003e `ALLOW_CORS=0` disables CORS restrictions, allowing all domains including Postman. |\r\n   | ALLOWED_ORIGINS | IP/domain origins in comma-separated values that are allowed to access the API if `ALLOW_CORS=1` and `ALLOW_ALL_ORIGINS=0`.\u003cbr\u003e Include `http://localhost:3000` by default to allow CORS access to the **/client** app. |\r\n   | DEPLOYMENT_PLATFORM | This variable refers to the backend `server`'s hosting platform, defaulting to `DEPLOYMENT_PLATFORM=regular`\u003cbr\u003efor full-server NodeJS express apps.\u003cbr\u003e\u003cbr\u003eValid values are:\u003cbr\u003e`regular` - for traditional full-server NodeJS express apps\u003cbr\u003e`vercel` - for Vercel (serverless) |\r\n   | MONGO_URI | MongoDB connection string.\u003cbr\u003eDefault value uses the Docker MongoDB connection string (defined in the docker compose file). |\r\n   | BASE_API_URL | Server base API url minus the forward slash |\r\n   | CHOKIDAR_USEPOLLING | Enables hot reload on `nodemon` running inside Docker containers on a Windows host. Set it to `true` if running Docker Desktop with WSL2 on a Windows OS. |\r\n   | CHOKIDAR_INTERVAL | Chokidar polling interval. Set it along with `CHOKIDAR_USEPOLLING=true` if running Docker Desktop with WSL2 on a Windows OS. The default value is `1000`. |\r\n\r\n   \u003c/details\u003e\r\n\r\n4. Seed (create) the initial data set.\u003cbr\u003e\r\n   - This step requires running the `\"npm run seed\"` script.\r\n   - Proceed to the [**\"Using Docker\"**](#-using-docker) section for more information on running the app first using Docker.\r\n   - Run the command after successfully running the server app using Docker from [A. Use Pre-Built Development Docker Image](#a-use-pre-built-development-docker-image) or [B. Build the Development Docker Image](#b-build-the-development-docker-image).\r\n      ```sh\r\n      docker exec -it weaponsforge-ph-regions npm run seed\r\n      ```\r\n\u003cbr\u003e\r\n\r\n## ⚡ Usage\r\n\r\n### 🐳 Using Docker\r\n\r\n### A. Use Pre-Built Development Docker Image\r\n\r\nSee [Docker Hub: weaponsforge/ph-regions](https://hub.docker.com/r/weaponsforge/ph-regions)\r\n\r\n1. Pull the development Docker image from Docker Hub using one of the options.\u003cbr\u003e\r\n   - `docker pull weaponsforge/ph-regions:latest`\r\n   - `docker compose pull` (using Docker compose from the root project directory)\r\n\r\n2. Navigate to the project directory. Create a `.env` file at **server/.env** using **server/.env.example** as reference.\r\n   - See [Installation](#️-installation) - **step # 3** for more information.\r\n\r\n3. Run the development Docker image.\r\n\r\n   - ```sh\r\n     docker compose up\r\n     ```\r\n\r\n   - Proceed to **Build the Development Docker Image - step # 2** for more information.\r\n\r\n### B. Build the Development Docker Image\r\n\r\n1. Build the image.\u003cbr\u003e\r\n   ```sh\r\n   docker compose build --no-cache\r\n   ```\r\n\r\n2. Run the container.\u003cbr\u003e\r\n   ```sh\r\n   docker compose up\r\n   ```\r\n   - \u003e 💡 **INFO:** Windows OS users may need to uncomment the `CHOKIDAR_USEPOLLING` and `CHOKIDAR_INTERVAL` environment variables to enable hot reload.\r\n   - \u003e 🔄 **Alternate Run Command**\u003cbr\u003e\r\n     \u003e Run this command instead of the first one to enable debugging with breakpoints in VS Code.\r\n\r\n        ```sh\r\n        docker compose -f docker-compose.debug.yml up\r\n        ```\r\n\r\n3. Confirm the running containers.\r\n   ```sh\r\n   docker ps\r\n\r\n   // -- weaponsforge-ph-regions (this app)\r\n   // -- mongodb-ph-regions (Mongo DB service)\r\n   ```\r\n\r\n4. 💡 Launch the API documentation to view available endpoints.\r\n\r\n   ```text\r\n   # Main API docs\r\n   http://localhost:3001\r\n\r\n   # Alternate API docs (interactive)\r\n   http://localhost:3001/docs\r\n   ```\r\n\r\n5. View the [Available Scripts](#-available-scripts) to run.\r\n\r\n6. Stop the containers to exit.\u003cbr\u003e\r\n   ```sh\r\n   docker compose down\r\n   ```\r\n\r\n### 🟩 Alternate Usage Using Node\r\n\r\n\u003e [!NOTE]\r\n\u003e Running the server directly with Node.js requires a locally installed and accessible MongoDB instance, which may need to be set up manually.\u003cbr\u003e\r\n\u003e\r\n\u003e When using a different MongoDB service or installation (other than the one provided in the Docker Compose setup), ensure the `MONGO_URI` variable in the `.env` file is properly configured.\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e👉 View usage instructions\u003c/summary\u003e\r\n\u003cbr\u003e\r\n\r\n1. Build the API documentation.\u003cbr\u003e\r\n   ```sh\r\n   # Builds the Redocly API documentation\r\n   npm run docs:build\r\n   ```\r\n\r\n   ```sh\r\n   # Builds the Swagger UI API documentation\r\n   npm run docs:swagger\r\n   ```\r\n\r\n2. Run the seeder script only once.\u003cbr\u003e\r\n   ```sh\r\n   npm run seed\r\n   ```\r\n\r\n3. Run the API for local development.\u003cbr\u003e\r\n   ```sh\r\n   npm run dev\r\n   ```\r\n\r\n4. 💡 Launch the API documentation to view available endpoints.\r\n\r\n   ```text\r\n   # Main API docs\r\n   http://localhost:3001\r\n\r\n   # Alternate API docs (interactive)\r\n   http://localhost:3001/docs\r\n   ```\r\n\r\n5. View the [Available Scripts](#-available-scripts) to run.\r\n\r\n\u003c/details\u003e\r\n\u003cbr\u003e\r\n\r\n## 📜 Available Scripts\r\n\r\nThese scripts, defined in the `\"/server/package.json\"` file, are compatible with running in Node and Docker. They run various TypeScript scripts, tests, and processes for code base management.\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e👉 Click to expand the list of available scripts\u003c/summary\u003e\r\n\r\n### `npm start`\r\n\r\nRuns the compiled (JavaScript) server app for production mode.\r\n\r\n### `npm run dev`\r\n\r\nRuns the app for local development (when using Node).\r\n\r\n### `npm run transpile`\r\n\r\nBuilds JavaScript, `.d.ts` declaration files, and map files from the TypeScript source files.\r\n\r\n### `npm run transpile:noemit`\r\n\r\nRuns type-checking without generating the JavaScript or declaration files from the TypeScript files.\r\n\r\n### `npm run watch`\r\n\r\nWatches file changes in `.ts` files using the `tsc --watch` option.\r\n\r\n### `npm run lint`\r\n\r\nLints TypeScript source codes.\r\n\r\n### `npm run lint:fix`\r\n\r\nFixes lint errors in TypeScript files.\r\n\r\n### `npm run seed`\r\n\r\nRuns the database seeder script, inserting initial data contents to the database.\r\n\r\n### `npm run docs:gen`\r\n\r\nGenerates the OpenAPI `openapi.yaml` (YAML) and `openapi.json` (JSON) files into the `/server/public` directory.\r\n\r\n\u003e 💡 **NOTE:** Comment out **Line #21, under [public folder volume]** in the `docker-compose.yml` file to update the `\"/server/public/openapi.yaml\"` and `\"/server/public/openapi.json\"` files in the host volume.\r\n\r\n### `npm run docs:build`\r\n\r\nBuilds the API documentation using the [Redocly CLI](https://www.npmjs.com/package/@redocly/cli) into the `/server/public/index.html` file.\r\n\r\n### `npm run build`\r\n\r\nStandard NPM build script that runs transpile, builds OpenAPI docs, and copies Swagger UI assets (`transpile` + `docs:build` + `docs:swagger`).\r\n\r\n\u003e 💡 **NOTE:** Comment out **Line #21 under [public folder volume]** in the `docker-compose.yml` file when running this script via Docker to resolve `EACCES: permission denied` errors.\r\n\r\n### `npm run docs:swagger`\r\n\r\nCopies the minimal Swagger UI assets (CSS/JS) from `node_modules` into `/public/docs`. The page `public/docs/index.html` references these assets and the generated OpenAPI spec in `/public/openapi.json`\r\n\r\n\u003e 💡 **NOTE:** Comment out **Line #21, under [public folder volume]** in the `docker-compose.yml` file when running this script via Docker to resolve `EACCES: permission denied` errors.\r\n\r\n\u003c/details\u003e\r\n\u003cbr\u003e\r\n\r\n## 📦 Docker Scripts\r\n\r\nThese scripts allow optional Docker-related processes, such as enabling file watching in Docker containers running in Windows WSL2 and others.\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e👉 Click to expand the list of available scripts\u003c/summary\u003e\r\n\r\n### Docker run command\r\n\r\n```sh\r\ndocker exec -it weaponsforge-ph-regions \u003cAVAILABLE_SCRIPT\u003e\r\n```\r\n\r\n### `npm run docker:dev`\r\n\r\nRuns the app for local development with the `--inspect` flag, enabling it for debugging with breakpoints in VS Code when running inside containers.\r\n\r\n### `npm run docker:seed:debug`\r\n\r\nRuns the database seeder script, inserting initial data contents to the database.\r\n\r\n```sh\r\ndocker exec -it weaponsforge-ph-regions npm run docker:seed:debug\r\n```\r\n\r\n\u003e 🔔 **IMPORTANT**\u003cbr\u003e\r\n\u003e This script requires having run only the `docker compose up` command. This ensures port `9229` is free for watching the script since it does not run the nodemon + server app with `tsx` and `--inspect=0.0.0.0:9229`.\r\n\r\n### `npm run docker:watch:win`\r\n\r\nWatches file changes in `.ts` files using the `tsc --watch` option with `dynamicPriorityPolling` in Docker containers running in Windows WSL2.\r\n\r\n\u003c/details\u003e\r\n\u003cbr\u003e\r\n\r\n## 🗂️ Adding New Endpoints\r\n\r\nFollow the steps for adding (or editing) new endpoints to the API.\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e👉 Click to view the guidelines\u003c/summary\u003e\r\n\r\n1. **Create a Zod schema**\r\n   - Follow the patterns in the `📐 schemas` directory (e.g., `province.schema.ts`).\r\n   - Ensure each schema field has a Zod `.meta()` attached, with a `description` key containing a short description of the field, and an `example`.\r\n2. **Create a Mongoose model**\r\n   - Follow the patterns in the `🧊 models` directory (e.g., `province.model.ts`).\r\n   - The Zod-inferred type (`z.infer()`) of the **Zod Schema** created in **step # 1** should be used to type-cast this model's **Mongoose Schema**.\r\n\r\n3. **Set up routes (API endpoints)**\u003cbr\u003e\r\nAdd new routes for the model in the `🪧 routes` directory (e.g., `/routes/province.ts`) **without input validation** for now.\r\n\r\n4. **Define query, response, and request schemas**\u003cbr\u003e\r\nCreate Zod schemas for HTTP query, response, params, and body in:\u003cbr\u003e\r\n`server/src/scripts/openapi/docs/api.schema.ts`\r\n\r\n   \u003e 💡 **INFO**\u003cbr\u003e\r\n   Follow the existing schema patterns in this file.\r\n\r\n5. **Add validation middleware**\u003cbr\u003e\r\n   - Implement `🔗 validation` middleware for the routes (from **step 3**) using the Zod schemas from **step 4**.\r\n   - Attach this middleware to the routes.\r\n\r\n6. **Document with OpenAPI**\u003cbr\u003e\r\nCreate OpenAPI documentation for the model in the `🌐 openapi` directory (e.g., `/scripts/openapi/docs/province.doc.ts`) and **register it** in `main.ts`.\r\n\r\n7. **Create a controller**\u003cbr\u003e\r\nAdd model-specific business logic in the `⚙️ controllers` directory (e.g., `/controllers/province.ts`) and connect it to the routes.\r\n\r\n8. **Test the endpoints**\u003cbr\u003e\r\nPerform manual tests to ensure everything works correctly.\r\n\r\n\u003c/details\u003e\r\n\u003cbr\u003e\r\n\r\n## Usage with GitHub Actions\r\n\r\n#### GitHub Secrets\r\n\r\n| GitHub Secrets | Description |\r\n| --- | --- |\r\n| BASE_API_URL | The Vercel server base URL of the production ph-regions API minus the forward slash. |\r\n| DOCKERHUB_USERNAME | Docker Hub username |\r\n| DOCKERHUB_TOKEN | Deploy token for the Docker Hub account |\r\n| VERCEL_ORG_ID | Vercel app's organization ID |\r\n| VERCEL_PROJECT_ID | Vercel app's project ID |\r\n| VERCEL_TOKEN | Vercel personal/token used by the CLI for auth in CI |\r\n| DEPLOYMENT_PLATFORM | Target deployment platform of the backend server. Value is `vercel` |\r\n\r\n#### GitHub Variables\r\n\r\n| GitHub Variable | Description |\r\n| --- | --- |\r\n| DOCKERHUB_USERNAME | Docker Hub username |\r\n\r\n### Deployment to Docker Hub\r\n\r\nThis repository deploys the latest development Docker image `weaponsforge/ph-regions:latest` to Docker Hub after creating new Tags/Releases with GitHub Actions. Supply the above-mentioned GitHub Secrets and Variables to enable deployment to Docker Hub. It requires a **Docker Hub account**.\r\n\r\nThe Docker Hub image is available at:\r\n\r\nhttps://hub.docker.com/r/weaponsforge/ph-regions\r\n\r\n### Deployment to Vercel\r\n\r\nThis repository deploys the latest production API and documentation to Vercel after creating new Tags/Releases with GitHub Actions. Supply the above-mentioned GitHub Secrets and Variables to enable deployment to Vercel. It also requires the following:\r\n\r\n- An Express app initialized in a **Vercel project**\r\n- **MongoDB Atlas** database (for the `MONGO_URI` environment variable in the Vercel project)\r\n\r\n## References\r\n\r\n- [OpenAPI Specification](https://swagger.io/specification/)\r\n- [Redocly - Introduction to OpenAPI](https://redocly.com/learn/openapi/learning-openapi)\r\n- [Redocly - API Governance](https://redocly.com/api-governance)\r\n- [Redocly Configuration](https://redocly.com/docs/redoc/config)\r\n- [Redocly CLI](https://www.npmjs.com/package/@redocly/cli)\r\n- [Redocly CLI Cookbook](https://github.com/Redocly/redocly-cli-cookbook)\r\n- [Redoc Demo](https://redocly.github.io/redoc/)\r\n- [Swagger Editor (Online)](https://swagger.io/tools/swagger-editor/)\r\n\r\n@weaponsforge\u003cbr\u003e\r\n20250711\u003cbr\u003e\r\n20250911\r\n\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweaponsforge%2Fph-regions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweaponsforge%2Fph-regions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweaponsforge%2Fph-regions/lists"}