# oac-tw/oac-spa architecture

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

- Interactive diagram: https://gitdiagram.com/oac-tw/oac-spa
- Repository: https://github.com/oac-tw/oac-spa

## Overview

##### Main components of the system
- Frontend Application – This is mainly implemented under “src”. It includes:
– The main Vue.js application (src/main.js) that bootstraps the UI.
– A series of Vue components (under src/components) covering the UI elements for maps (mapUI, mapUIxs), layers (layer, layerBaseMap, layerLegend, etc.), search functionality, filtering, and additional interactive parts.
– Styling (custom.scss, element-variables.scss) for theming and layout.
- State Management – Vuex is used (src/store.js plus separate state files such as layerState.js and resultState.js) to manage the application’s state across UI components.
- & Layer Management – This is a central area of the application where the following reside:
– Configuration files (public/layerDef.json, public/layerCatelog.json, public/layerLegend.json, public/layerTag.json) define layer behaviors, definitions, and legends.
– Leaflet-based mapping logic and extensions, implemented in both JavaScript (src) and TypeScript (typescript folder). The TypeScript modules extend Leaflet’s capabilities by including various layer types (e.g., geojsonLayer, gradientLayer, typhoonLayer, velocity layers, etc.).
- PWA and Deployment Components – The project uses a service worker (src/sw.js, src/sw-manifest.js) configured with workbox, as well as deployment scripts (deploy.js, with MSDeploy configuration guidelines in IIS_config.md) and webpack or babel configurations (vue.config.js, babel.config.js) that tailor the build for production.

##### Out relationships and interactions
- The Vue frontend interacts with the state management layer (Vuex) which in turn coordinates data and visibility settings for various mapping components.
- The mapping modules (both in Vue components and in the TypeScript layer modules) fetch configuration details from the public JSON files to initialize base layers, overlays, and legends.
- The service worker and PWA integration (configured through workbox and manifest-related settings) handle caching and offline accessibility: a key aspect that touches the loading of map tiles and assets.
- Deployment and build processes (e.g., npm run serve, npm run build, npm run deploy) are orchestrated via the provided configuration files, deploy.js, and package.json scripts, showing a separation between development and production pipelines.

##### Significant architectural patterns/design principles
- Component-based UI: The project is broken down into modular Vue components that manage discrete UI elements.
- State-driven Architecture: Vuex is set up to modularize state (layer, result, etc.) ensuring that global application state is maintained in an organized way.
- Separation of Concerns: The system cleanly separates presentation (Vue components), state (Vuex), business logic (map and layer modules in both JS and TypeScript), and configuration (JSON files in public).
- Progressive Enhancement: The use of PWA techniques via service workers and Workbox to improve performance and offline availability.
- Extensibility: The TypeScript directory demonstrates a modular and extensible approach to extending Leaflet’s functionality for several kinds of dynamic layers.

##### Relevant technologies and frameworks
- Vue.js and Vuex for the front-end UI and state management.
- Leaflet with extended TypeScript modules for mapping and geospatial visualizations.
- Workbox, service workers, and PWA-related technologies for caching and offline support.
- Webpack configurations (via vue.config.js, babel.config.js) to drive the build/deployment process.
- MSDeploy for deployment (with details in IIS_config.md and deploy.js).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Application
    subgraph "Frontend Application"
        F1["Main Vue App"]
        F2["Vue Components"]
        F3["Styling"]
        F3a["custom.scss"]
        F3b["element-variables.scss"]
    end

    %% State Management
    subgraph "State Management"
        S1["Global Store"]
        S2["layerState.js"]
        S3["resultState.js"]
        S4["filterState.js"]
    end

    %% Mapping & Layers
    subgraph "Mapping & Layers"
        subgraph "JSON Configuration Files"
            M1a["layerDef.json"]
            M1b["layerCatelog.json"]
            M1c["layerLegend.json"]
            M1d["layerTag.json"]
        end
        subgraph "Vue Mapping Components"
            M2a["mapUI.vue"]
            M2b["mapUIxs.vue"]
        end
        subgraph "Leaflet Extensions"
            M3a["geojsonLayer.ts"]
            M3b["gradientLayer.ts"]
            M3c["typhoonLayer.ts"]
            M3d["velocity (directory)"]
        end
    end

    %% Public Assets & Configuration
    subgraph "Public Assets & Configuration"
        P1["index.html"]
        P2["Assets (folder)"]
        P3["Map Layers (folder)"]
        P4["Public Resources (folder)"]
    end

    %% PWA and Deployment
    subgraph "PWA and Deployment"
        subgraph "PWA"
            W1["Service Worker"]
            W2["SW Manifest"]
        end
        subgraph "Deployment & Build Pipeline"
            D1["deploy.js"]
            D2["IIS_config.md"]
            D3["vue.config.js"]
            D4["babel.config.js"]
        end
    end

    %% Connections between components
    F1 -->|"bootstraps"| F2
    F2 -->|"updatesState"| S1
    F2 -->|"updatesState"| S2
    F2 -->|"updatesState"| S3
    F2 -->|"updatesState"| S4

    M1a -->|"configures"| M2a
    M1b -->|"configures"| M2a
    M1c -->|"configures"| M2b
    M1d -->|"configures"| M2b

    M3a -->|"extends"| M2a
    M3b -->|"extends"| M2a
    M3c -->|"extends"| M2b
    M3d -->|"extends"| M2b

    S2 -->|"informs"| M2a
    S3 -->|"informs"| M2b

    W1 -->|"caches"| P1
    W2 -->|"manifests"| P1
    W1 -->|"interacts"| F1

    D1 -->|"deploys"| F1
    D1 -->|"deploys"| S1
    D1 -->|"deploys"| M1a
    D3 -->|"builds"| F2
    D4 -->|"builds"| F2

    F3 --> F3a
    F3 --> F3b

    D1 -->|"deploys"| P2
    D1 -->|"deploys"| P3
    D1 -->|"deploys"| P4

    %% Click Events for Frontend Application
    click F1 "https://github.com/oac-tw/oac-spa/blob/master/src/main.js"
    click F2 "https://github.com/oac-tw/oac-spa/tree/master/src/components"
    click F3a "https://github.com/oac-tw/oac-spa/blob/master/src/custom.scss"
    click F3b "https://github.com/oac-tw/oac-spa/blob/master/src/element-variables.scss"

    %% Click Events for State Management
    click S1 "https://github.com/oac-tw/oac-spa/blob/master/src/store.js"
    click S2 "https://github.com/oac-tw/oac-spa/blob/master/src/components/layer/layerState.js"
    click S3 "https://github.com/oac-tw/oac-spa/blob/master/src/components/result/resultState.js"
    click S4 "https://github.com/oac-tw/oac-spa/blob/master/src/components/filterState.js"

    %% Click Events for Mapping & Layers - JSON Configuration Files
    click M1a "https://github.com/oac-tw/oac-spa/blob/master/public/layerDef.json"
    click M1b "https://github.com/oac-tw/oac-spa/blob/master/public/layerCatelog.json"
    click M1c "https://github.com/oac-tw/oac-spa/blob/master/public/layerLegend.json"
    click M1d "https://github.com/oac-tw/oac-spa/blob/master/public/layerTag.json"

    %% Click Events for Mapping & Layers - Vue Mapping Components
    click M2a "https://github.com/oac-tw/oac-spa/blob/master/src/components/mapUI.vue"
    click M2b "https://github.com/oac-tw/oac-spa/blob/master/src/components/mapUIxs.vue"

    %% Click Events for Mapping & Layers - Leaflet Extensions
    click M3a "https://github.com/oac-tw/oac-spa/blob/master/typescript/src/layer/geojsonLayer.ts"
    click M3b "https://github.com/oac-tw/oac-spa/blob/master/typescript/src/layer/gradientLayer.ts"
    click M3c "https://github.com/oac-tw/oac-spa/blob/master/typescript/src/layer/typhoonLayer.ts"
    click M3d "https://github.com/oac-tw/oac-spa/tree/master/typescript/src/layer/velocity"

    %% Click Events for Public Assets & Configuration
    click P1 "https://github.com/oac-tw/oac-spa/blob/master/public/index.html"
    click P2 "https://github.com/oac-tw/oac-spa/tree/master/public/assets"
    click P3 "https://github.com/oac-tw/oac-spa/tree/master/public/layers"
    click P4 "https://github.com/oac-tw/oac-spa/tree/master/public/res"

    %% Click Events for PWA and Deployment
    click W1 "https://github.com/oac-tw/oac-spa/blob/master/src/sw.js"
    click W2 "https://github.com/oac-tw/oac-spa/blob/master/src/sw-manifest.js"
    click D1 "https://github.com/oac-tw/oac-spa/blob/master/deploy.js"
    click D2 "https://github.com/oac-tw/oac-spa/blob/master/IIS_config.md"
    click D3 "https://github.com/oac-tw/oac-spa/blob/master/vue.config.js"
    click D4 "https://github.com/oac-tw/oac-spa/blob/master/babel.config.js"

    %% Styles for color coding
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef state fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef map fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef public fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef pwa fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef build fill:#FFA500,stroke:#000,stroke-width:2px;

    class F1,F2,F3,F3a,F3b ui;
    class S1,S2,S3,S4 state;
    class M1a,M1b,M1c,M1d,M2a,M2b,M3a,M3b,M3c,M3d map;
    class P1,P2,P3,P4 public;
    class W1,W2 pwa;
    class D1,D2,D3,D4 build;
```
