# jemcats-software/maple architecture

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

- Interactive diagram: https://gitdiagram.com/jemcats-software/maple
- Repository: https://github.com/jemcats-software/maple

## Overview

MAPLE converts Plus Codes to memorable four-word codes and back; its coordinate interface converts latitude/longitude through Plus Codes. Node.js and browser implementations expose the core capability, while a small Express service provides HTTP endpoints and optional usage statistics. The README establishes the encoding purpose; source excerpts confirm the Node.js and service flows. Browser pages and some modules are present in the tree but were not sampled, so their internal wiring is not inferred.

Main entry points: [`nodejs/index.js`](https://github.com/jemcats-software/maple/blob/main/nodejs/index.js) (Node entry), [`docker/main_scripts/index.js`](https://github.com/jemcats-software/maple/blob/main/docker/main_scripts/index.js) (HTTP API), [`nodejs/src/MAPLE-coords.js`](https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE-coords.js) (Coordinate codec), [`nodejs/src/MAPLE.js`](https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE.js) (Word-code codec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_node_entry["Node entry<br/>[index.js]"]
  node_browser_library["Browser library<br/>[MAPLE-full.js]"]
  node_web_pages["Web pages"]
end

subgraph group_encoding["Encoding library"]
  node_maple_core["Word-code codec<br/>[MAPLE.js]"]
  node_maple_helper["List loader and alphabet<br/>[MAPLE-helper.js]"]
  node_coords["Coordinate codec<br/>[MAPLE-coords.js]"]
  node_browser_full["Browser codec and loader<br/>[MAPLE-full.js]"]
end

subgraph group_service["HTTP service"]
  node_http_api["HTTP API<br/>[index.js]"]
end

subgraph group_data["Word and stats data"]
  node_word_lists["Word-list files<br/>[words_1.json]"]
  node_stats[("Request statistics<br/>[stats.json]")]
end

node_user(("User or caller"))
node_remote_lists["Hosted word lists"]
node_olc_lib["Plus Codes library"]

node_user -->|"uses"| node_node_entry
node_node_entry -->|"assembles"| node_maple_helper
node_node_entry -->|"assembles"| node_maple_core
node_node_entry -->|"assembles"| node_coords
node_maple_helper -->|"fetches lists"| node_remote_lists
node_maple_core -->|"uses lists"| node_maple_helper
node_coords -->|"encodes or decodes"| node_maple_core
node_coords -->|"converts coordinates"| node_olc_lib
node_user -->|"uses"| node_browser_library
node_browser_full -->|"fetches lists"| node_remote_lists
node_browser_library -->|"loads codec"| node_browser_full
node_user -->|"visits"| node_web_pages
node_user -->|"requests"| node_http_api
node_http_api -->|"encodes or decodes"| node_maple_core
node_http_api -->|"converts coordinates"| node_coords
node_http_api -->|"reads and writes"| node_stats

click node_node_entry "https://github.com/jemcats-software/maple/blob/main/nodejs/index.js"
click node_browser_library "https://github.com/jemcats-software/maple/blob/main/js/MAPLE-full.js"
click node_web_pages "https://github.com/jemcats-software/maple/tree/main/webpage"
click node_http_api "https://github.com/jemcats-software/maple/blob/main/docker/main_scripts/index.js"
click node_maple_core "https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE.js"
click node_maple_helper "https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE-helper.js"
click node_coords "https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE-coords.js"
click node_browser_full "https://github.com/jemcats-software/maple/blob/main/js/MAPLE-full.js"
click node_word_lists "https://github.com/jemcats-software/maple/blob/main/assets/dist/words_1.json"
click node_stats "https://github.com/jemcats-software/maple/blob/main/docker/data/stats.json"

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_node_entry,node_browser_library,node_web_pages,node_user toneBlue
class node_maple_core,node_maple_helper,node_coords,node_browser_full toneAmber
class node_http_api toneMint
class node_word_lists,node_stats toneRose
class node_remote_lists,node_olc_lib toneIndigo
```

## Components

### Clients

- [Node entry](https://github.com/jemcats-software/maple/blob/main/nodejs/index.js): `nodejs/index.js`
- [Browser library](https://github.com/jemcats-software/maple/blob/main/js/MAPLE-full.js): `js/MAPLE-full.js`
- [Web pages](https://github.com/jemcats-software/maple/tree/main/webpage): `webpage`

### Encoding library

- [Word-code codec](https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE.js): `nodejs/src/MAPLE.js`
- [List loader and alphabet](https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE-helper.js): `nodejs/src/MAPLE-helper.js`
- [Coordinate codec](https://github.com/jemcats-software/maple/blob/main/nodejs/src/MAPLE-coords.js): `nodejs/src/MAPLE-coords.js`
- [Browser codec and loader](https://github.com/jemcats-software/maple/blob/main/js/MAPLE-full.js): `js/MAPLE-full.js`

### HTTP service

- [HTTP API](https://github.com/jemcats-software/maple/blob/main/docker/main_scripts/index.js): `docker/main_scripts/index.js`

### Word and stats data

- [Word-list files](https://github.com/jemcats-software/maple/blob/main/assets/dist/words_1.json): `assets/dist/words_1.json`
- [Request statistics](https://github.com/jemcats-software/maple/blob/main/docker/data/stats.json): `docker/data/stats.json`

### Other components

- **User or caller**
- **Hosted word lists**
- **Plus Codes library**

## Connections

- User or caller → Node entry: uses
- Node entry → List loader and alphabet: assembles
- Node entry → Word-code codec: assembles
- Node entry → Coordinate codec: assembles
- List loader and alphabet → Hosted word lists: fetches lists
- Word-code codec → List loader and alphabet: uses lists
- Coordinate codec → Word-code codec: encodes or decodes
- Coordinate codec → Plus Codes library: converts coordinates
- User or caller → Browser library: uses
- Browser codec and loader → Hosted word lists: fetches lists
- Browser library → Browser codec and loader: loads codec
- User or caller → Web pages: visits
- User or caller → HTTP API: requests
- HTTP API → Word-code codec: encodes or decodes
- HTTP API → Coordinate codec: converts coordinates
- HTTP API → Request statistics: reads and writes