# ye-shapovalov/katottg-data-toolkit architecture

> Architecture diagram of the GitHub repository ye-shapovalov/katottg-data-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ye-shapovalov/katottg-data-toolkit
- Repository: https://github.com/ye-shapovalov/katottg-data-toolkit

## Overview

KATOTTG Data Toolkit prepares administrative and territorial-status records from user-supplied Word/Excel files, packages them with optional geographic enrichment, and provides a browser viewer for searching and inspecting prepared data. The graph includes documented viewer and converter capabilities even where their implementation was not sampled; edges for those interactions rely on README statements, not inspection of unsampled source.

Main entry points: [`index.html`](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html) (Prepared local data), [`tools/prepare_data.html`](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data.html) (Preparation interface), [`tools/prepare_data_core.js`](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js) (JSON/XLSX export), [`tools/status_summary.js`](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/status_summary.js) (Settlement summaries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prepare["Data preparation"]
  node_prepui["Preparation interface<br/>[prepare_data.html]"]
  node_table_reader["Word/Excel reader"]
  node_table_detection["Table detection"]
  node_record_normalization["Record normalization"]
  node_record_merge["Code-based merge"]
  node_hierarchy["Hierarchy resolution"]
end

subgraph group_shared["Shared data logic"]
  node_summary_logic["Settlement summaries<br/>[status_summary.js]"]
end

subgraph group_package["Export and enrichment"]
  node_export["JSON/XLSX export"]
  node_geo_enrichment["GeoJSON enrichment<br/>[prepare_data.html]"]
  node_download["ZIP package<br/>[prepare_data.html]"]
end

subgraph group_viewer["Registry viewer"]
  node_viewer["Registry application<br/>[index.html]"]
  node_local_data[("Prepared local data<br/>[index.html]")]
  node_search_filters["Search and filters<br/>[index.html]"]
  node_parent_summaries["Parent summaries<br/>[index.html]"]
  node_table_hierarchy["Table and hierarchy<br/>[index.html]"]
  node_map_view["Settlement map<br/>[settlement_map.js]"]
  node_url_state["URL view state"]
end

node_user(("Data user"))
node_sourcefiles["Source documents"]
node_boundaries["Boundary GeoJSON"]
node_tiles["Online map resources"]

node_user -->|"uploads files"| node_prepui
node_sourcefiles -->|"provides inputs"| node_prepui
node_prepui -->|"reads tables"| node_table_reader
node_table_reader -->|"extracts tables"| node_table_detection
node_table_detection -->|"identifies columns"| node_record_normalization
node_record_normalization -->|"normalizes records"| node_record_merge
node_record_merge -->|"resolves parents"| node_hierarchy
node_record_merge -->|"summarizes parents"| node_summary_logic
node_hierarchy -->|"supplies records"| node_export
node_summary_logic -->|"supplies summaries"| node_export
node_prepui -->|"exports results"| node_export
node_boundaries -->|"provides geometry"| node_geo_enrichment
node_export -->|"enriches from JSON"| node_geo_enrichment
node_geo_enrichment -->|"packages outputs"| node_download
node_user -->|"opens viewer"| node_viewer
node_viewer -->|"loads records"| node_local_data
node_local_data -->|"filters records"| node_search_filters
node_local_data -->|"summarizes settlements"| node_parent_summaries
node_parent_summaries -->|"uses shared logic"| node_summary_logic
node_search_filters -->|"presents results"| node_table_hierarchy
node_search_filters -->|"selects map results"| node_map_view
node_local_data -->|"provides geographic data"| node_map_view
node_map_view -->|"uses map resources"| node_tiles
node_viewer -->|"preserves view state"| node_url_state
node_url_state -->|"restores address state"| node_viewer

click node_prepui "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data.html"
click node_table_reader "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js"
click node_table_detection "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js"
click node_record_normalization "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js"
click node_record_merge "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js"
click node_hierarchy "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js"
click node_summary_logic "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/status_summary.js"
click node_export "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js"
click node_geo_enrichment "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data.html"
click node_download "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data.html"
click node_viewer "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html"
click node_local_data "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html"
click node_search_filters "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html"
click node_parent_summaries "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html"
click node_table_hierarchy "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html"
click node_map_view "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/settlement_map.js"
click node_url_state "https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/registry_url_state.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_prepui,node_table_reader,node_table_detection,node_record_normalization,node_record_merge,node_hierarchy,node_user toneBlue
class node_summary_logic toneAmber
class node_export,node_geo_enrichment,node_download toneMint
class node_viewer,node_local_data,node_search_filters,node_parent_summaries,node_table_hierarchy,node_map_view,node_url_state toneRose
class node_sourcefiles,node_boundaries,node_tiles toneIndigo
```

## Components

### Data preparation

- [Preparation interface](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data.html): `tools/prepare_data.html`
- [Word/Excel reader](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js): `tools/prepare_data_core.js`
- [Table detection](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js): `tools/prepare_data_core.js`
- [Record normalization](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js): `tools/prepare_data_core.js`
- [Code-based merge](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js): `tools/prepare_data_core.js`
- [Hierarchy resolution](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js): `tools/prepare_data_core.js`

### Shared data logic

- [Settlement summaries](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/status_summary.js): `tools/status_summary.js`

### Export and enrichment

- [JSON/XLSX export](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data_core.js): `tools/prepare_data_core.js`
- [GeoJSON enrichment](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data.html): `tools/prepare_data.html`
- [ZIP package](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/prepare_data.html): `tools/prepare_data.html`

### Registry viewer

- [Registry application](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html): `index.html`
- [Prepared local data](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html): `index.html`
- [Search and filters](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html): `index.html`
- [Parent summaries](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html): `index.html`
- [Table and hierarchy](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/index.html): `index.html`
- [Settlement map](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/settlement_map.js): `tools/settlement_map.js`
- [URL view state](https://github.com/ye-shapovalov/katottg-data-toolkit/blob/main/tools/registry_url_state.js): `tools/registry_url_state.js`

### Other components

- **Data user**
- **Source documents**
- **Boundary GeoJSON**
- **Online map resources**

## Connections

- Data user → Preparation interface: uploads files (evidence: `README.md`)
- Source documents → Preparation interface: provides inputs (evidence: `README.md`)
- Preparation interface → Word/Excel reader: reads tables (evidence: `tools/prepare_data_core.js`)
- Word/Excel reader → Table detection: extracts tables (evidence: `README.md`)
- Table detection → Record normalization: identifies columns (evidence: `README.md`)
- Record normalization → Code-based merge: normalizes records (evidence: `tools/prepare_data_core.js`)
- Code-based merge → Hierarchy resolution: resolves parents (evidence: `tools/prepare_data_core.js`)
- Code-based merge → Settlement summaries: summarizes parents (evidence: `tools/prepare_data_core.js`)
- Hierarchy resolution → JSON/XLSX export: supplies records (evidence: `README.md`)
- Settlement summaries → JSON/XLSX export: supplies summaries (evidence: `README.md`)
- Preparation interface → JSON/XLSX export: exports results (evidence: `README.md`)
- Boundary GeoJSON → GeoJSON enrichment: provides geometry (evidence: `README.md`)
- JSON/XLSX export → GeoJSON enrichment: enriches from JSON (evidence: `README.md`)
- GeoJSON enrichment → ZIP package: packages outputs (evidence: `README.md`)
- Data user → Registry application: opens viewer (evidence: `README.md`)
- Registry application → Prepared local data: loads records (evidence: `README.md`)
- Prepared local data → Search and filters: filters records (evidence: `README.md`)
- Prepared local data → Parent summaries: summarizes settlements (evidence: `README.md`)
- Parent summaries → Settlement summaries: uses shared logic (evidence: `README.md`)
- Search and filters → Table and hierarchy: presents results (evidence: `README.md`)
- Search and filters → Settlement map: selects map results (evidence: `README.md`)
- Prepared local data → Settlement map: provides geographic data (evidence: `README.md`)
- Settlement map → Online map resources: uses map resources (evidence: `README.md`)
- Registry application → URL view state: preserves view state (evidence: `README.md`)
- URL view state → Registry application: restores address state (evidence: `README.md`)
