# octapokta/ethnic-map-public architecture

> Architecture diagram of the GitHub repository octapokta/ethnic-map-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/octapokta/ethnic-map-public
- Repository: https://github.com/octapokta/ethnic-map-public

## Overview

Middle East Ethnic Map is a browser-based interactive demographic atlas. Users enter through the welcome screen, choose country layers or a cross-border ethnicity, and explore the rendered map with pan and zoom; selecting demographic or city details opens dossiers. The map, data, and DOM-building modules are evidenced in the sampled source. README-described routing, tutorial, and analytics are retained, but analytics wiring and several subsystem internals were not sampled, so uncertain links are omitted.

Main entry points: [`js/ui/ui-builder.js`](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-builder.js) (DOM and layer builder), [`js/ui/ui-events.js`](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-events.js) (UI event handlers), [`js/ui/ui-core.js`](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-core.js) (UI state and routing), [`js/ui/ui-panels.js`](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-panels.js) (Demographic dossiers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Map experience"]
  node_map_engine["Map physics and rendering<br/>[map.js]"]
  node_panels["Demographic dossiers<br/>[ui-panels.js]"]
end

subgraph group_content["Map content"]
  node_builder["DOM and layer builder<br/>[ui-builder.js]"]
  node_config["App and image config<br/>[data-config.js]"]
  node_countries["Country demographics<br/>[data-countries.js]"]
  node_cities["City data<br/>[data-cities.js]"]
  node_regional_assets["Map image assets"]
end

subgraph group_interface["Interface and navigation"]
  node_app["Application entry<br/>[index.html]"]
  node_welcome["Welcome and loading<br/>[ui-welcome.js]"]
  node_ui_core["UI state and routing<br/>[ui-core.js]"]
  node_ui_events["UI event handlers<br/>[ui-events.js]"]
  node_ui_utils["UI utilities<br/>[ui-utils.js]"]
  node_audio["Sound effects<br/>[audio.js]"]
  node_tutorial["Tutorial interface<br/>[ui-core.js]"]
end

subgraph group_services["External services"]
  node_contact_service["Contact form service"]
  node_analytics["Google Analytics 4"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens"| node_welcome
node_visitor -->|"selects and controls"| node_ui_events
node_app -->|"sets up loading"| node_welcome
node_app -->|"initializes UI"| node_ui_core
node_welcome -.->|"submits form"| node_contact_service
node_ui_core -->|"injects data"| node_builder
node_config -->|"provides config"| node_builder
node_countries -->|"provides country data"| node_builder
node_cities -->|"provides city data"| node_builder
node_regional_assets -->|"supplies map imagery"| node_builder
node_ui_events -->|"updates layer state"| node_ui_core
node_ui_events -->|"resets map view"| node_map_engine
node_ui_events -->|"plays sounds"| node_audio
node_ui_events -->|"selects demographics"| node_panels
node_builder -->|"opens regional dossier"| node_panels
node_panels -->|"drags and layers panels"| node_ui_utils
node_map_engine -->|"reads country views"| node_ui_core
node_ui_core -->|"routes tutorial state"| node_tutorial
node_visitor -.->|"interaction tracking"| node_analytics

click node_app "https://github.com/octapokta/ethnic-map-public/blob/main/index.html"
click node_welcome "https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-welcome.js"
click node_ui_core "https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-core.js"
click node_ui_events "https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-events.js"
click node_builder "https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-builder.js"
click node_map_engine "https://github.com/octapokta/ethnic-map-public/blob/main/js/core/map.js"
click node_panels "https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-panels.js"
click node_ui_utils "https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-utils.js"
click node_audio "https://github.com/octapokta/ethnic-map-public/blob/main/js/core/audio.js"
click node_config "https://github.com/octapokta/ethnic-map-public/blob/main/js/data/data-config.js"
click node_countries "https://github.com/octapokta/ethnic-map-public/blob/main/js/data/data-countries.js"
click node_cities "https://github.com/octapokta/ethnic-map-public/blob/main/js/data/data-cities.js"
click node_regional_assets "https://github.com/octapokta/ethnic-map-public/tree/main/images"
click node_tutorial "https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-core.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_map_engine,node_panels toneBlue
class node_builder,node_config,node_countries,node_cities,node_regional_assets toneAmber
class node_app,node_welcome,node_ui_core,node_ui_events,node_ui_utils,node_audio,node_tutorial toneMint
class node_contact_service,node_analytics toneRose
class node_visitor toneIndigo
```

## Components

### Map experience

- [Map physics and rendering](https://github.com/octapokta/ethnic-map-public/blob/main/js/core/map.js): `js/core/map.js`
- [Demographic dossiers](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-panels.js): `js/ui/ui-panels.js`

### Map content

- [DOM and layer builder](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-builder.js): `js/ui/ui-builder.js`
- [App and image config](https://github.com/octapokta/ethnic-map-public/blob/main/js/data/data-config.js): `js/data/data-config.js`
- [Country demographics](https://github.com/octapokta/ethnic-map-public/blob/main/js/data/data-countries.js): `js/data/data-countries.js`
- [City data](https://github.com/octapokta/ethnic-map-public/blob/main/js/data/data-cities.js): `js/data/data-cities.js`
- [Map image assets](https://github.com/octapokta/ethnic-map-public/tree/main/images): `images`

### Interface and navigation

- [Application entry](https://github.com/octapokta/ethnic-map-public/blob/main/index.html): `index.html`
- [Welcome and loading](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-welcome.js): `js/ui/ui-welcome.js`
- [UI state and routing](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-core.js): `js/ui/ui-core.js`
- [UI event handlers](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-events.js): `js/ui/ui-events.js`
- [UI utilities](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-utils.js): `js/ui/ui-utils.js`
- [Sound effects](https://github.com/octapokta/ethnic-map-public/blob/main/js/core/audio.js): `js/core/audio.js`
- [Tutorial interface](https://github.com/octapokta/ethnic-map-public/blob/main/js/ui/ui-core.js): `js/ui/ui-core.js`

### External services

- **Contact form service**
- **Google Analytics 4**

### Other components

- **Visitor**

## Connections

- Visitor → Welcome and loading: opens
- Visitor → UI event handlers: selects and controls
- Application entry → Welcome and loading: sets up loading
- Application entry → UI state and routing: initializes UI
- Welcome and loading → Contact form service: submits form
- UI state and routing → DOM and layer builder: injects data
- App and image config → DOM and layer builder: provides config
- Country demographics → DOM and layer builder: provides country data
- City data → DOM and layer builder: provides city data
- Map image assets → DOM and layer builder: supplies map imagery
- UI event handlers → UI state and routing: updates layer state
- UI event handlers → Map physics and rendering: resets map view
- UI event handlers → Sound effects: plays sounds
- UI event handlers → Demographic dossiers: selects demographics
- DOM and layer builder → Demographic dossiers: opens regional dossier
- Demographic dossiers → UI utilities: drags and layers panels
- Map physics and rendering → UI state and routing: reads country views
- UI state and routing → Tutorial interface: routes tutorial state
- Visitor → Google Analytics 4: interaction tracking