PH Regions API Architecture

PH Regions API Architecture An architecture diagram generated by Archify. API Clients · Browser / App · Public internet (untrusted) API Clients Browser / App Express App · entry point · Express runtime process (app trust boundary) Express App entry point Route Layer · 5 routers · Express runtime process (app trust boundary) Route Layer 5 routers Zod Validation · query + id params · Express runtime process (app trust boundary) Zod Validation query + id params Controllers · per resource · Express runtime process (app trust boundary) Controllers per resource Data Access Layer · Mongo CRUD + models · Express runtime process (app trust boundary) Data Access Layer Mongo CRUD + models MongoDB · 4 core collections · Data tier MongoDB 4 core collections API Docs · static Swagger UI · Express runtime process (app trust boundary) API Docs static Swagger UI Serverless Guard · Vercel mode only · Express runtime process (app trust boundary) Serverless Guard Vercel mode only Seed CLI · npm run seed · Offline tooling (operator-run, outside request path) Seed CLI npm run seed ph-municipalities · npm dataset package · Offline tooling (operator-run, outside request path) ph-municipalities npm dataset package HTTPS GET /api/* query params validated req CRUD call Mongoose query static /public vercel mode ensures connection deleteMany + insertMany reads dataset Public internet (untrusted) Express runtime process (app trust boundary) Data tier Offline tooling (operator-run, outside request path) Legend Frontend Backend Database Cloud Security External

Validation & data access

  • • Zod validates query + :id params before any controller runs (middleware/validate.ts)
  • • MongoCrudClass wraps findById/findOne/find; region -> province -> municipality resolved via populate()

Trust boundary & dependencies

  • • No auth/API-key/JWT anywhere — public read-only API; CORS allowlist is the only perimeter gate (express-rate-limit is installed but unused)
  • • MongoDB is the only datastore; ph-municipalities npm package feeds the offline seed CLI only — no cache, queue, or third-party API calls

Deployment modes

  • • Regular mode opens one long-lived Mongoose connection at boot; Vercel mode's guard reconnects per invocation
  • • Docs (Swagger UI, openapi.json/yaml) are served as static files; a /docs router exists but is unmounted