diff --git a/README.md b/README.md index 8357166..f3d2588 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,13 @@ A RESTful API that serves **hierarchical location data** of the Philippines — [![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) +### Online Demo + +- REST API: +- API documentation + - Static: + - Interactive: +
@@ -18,18 +25,19 @@ A RESTful API that serves **hierarchical location data** of the Philippines —

-### Online Deployments +### Local Development Screenshots -- REST API: -- API documentation - - Static: - - Interactive: +

+ Static API docs screenshot + Interactive API docs screenshot +

### Table of Contents - [Requirements](#-requirements) - [Core Libraries/Frameworks](#-core-librariesframeworks) - [Project Folder Structure](#-project-folder-structure) +- [Quickstart](#-quickstart) - [Installation](#️-installation) - [Usage](#-usage) - [Using Docker](#-using-docker) @@ -63,9 +71,9 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu | tsx | `4.20.3` | 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 an OpenAPI yaml file from Zod schemas. | -| @redocly/cli | `2.1.0` | 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. | +| @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. | +| swagger-ui-express | `4.1.8` | Generates a Swagger UI API documentation using an OpenAPI JSON input. |
@@ -90,6 +98,25 @@ The main app is inside the `📂 server/src` folder.
+## 🆕 Quickstart + +Follow these steps to set up and use the code repository easily. Read the [Installation](#️-installation) section for detailed setup and usage instructions. + +1. Create a `.env` file in the `/server` directory, copying the contents of the `.env.example` file. + +2. Build the development images.
+`docker compose build` + +3. Run the development containers.
+`docker compose up` + +4. Create initial data.
+`docker exec -it weaponsforge-ph-regions npm run seed` + +5. Access the available resources: + - REST API documentation: http://localhost:3001 + - REST API endpoints: http://localhost:3001/api + ## 🛠️ Installation 1. Clone the repository.
@@ -121,8 +148,8 @@ The main app is inside the `📂 server/src` folder. 4. Seed (create) the initial data set.
- This step requires running the `"npm run seed"` script. - - Proceed to the [**"Using Docker"**](#-using-docker) section for more information on running the app using Docker. - - Run the command after successfully running the server app from **Usage - Using Docker - step # 3**. + - Proceed to the [**"Using Docker"**](#-using-docker) section for more information on running the app first using Docker. + - 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). ```sh docker exec -it weaponsforge-ph-regions npm run seed ``` @@ -285,7 +312,7 @@ Runs the database seeder script, inserting initial data contents to the database Generates the OpenAPI `openapi.yaml` (YAML) and `openapi.json` (JSON) files into the `/server/public` directory. -> 💡 **NOTE:** Comment out **Line #20, [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. +> 💡 **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. ### `npm run docs:build` @@ -295,13 +322,13 @@ Builds the API documentation using the [Redocly CLI](https://www.npmjs.com/packa Standard NPM build script that runs transpile, builds OpenAPI docs, and copies Swagger UI assets (`transpile` + `docs:build` + `docs:swagger`). -> 💡 **NOTE:** Comment out **Line #20 under [public folder volume]** in the `docker-compose.yml` file when running this script via Docker to resolve `EACCES: permission denied` errors. +> 💡 **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. ### `npm run docs:swagger` Copies 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` -> 💡 **NOTE:** Comment out **Line #20, [public folder volume]** in the `docker-compose.yml` file when running this script via Docker to resolve `EACCES: permission denied` errors. +> 💡 **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.
@@ -348,17 +375,18 @@ Follow the steps for adding (or editing) new endpoints to the API.
👉 Click to view the guidelines -1. **Create a Zod schema**
-Follow the patterns in the `📐 schemas` directory (e.g., `province.schema.ts`). - -2. **Create a Mongoose model**
-Follow the patterns in the `🧊 models` directory (e.g., `province.model.ts`). +1. **Create a Zod schema** + - Follow the patterns in the `📐 schemas` directory (e.g., `province.schema.ts`). + - Ensure each schema field has a Zod `.meta()` attached, with a `description` key containing a short description of the field, and an `example`. +2. **Create a Mongoose model** + - Follow the patterns in the `🧊 models` directory (e.g., `province.model.ts`). + - 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**. 3. **Set up routes (API endpoints)**
Add new routes for the model in the `🪧 routes` directory (e.g., `/routes/province.ts`) **without input validation** for now. 4. **Define query, response, and request schemas**
-Create Zod schemas for query, response, params, and body in:
+Create Zod schemas for HTTP query, response, params, and body in:
`server/src/scripts/openapi/docs/api.schema.ts` > 💡 **INFO**
diff --git a/assets/README.md b/assets/README.md new file mode 100644 index 0000000..f12fc12 --- /dev/null +++ b/assets/README.md @@ -0,0 +1,11 @@ +## assets + +This folder contains media assets used within the repository. + +### Notes + +- The `architecture.drawio` file was created using [draw.io](https://www.drawio.com/) v28.1.2. + > Export `assets/architecture.drawio` to `assets/architecture.png` (**File** → **Export as** → **PNG**) whenever the diagram changes. + +@weaponsforge
+20250922 diff --git a/assets/architecture.drawio b/assets/architecture.drawio index 46ce844..6f14331 100644 --- a/assets/architecture.drawio +++ b/assets/architecture.drawio @@ -16,7 +16,7 @@ - + @@ -48,9 +48,21 @@ - + + + + + + + + + + + + + diff --git a/assets/architecture.png b/assets/architecture.png index c6b6e35..6406cfd 100644 Binary files a/assets/architecture.png and b/assets/architecture.png differ diff --git a/assets/ph_regions_ss_01.png b/assets/ph_regions_ss_01.png new file mode 100644 index 0000000..c8ffdd1 Binary files /dev/null and b/assets/ph_regions_ss_01.png differ diff --git a/assets/ph_regions_ss_02.png b/assets/ph_regions_ss_02.png new file mode 100644 index 0000000..5a3ce1e Binary files /dev/null and b/assets/ph_regions_ss_02.png differ diff --git a/server/package-lock.json b/server/package-lock.json index 8c0a9ba..c94bfb8 100644 --- a/server/package-lock.json +++ b/server/package-lock.json @@ -1,12 +1,12 @@ { "name": "ph-regions", - "version": "1.1.0", + "version": "1.1.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ph-regions", - "version": "1.1.0", + "version": "1.1.1", "license": "MIT", "dependencies": { "cookie-parser": "^1.4.7", diff --git a/server/package.json b/server/package.json index 75725c4..b7597ac 100644 --- a/server/package.json +++ b/server/package.json @@ -1,6 +1,6 @@ { "name": "ph-regions", - "version": "1.1.0", + "version": "1.1.1", "type": "module", "description": "A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality.", "main": "dist/server.js",