# netbymatt/ws4kp architecture

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

- Interactive diagram: https://gitdiagram.com/netbymatt/ws4kp
- Repository: https://github.com/netbymatt/ws4kp

## Overview

##### Project Type and Purpose
- This is a full-stack, Node.js-based web application that simulates a “90’s Weather Channel” local forecast using modern HTML/CSS/JS.
- The Node server (index.mjs) serves dynamic views (EJS), static assets, and acts as a CORS proxy to NOAA’s Weather API.

##### File Structure
- Root
– index.mjs: entry point, starts Node server
– Dockerfile / .github/workflows: CI/CD & containerization
– gulpfile.mjs + gulp/**: build pipeline for static distribution (/dist)
- server/
– scripts/: CORS proxy modules + optional custom.js hook
– fonts/, images/, music/: static assets served to client
– styles/: SCSS & compiled CSS for styling
– manifest.json, robots.txt: PWA config & crawler hints
- views/
– index.ejs + partials/: server-side templates build the UI shell
- src/, cors/, datagenerators/:
– src/: auxiliary scripts (playlist generation)
– cors/: static CORS proxies usable in serverless setups
– datagenerators/: offline data‐preparation scripts
- dist/: final static bundle for CDN/S3 hosting
- tests/: unit & integration tests

##### Key Insights from README
- Node server solves CORS by proxying api.weather.gov requests.
- Build step (`npm run buildDist`) emits `/dist` for pure-static deployment.
- Uses ES modules, classes, async/await, Luxon date library.
- UI is rendered in EJS, then enhanced by client-side JS modules (under server/scripts/modules).

##### Main Components & Their Interactions
a. Browser (Client)
- Loads HTML from Node server (EJS).
- Fetches CSS/JS static assets.
- Invokes client modules to render each “display.”
- Makes API calls to CORS proxy endpoints on the Node server.
b. Node.js Server
- HTTP server (index.mjs) using native http or Express-like routing.
- Serves EJS templates and static folders (styles, images, music).
- Implements CORS proxy routes (server/scripts/modules/utils/cors.mjs).
- Hosts custom hook (server/scripts/custom.js).
c. NOAA Weather API (external)
- Authoritative data source for all weather data via REST.
- Node server proxies requests, adds CORS headers.
d. Build System (Gulp)
- Runs tasks: compile SCSS → CSS, bundle or copy JS, optimize assets.
- Outputs fully static site under /dist.
e. Optional Data‐Generation Scripts (offline)
- datagenerators/*.mjs produce JSON used in tests or demos.

##### Architectural Patterns & Principles
- Separation of concerns: UI (EJS + CSS), data fetching/proxy (server scripts), build pipeline.
- Modular client-side code: each display is an ES6 class under server/scripts/modules.
- Proxy pattern for CORS (single point of entry for external API).
- Static site export capability for CDN hosting (serverless).
- Containerization via Docker for easy local run & CORS handling.

1. Client Browser
2. Node.js Server
3. NOAA Weather API (external)
4. Build System / CI & CD (Gulp, Docker, GitHub Actions)
- EJS View Engine → views/partials
- Static Asset Server → styles/, images/, music/
- CORS Proxy Module → server/scripts/modules/utils/cors.mjs
- Customization Hook → server/scripts/custom.js
- Browser → GET / → Node
- Browser → GET /scripts, /styles → Node static server
- Browser → XHR /cors/* → Node CORS proxy
- Node CORS proxy → HTTPS → NOAA API
- Gulp (build) → outputs /dist → possible static hosting/CDN
- GitHub Actions → Docker build & push → container registry
- Blue rectangles for internal components (View Engine, CORS Module)
- Green for external (NOAA API, CDN)
- Orange for build/CI (Gulp, GitHub Actions, Docker)

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef internal fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef external fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef build fill:#FFE0B2,stroke:#E65100,color:#E65100

    subgraph "Client Browser" 
        direction TB
        CB["Browser"]:::external
    end

    subgraph "Node.js Server"
        direction TB
        Entry["Entry Point (index.mjs)"]:::internal
        subgraph "View Engine"
            EJS["EJS View Engine"]:::internal
        end
        subgraph "Static Assets"
            Styles["Styles"]:::internal
            Images["Images"]:::internal
            Music["Music"]:::internal
            Fonts["Fonts"]:::internal
            Manifest["manifest.json"]:::internal
            Robots["robots.txt"]:::internal
        end
        subgraph "CORS & API"
            CORS["CORS Proxy Module"]:::internal
        end
        Custom["Customization Hook"]:::internal
        subgraph "Client Modules"
            CM["Display Modules"]:::internal
        end
        subgraph "Auxiliary Server Scripts"
            AuxS["Aux Server Scripts"]:::internal
        end
    end

    NOAA["NOAA Weather API"]:::external

    subgraph "Build / CI-CD"
        direction TB
        Gulp["Gulp Build System"]:::build
        Dist["/dist Output"]:::build
        subgraph "CI Config"
            WD["build-docker.yaml"]:::build
            CL["codeql-analysis.yml"]:::build
        end
        Docker["Docker Containerization"]:::build
        GitHub["GitHub Actions"]:::build
        Tests["Tests"]:::build
        CDN["CDN/S3 Hosting"]:::external
    end

    subgraph "Auxiliary Scripts"
        direction TB
        DG["Data Preparation Scripts"]:::internal
        Playlist["Playlist Utilities"]:::internal
    end

    CB -->|"GET /"| Entry
    CB -->|"GET static assets"| Styles
    CB -->|"GET static assets"| Images
    CB -->|"GET static assets"| Music
    CB -->|"GET static assets"| Fonts
    CB -->|"GET static assets"| Manifest
    CB -->|"GET static assets"| Robots
    CB -->|"XHR /cors/*"| CORS
    Entry --> EJS
    Entry --> Styles
    Entry --> Images
    Entry --> Music
    Entry --> Fonts
    Entry --> Manifest
    Entry --> Robots
    EJS --> CB
    CM --> EJS
    CORS -->|"HTTPS"| NOAA
    Gulp --> Dist
    Dist --> CDN
    WD --> GitHub
    CL --> GitHub
    GitHub --> Docker
    GitHub --> Tests
    Docker --> Entry
    DG --> Tests
    Playlist --> Tests
    AuxS --> Entry

    click Entry "https://github.com/netbymatt/ws4kp/blob/main/index.mjs"
    click Docker "https://github.com/netbymatt/ws4kp/tree/main/Dockerfile"
    click WD "https://github.com/netbymatt/ws4kp/blob/main/.github/workflows/build-docker.yaml"
    click CL "https://github.com/netbymatt/ws4kp/blob/main/.github/workflows/codeql-analysis.yml"
    click Gulp "https://github.com/netbymatt/ws4kp/blob/main/gulpfile.mjs"
    click Gulp "https://github.com/netbymatt/ws4kp/blob/main/gulp/publish-frontend.mjs"
    click Gulp "https://github.com/netbymatt/ws4kp/blob/main/gulp/update-vendor.mjs"
    click Dist "https://github.com/netbymatt/ws4kp/tree/main/dist/"
    click EJS "https://github.com/netbymatt/ws4kp/blob/main/views/index.ejs"
    click EJS "https://github.com/netbymatt/ws4kp/tree/main/views/partials/"
    click Styles "https://github.com/netbymatt/ws4kp/tree/main/server/styles/"
    click Images "https://github.com/netbymatt/ws4kp/tree/main/server/images/"
    click Music "https://github.com/netbymatt/ws4kp/tree/main/server/music/"
    click Fonts "https://github.com/netbymatt/ws4kp/tree/main/server/fonts/"
    click Manifest "https://github.com/netbymatt/ws4kp/blob/main/server/manifest.json"
    click Robots "https://github.com/netbymatt/ws4kp/blob/main/server/robots.txt"
    click CORS "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/modules/utils/cors.mjs"
    click CORS "https://github.com/netbymatt/ws4kp/blob/main/cors/index.mjs"
    click CORS "https://github.com/netbymatt/ws4kp/blob/main/cors/outlook.mjs"
    click CORS "https://github.com/netbymatt/ws4kp/blob/main/cors/radar.mjs"
    click Custom "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/custom.sample.js"
    click CM "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/modules/almanac.mjs"
    click CM "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/modules/currentweather.mjs"
    click CM "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/modules/hourly-graph.mjs"
    click DG "https://github.com/netbymatt/ws4kp/blob/main/datagenerators/chunk.mjs"
    click DG "https://github.com/netbymatt/ws4kp/blob/main/datagenerators/https.mjs"
    click DG "https://github.com/netbymatt/ws4kp/blob/main/datagenerators/regionalcities.mjs"
    click DG "https://github.com/netbymatt/ws4kp/blob/main/datagenerators/stations.mjs"
    click DG "https://github.com/netbymatt/ws4kp/blob/main/datagenerators/travelcities.mjs"
    click DG "https://github.com/netbymatt/ws4kp/tree/main/datagenerators/output/"
    click AuxS "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/index.mjs"
    click AuxS "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/data/regionalcities.js"
    click AuxS "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/data/stations.js"
    click AuxS "https://github.com/netbymatt/ws4kp/blob/main/server/scripts/data/travelcities.js"
    click Tests "https://github.com/netbymatt/ws4kp/tree/main/tests/"
    click Playlist "https://github.com/netbymatt/ws4kp/blob/main/src/playlist-reader.mjs"
    click Playlist "https://github.com/netbymatt/ws4kp/blob/main/src/playlist.mjs"
```
