# cywhale/ogcquery architecture

> Architecture diagram of the GitHub repository cywhale/ogcquery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cywhale/ogcquery
- Repository: https://github.com/cywhale/ogcquery

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Client["Browser / API Consumer\n(CesiumJS, Leaflet, CLI, Swagger UI)"]:::blue
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB

        subgraph "Network & Process" 
            direction TB
            LB["pm2.sh\n(Process Manager / Load Balancer)"]:::gray
        end

        subgraph "HTTPS Configuration" 
            direction TB
            HTTPS["confighttps.mjs\n(HTTPS Layer Config)"]:::orange
        end

        subgraph "Core Application" 
            direction TB
            App["srvapp.mjs\n(Application Bootstrap)"]:::green
            Entry["index.mjs\n(Server Entry Point)"]:::green
            Router["router.mjs\n(Central Router)"]:::green

            subgraph "Routes" 
                direction TB
                FE["frontend.mjs\n(/hub/swagger UI Handler)"]:::green
                OGC["ogcqry.mjs\n(/capability Handler)"]:::green
            end
        end

        subgraph "Utility Layer"
            direction TB
            Swagger["config_swagger.mjs\n(Swagger Config)"]:::orange
            Parser["parse_xml01.js\n(XML→JSON Parsing Utility)"]:::orange
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OGCServ["WMS/WMTS Servers\n(NASA GIBS etc)"]:::gray
    end

    %% Data Flow Arrows
    Client -->|"HTTPS"| LB
    LB -->|"HTTPS"| HTTPS
    HTTPS -->|"boots"| App
    App -->|"calls"| Entry
    Entry -->|"routes to"| Router
    Router -->|"UI request"| FE
    Router -->|"Capability request"| OGC
    OGC -->|"uses parser"| Parser
    Parser -->|"returns JSON"| OGC
    OGC -->|"responds JSON"| Router
    Router -->|"response"| Entry
    Entry -->|"response via HTTPS"| Client
    OGC -->|"fetch XML/HTTP"| OGCServ
    Swagger -.->|"configures docs for"| FE

    %% Click Events
    click LB "https://github.com/cywhale/ogcquery/blob/main/pm2.sh"
    click HTTPS "https://github.com/cywhale/ogcquery/blob/main/src/confighttps.mjs"
    click Swagger "https://github.com/cywhale/ogcquery/blob/main/src/config_swagger.mjs"
    click App "https://github.com/cywhale/ogcquery/blob/main/src/srvapp.mjs"
    click Entry "https://github.com/cywhale/ogcquery/blob/main/src/index.mjs"
    click Router "https://github.com/cywhale/ogcquery/blob/main/src/router.mjs"
    click FE "https://github.com/cywhale/ogcquery/blob/main/src/routes/frontend.mjs"
    click OGC "https://github.com/cywhale/ogcquery/blob/main/src/routes/ogcqry.mjs"
    click Parser "https://github.com/cywhale/ogcquery/blob/main/pretest/src/parse_xml01.js"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085;
    classDef green fill:#d4edda,stroke:#155724,color:#155724;
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404;
    classDef gray fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
