# publicmap/electionmap architecture

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

- Interactive diagram: https://gitdiagram.com/publicmap/electionmap
- Repository: https://github.com/publicmap/electionmap

## Overview

##### Main Components
- User Interface (UI): Represented by the index.html that loads in the browser.
- Client‑side Javascript Modules: The various JS files (like ECILookup.js, add-marker.js, add-map-layers.js, addMapControls.js, locate-user.js, map-layer-config.js, query-layer-features.js, show-data-at-point.js, and the bundled file in js/dist) act as dedicated modules handling map initialization, querying the Mapbox API, dynamic control additions (e.g., layers and markers), and user interaction.
- External Services:
– Mapbox GL JS: The mapping engine that renders the basemap, constituency boundaries, and interactive layers.
– Mapbox Tile API: The external API call (as described in README) that provides constituency details via tile queries.
– OpenStreetMap: The source for street-level basemap details.
– Datameet Maps: The source for constituency shapefiles that are hosted on Mapbox.

##### Relationships and Interactions
- The User accesses the application via a browser that loads index.html.
- index.html references the bundled JavaScript (either directly from js/index.js during development or the compiled file in js/dist after a build).
- The main JavaScript (controller) coordinates the behavior of various modules:
- For example, ECILookup.js manages API calls to the Mapbox tile query URL for constituency data.
- -map-layers.js, add-marker.js, and addMapControls.js handle the addition of visual layers, markers, and interactive controls to the Mapbox instance.
- locate-user.js likely determines the user’s location to center the map.
- query-layer-features.js and show-data-at-point.js work together to identify and display data based on map interactions.
- All these modules depend on Mapbox GL JS to render the dynamic map, which in turn integrates basemap details (from OpenStreetMap) and constituency boundaries (via data hosted from Datameet Maps on Mapbox).
- npm scripts and node modules (specified in package.json) are used to manage dependencies and compile the JavaScript source into a single (or optimized) bundle available in the js/dist folder.

##### Architectural Patterns and Design Principles
- Modular Design: Each JavaScript file is dedicated to a particular map-handling task, lending well to separation of concerns.
- Client-Side Rendering: The architecture relies on the browser to render the UI and map components using external APIs, without a dedicated back‑end server.
- Build/Compilation Workflow: Note the development/build separation—changes are made to individual modules and then compiled to a distribution folder for production.
- External API Integration: Clear interaction with third-party services (Mapbox and OpenStreetMap) for data and rendering.

##### Technologies and Frameworks
- HTML and JavaScript form the client base.
- Mapbox GL JS for map rendering.
- Mapbox API for constituency data queries.
- npm (along with Node.js) for dependency management and building the final JavaScript bundle.
- Image assets and configuration files (such as .gitignore, LICENSE, and package files) support development and deployment practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    Browser["Client Browser"]:::ui
    IndexHTML["index.html"]:::ui

    %% JavaScript Controller and Modules
    subgraph "JavaScript Controller Layer"
        JSIndex["Main JavaScript Controller<br>(js/index.js)"]:::js
        ECILookup["Election Constituency Lookup<br>(js/ECILookup.js)"]:::js
        AddMapLayers["Map Layer Setup<br>(js/add-map-layers.js)"]:::js
        AddMarker["Marker Management<br>(js/add-marker.js)"]:::js
        AddMapControls["Map Controls<br>(js/addMapControls.js)"]:::js
        LocateUser["User Location Handling<br>(js/locate-user.js)"]:::js
        MapLayerConfig["Map Layer Configuration<br>(js/map-layer-config.js)"]:::js
        QueryLayerFeatures["Querying Map Features<br>(js/query-layer-features.js)"]:::js
        ShowDataAtPoint["Displaying Data at Map Points<br>(js/show-data-at-point.js)"]:::js
    end

    %% External Services
    MapboxGL["Mapbox GL JS Engine"]:::external
    MapboxTile["Mapbox Tile API"]:::external
    OpenStreetMap["OpenStreetMap<br>Basemap Details"]:::external
    Datameet["Datameet Maps via Mapbox<br>Shapefiles"]:::external

    %% Build/Dev Tools
    Build["Production Build<br>(Bundled JS: js/dist/index.js)"]:::build
    BuildTool["Dependency/Build Management<br>(package.json)"]:::build

    %% UI Flow
    Browser --> IndexHTML
    IndexHTML --> JSIndex

    %% Controller Module Interactions
    JSIndex --> ECILookup
    JSIndex --> AddMapLayers
    JSIndex --> AddMarker
    JSIndex --> AddMapControls
    JSIndex --> LocateUser
    JSIndex --> MapLayerConfig
    JSIndex --> QueryLayerFeatures
    JSIndex --> ShowDataAtPoint

    %% Modules Communicating with External Services
    ECILookup -->|"tile_query"| MapboxTile
    AddMapLayers --> MapboxGL
    AddMarker --> MapboxGL
    AddMapControls --> MapboxGL
    LocateUser --> MapboxGL
    MapLayerConfig --> MapboxGL
    QueryLayerFeatures --> MapboxGL
    ShowDataAtPoint --> MapboxGL

    %% External Service Integrations
    MapboxGL --> OpenStreetMap
    MapboxGL --> Datameet

    %% Build Process Connections
    JSIndex --- Build
    ECILookup --- Build
    AddMapLayers --- Build
    AddMarker --- Build
    AddMapControls --- Build
    LocateUser --- Build
    MapLayerConfig --- Build
    QueryLayerFeatures --- Build
    ShowDataAtPoint --- Build
    Build --- BuildTool

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#036,stroke-width:2px;
    classDef js fill:#90EE90,stroke:#060,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef build fill:#D3D3D3,stroke:#808080,stroke-width:2px;

    %% Click Events
    click IndexHTML "https://github.com/publicmap/electionmap/blob/master/index.html"
    click JSIndex "https://github.com/publicmap/electionmap/blob/master/js/index.js"
    click ECILookup "https://github.com/publicmap/electionmap/blob/master/js/ECILookup.js"
    click AddMapLayers "https://github.com/publicmap/electionmap/blob/master/js/add-map-layers.js"
    click AddMarker "https://github.com/publicmap/electionmap/blob/master/js/add-marker.js"
    click AddMapControls "https://github.com/publicmap/electionmap/blob/master/js/addMapControls.js"
    click LocateUser "https://github.com/publicmap/electionmap/blob/master/js/locate-user.js"
    click MapLayerConfig "https://github.com/publicmap/electionmap/blob/master/js/map-layer-config.js"
    click QueryLayerFeatures "https://github.com/publicmap/electionmap/blob/master/js/query-layer-features.js"
    click ShowDataAtPoint "https://github.com/publicmap/electionmap/blob/master/js/show-data-at-point.js"
    click Build "https://github.com/publicmap/electionmap/blob/master/js/dist/index.js"
    click BuildTool "https://github.com/publicmap/electionmap/blob/master/package.json"
```
