How cywhale/ogcquery works
Project type and purpose
• OGCquery API is a Node.js-based HTTP(s) microservice that
– Fetches WMS/WMTS GetCapabilities XML from external map servers
– Parses XML into JSON (layers, service, capability, bbox, crs, style, etc.)
– Serves the JSON to clients (e.g. CesiumJS/Leaflet UIs)
• No database—stateless, purely request/response with external OGC servers
Main components
A. Client(s)
• Browser or API Consumer (CesiumJS, Leaflet, CLI, Swagger UI)
B. Load Balancer / Process Manager / Reverse Proxy
• pm2 (via pm2.sh) or external LB (optional)
C. HTTPS layer
• confighttps.mjs sets up SSL certificates and HTTPS server
D. Node.js Application
1. srvapp.mjs – bootstraps the server
2. index.mjs – imports HTTPS and Router
3. router.mjs – central routing logic
4. routes/
• frontend.mjs – serves static or documentation (Swagger UI)
• ogcqry.mjs – handles /capability endpoint
5. src/parse_xml01.js (via pretest/src) – XML → JSON parsing logic
E. Swagger / Documentation
• config_swagger.mjs exposes Swagger docs at /hub/swagger
F. External OGC Services
• WMS/WMTS endpoints (e.g., NASA GIBS URL)
Relationships & data flow
1. Client → HTTPS Load Balancer / pm2 → Node HTTPS server
2. Server → router.mjs → appropriate route handler
• If "/hub/swagger" or UI call → frontend.mjs
• If "/ogcquery/capability" → ogcqry.mjs
3. ogcqry.mjs
a. Extracts query params (url, type, layer, etc.)
b. Calls helper (parse_xml01.js) to fetch remote GetCapabilities XML
c. Parses XML → intermediate JS objects
4. JSON response → back through same chain → client
Architectural patterns & design principles
• Modular routing (router.mjs + per-route modules)
• Separation of concerns:
– HTTPS configuration separate from application logic
– Swagger configuration separate from business logic
– XML parsing isolated in a utility module
• Stateless service: each request is independent
• Pretest folder for prototyping and experiments (Python, JS notebooks)
• Clear component labels (e.g., “ogcqry.mjs – /capability handler”)
– “Client Layer”
– “Application Layer” (HTTPS, Router, Controllers)
– “Utility Layer” (Parser, Swagger)
– “External Services”