# koaokano/geosplit architecture

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

- Interactive diagram: https://gitdiagram.com/koaokano/geosplit
- Repository: https://github.com/koaokano/geosplit

## Overview

GeoSplit is a Python CLI and API for validating GeoJSON, splitting FeatureCollections and GeoPackage layers, and converting between GeoJSON and GeoPackage. The main user workflow enters through the CLI or public Python API, then reaches validation, planning, and splitting or conversion. Core also handles streamed GeoJSON parsing and recoverable output transactions. GeoPackage operations depend on optional GeoPandas support. The graph follows excerpted calls and README-described capabilities; unsampled core paths are not expanded into additional implementation details.

Main entry points: [`src/geosplit/cli.py`](https://github.com/koaokano/geosplit/blob/main/src/geosplit/cli.py) (Command interface), [`src/geosplit/core.py`](https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py) (Streaming and splitting), [`src/geosplit/convert.py`](https://github.com/koaokano/geosplit/blob/main/src/geosplit/convert.py) (GeoPackage splitting), [`src/geosplit/__init__.py`](https://github.com/koaokano/geosplit/blob/main/src/geosplit/__init__.py) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["Command interface<br/>[cli.py]"]
  node_public_api["Public API<br/>[__init__.py]"]
end

subgraph group_geojson["GeoJSON processing"]
  node_validation["GeoJSON validation<br/>[validation.py]"]
  node_streaming["Streaming and splitting<br/>[core.py]"]
  node_batch_api["Batch iteration<br/>[core.py]"]
  node_split_planning["Split planning<br/>[core.py]"]
  node_geojson_output["GeoJSON chunks<br/>[core.py]"]
end

subgraph group_package["GeoPackage operations"]
  node_conversion["Format conversion<br/>[convert.py]"]
  node_gpkg_split["GeoPackage splitting<br/>[convert.py]"]
  node_geopandas["GeoPandas"]
end

subgraph group_output["Output management"]
  node_transaction["Output transactions<br/>[core.py]"]
  node_filesystem[("Output files")]
end

node_user(("CLI user"))
node_python_user(("Python API user"))

node_user -->|"runs commands"| node_cli
node_python_user -->|"calls API"| node_public_api
node_cli -->|"validates"| node_validation
node_cli -->|"splits GeoJSON"| node_streaming
node_cli -->|"plans splits"| node_split_planning
node_cli -->|"converts formats"| node_conversion
node_cli -->|"splits layers"| node_gpkg_split
node_public_api -->|"exports split API"| node_streaming
node_public_api -->|"exports validation"| node_validation
node_validation -->|"reads features"| node_streaming
node_streaming -->|"yields batches"| node_batch_api
node_streaming -->|"builds plans"| node_split_planning
node_split_planning -->|"plans chunks"| node_geojson_output
node_streaming -.->|"stages outputs"| node_transaction
node_transaction -.->|"commits files"| node_filesystem
node_conversion -->|"reads and writes"| node_geopandas
node_gpkg_split -->|"reads layers"| node_geopandas
node_gpkg_split -->|"commits chunks"| node_transaction
node_conversion -->|"writes converted file"| node_filesystem
node_gpkg_split -->|"writes layer chunks"| node_filesystem

click node_cli "https://github.com/koaokano/geosplit/blob/main/src/geosplit/cli.py"
click node_public_api "https://github.com/koaokano/geosplit/blob/main/src/geosplit/__init__.py"
click node_validation "https://github.com/koaokano/geosplit/blob/main/src/geosplit/validation.py"
click node_streaming "https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py"
click node_batch_api "https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py"
click node_split_planning "https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py"
click node_geojson_output "https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py"
click node_conversion "https://github.com/koaokano/geosplit/blob/main/src/geosplit/convert.py"
click node_gpkg_split "https://github.com/koaokano/geosplit/blob/main/src/geosplit/convert.py"
click node_transaction "https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py"

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_cli,node_public_api,node_user,node_python_user toneBlue
class node_validation,node_streaming,node_batch_api,node_split_planning,node_geojson_output toneAmber
class node_conversion,node_gpkg_split,node_geopandas toneMint
class node_transaction,node_filesystem toneRose
```

## Components

### User entry points

- [Command interface](https://github.com/koaokano/geosplit/blob/main/src/geosplit/cli.py): `src/geosplit/cli.py`
- [Public API](https://github.com/koaokano/geosplit/blob/main/src/geosplit/__init__.py): `src/geosplit/__init__.py`

### GeoJSON processing

- [GeoJSON validation](https://github.com/koaokano/geosplit/blob/main/src/geosplit/validation.py): `src/geosplit/validation.py`
- [Streaming and splitting](https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py): `src/geosplit/core.py`
- [Batch iteration](https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py): `src/geosplit/core.py`
- [Split planning](https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py): `src/geosplit/core.py`
- [GeoJSON chunks](https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py): `src/geosplit/core.py`

### GeoPackage operations

- [Format conversion](https://github.com/koaokano/geosplit/blob/main/src/geosplit/convert.py): `src/geosplit/convert.py`
- [GeoPackage splitting](https://github.com/koaokano/geosplit/blob/main/src/geosplit/convert.py): `src/geosplit/convert.py`
- **GeoPandas**

### Output management

- [Output transactions](https://github.com/koaokano/geosplit/blob/main/src/geosplit/core.py): `src/geosplit/core.py`
- **Output files**

### Other components

- **CLI user**
- **Python API user**

## Connections

- CLI user → Command interface: runs commands
- Python API user → Public API: calls API (evidence: `src/geosplit/__init__.py`)
- Command interface → GeoJSON validation: validates (evidence: `src/geosplit/cli.py`)
- Command interface → Streaming and splitting: splits GeoJSON (evidence: `src/geosplit/cli.py`)
- Command interface → Split planning: plans splits (evidence: `src/geosplit/cli.py`)
- Command interface → Format conversion: converts formats (evidence: `src/geosplit/cli.py`)
- Command interface → GeoPackage splitting: splits layers (evidence: `src/geosplit/cli.py`)
- Public API → Streaming and splitting: exports split API (evidence: `src/geosplit/__init__.py`)
- Public API → GeoJSON validation: exports validation (evidence: `src/geosplit/__init__.py`)
- GeoJSON validation → Streaming and splitting: reads features (evidence: `src/geosplit/validation.py`)
- Streaming and splitting → Batch iteration: yields batches (evidence: `README.md`)
- Streaming and splitting → Split planning: builds plans (evidence: `README.md`)
- Split planning → GeoJSON chunks: plans chunks (evidence: `README.md`)
- Streaming and splitting → Output transactions: stages outputs (evidence: `src/geosplit/core.py`)
- Output transactions → Output files: commits files
- Format conversion → GeoPandas: reads and writes (evidence: `src/geosplit/convert.py`)
- GeoPackage splitting → GeoPandas: reads layers (evidence: `src/geosplit/convert.py`)
- GeoPackage splitting → Output transactions: commits chunks (evidence: `src/geosplit/convert.py`)
- Format conversion → Output files: writes converted file (evidence: `src/geosplit/convert.py`)
- GeoPackage splitting → Output files: writes layer chunks (evidence: `src/geosplit/convert.py`)
