# turtiesocks/koji architecture

> Architecture diagram of the GitHub repository turtiesocks/koji, 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/turtiesocks/koji
- Repository: https://github.com/turtiesocks/koji

## Overview

Kōji is a geospatial mapping and automation application: users create or import geofences, configure clustering and routing, inspect results on a map, and optionally save or export them. It also provides an admin panel and public API. The graph combines README capabilities with the supplied excerpts and repository paths; backend handler and persistence wiring is not fully sampled, so those internal links are limited to the evident API, algorithm, and model boundaries.

Main entry points: [`server/api/src/lib.rs`](https://github.com/turtiesocks/koji/blob/main/server/api/src/lib.rs) (HTTP API), [`server/api/src/public/v1/mod.rs`](https://github.com/turtiesocks/koji/blob/main/server/api/src/public/v1/mod.rs) (Public endpoints), [`client/src/services/fetches.ts`](https://github.com/turtiesocks/koji/blob/main/client/src/services/fetches.ts) (API client), [`client/src/pages/map/index.tsx`](https://github.com/turtiesocks/koji/blob/main/client/src/pages/map/index.tsx) (Interactive map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Mapping client"]
  node_map_ui["Interactive map<br/>[index.tsx]"]
  node_drawing["Geofence drawing<br/>[Drawing.tsx]"]
  node_shape_state["Geometry state<br/>[useShapes.ts]"]
  node_routing_ui["Routing controls<br/>[Routing.tsx]"]
  node_import_export["Import and export<br/>[useImportExport.ts]"]
  node_client_api["API client<br/>[fetches.ts]"]
end

subgraph group_backend["API and algorithms"]
  node_server["Server startup<br/>[main.rs]"]
  node_api["HTTP API<br/>[lib.rs]"]
  node_public_api["Public endpoints<br/>[mod.rs]"]
  node_private_api["Admin endpoints<br/>[mod.rs]"]
  node_algorithms["Geospatial algorithms<br/>[lib.rs]"]
  node_routing_alg["Route algorithms<br/>[mod.rs]"]
  node_clustering_alg["Clustering algorithms<br/>[mod.rs]"]
end

subgraph group_management["Management and data"]
  node_admin_ui["Admin panel<br/>[index.tsx]"]
  node_admin_resources["Geofence and route management<br/>[GeofenceList.tsx]"]
  node_models["Domain models<br/>[mod.rs]"]
  node_db[("Application database<br/>[prelude.rs]")]
end

subgraph group_integrations["Integrations"]
  node_nominatim_client["Nominatim client<br/>[client.rs]"]
end

node_map_user(("Map user"))
node_external_client(("API integrator"))
node_nominatim(("Nominatim service"))
node_scanner[("Scanner database")]

node_map_user -->|"uses"| node_map_ui
node_map_ui -->|"opens drawing"| node_drawing
node_drawing -->|"edits geometry"| node_shape_state
node_map_ui -->|"renders geometry"| node_shape_state
node_map_user -->|"configures"| node_routing_ui
node_routing_ui -->|"requests routing"| node_client_api
node_import_export -->|"requests conversion"| node_client_api
node_client_api -->|"sends requests"| node_api
node_server -->|"starts"| node_api
node_external_client -->|"integrates via"| node_public_api
node_api -->|"serves"| node_public_api
node_api -->|"serves"| node_private_api
node_public_api -->|"invokes calculations"| node_algorithms
node_algorithms -->|"dispatches clustering"| node_clustering_alg
node_algorithms -->|"dispatches routing"| node_routing_alg
node_admin_ui -->|"manages resources"| node_admin_resources
node_admin_ui -->|"requests data"| node_client_api
node_private_api -->|"uses models"| node_models
node_public_api -->|"uses models"| node_models
node_models -->|"accesses persistence"| node_db
node_nominatim_client -.->|"queries"| node_nominatim
node_import_export -.->|"can save export"| node_scanner

click node_map_ui "https://github.com/turtiesocks/koji/blob/main/client/src/pages/map/index.tsx"
click node_drawing "https://github.com/turtiesocks/koji/blob/main/client/src/components/drawer/Drawing.tsx"
click node_shape_state "https://github.com/turtiesocks/koji/blob/main/client/src/hooks/useShapes.ts"
click node_routing_ui "https://github.com/turtiesocks/koji/blob/main/client/src/components/drawer/Routing.tsx"
click node_import_export "https://github.com/turtiesocks/koji/blob/main/client/src/hooks/useImportExport.ts"
click node_client_api "https://github.com/turtiesocks/koji/blob/main/client/src/services/fetches.ts"
click node_server "https://github.com/turtiesocks/koji/blob/main/server/src/main.rs"
click node_api "https://github.com/turtiesocks/koji/blob/main/server/api/src/lib.rs"
click node_public_api "https://github.com/turtiesocks/koji/blob/main/server/api/src/public/v1/mod.rs"
click node_private_api "https://github.com/turtiesocks/koji/blob/main/server/api/src/private/mod.rs"
click node_algorithms "https://github.com/turtiesocks/koji/blob/main/server/algorithms/src/lib.rs"
click node_routing_alg "https://github.com/turtiesocks/koji/blob/main/server/algorithms/src/routing/mod.rs"
click node_clustering_alg "https://github.com/turtiesocks/koji/blob/main/server/algorithms/src/clustering/mod.rs"
click node_admin_ui "https://github.com/turtiesocks/koji/blob/main/client/src/pages/admin/index.tsx"
click node_admin_resources "https://github.com/turtiesocks/koji/blob/main/client/src/pages/admin/geofence/GeofenceList.tsx"
click node_models "https://github.com/turtiesocks/koji/blob/main/server/model/src/db/mod.rs"
click node_db "https://github.com/turtiesocks/koji/blob/main/server/model/src/db/prelude.rs"
click node_nominatim_client "https://github.com/turtiesocks/koji/blob/main/server/nominatim/src/client.rs"

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_ui,node_drawing,node_shape_state,node_routing_ui,node_import_export,node_client_api,node_map_user toneBlue
class node_server,node_api,node_public_api,node_private_api,node_algorithms,node_routing_alg,node_clustering_alg,node_scanner toneAmber
class node_admin_ui,node_admin_resources,node_models,node_db,node_external_client toneMint
class node_nominatim_client toneRose
class node_nominatim toneIndigo
```

## Components

### Mapping client

- [Interactive map](https://github.com/turtiesocks/koji/blob/main/client/src/pages/map/index.tsx): `client/src/pages/map/index.tsx`
- [Geofence drawing](https://github.com/turtiesocks/koji/blob/main/client/src/components/drawer/Drawing.tsx): `client/src/components/drawer/Drawing.tsx`
- [Geometry state](https://github.com/turtiesocks/koji/blob/main/client/src/hooks/useShapes.ts): `client/src/hooks/useShapes.ts`
- [Routing controls](https://github.com/turtiesocks/koji/blob/main/client/src/components/drawer/Routing.tsx): `client/src/components/drawer/Routing.tsx`
- [Import and export](https://github.com/turtiesocks/koji/blob/main/client/src/hooks/useImportExport.ts): `client/src/hooks/useImportExport.ts`
- [API client](https://github.com/turtiesocks/koji/blob/main/client/src/services/fetches.ts): `client/src/services/fetches.ts`

### API and algorithms

- [Server startup](https://github.com/turtiesocks/koji/blob/main/server/src/main.rs): `server/src/main.rs`
- [HTTP API](https://github.com/turtiesocks/koji/blob/main/server/api/src/lib.rs): `server/api/src/lib.rs`
- [Public endpoints](https://github.com/turtiesocks/koji/blob/main/server/api/src/public/v1/mod.rs): `server/api/src/public/v1/mod.rs`
- [Admin endpoints](https://github.com/turtiesocks/koji/blob/main/server/api/src/private/mod.rs): `server/api/src/private/mod.rs`
- [Geospatial algorithms](https://github.com/turtiesocks/koji/blob/main/server/algorithms/src/lib.rs): `server/algorithms/src/lib.rs`
- [Route algorithms](https://github.com/turtiesocks/koji/blob/main/server/algorithms/src/routing/mod.rs): `server/algorithms/src/routing/mod.rs`
- [Clustering algorithms](https://github.com/turtiesocks/koji/blob/main/server/algorithms/src/clustering/mod.rs): `server/algorithms/src/clustering/mod.rs`

### Management and data

- [Admin panel](https://github.com/turtiesocks/koji/blob/main/client/src/pages/admin/index.tsx): `client/src/pages/admin/index.tsx`
- [Geofence and route management](https://github.com/turtiesocks/koji/blob/main/client/src/pages/admin/geofence/GeofenceList.tsx): `client/src/pages/admin/geofence/GeofenceList.tsx`
- [Domain models](https://github.com/turtiesocks/koji/blob/main/server/model/src/db/mod.rs): `server/model/src/db/mod.rs`
- [Application database](https://github.com/turtiesocks/koji/blob/main/server/model/src/db/prelude.rs): `server/model/src/db/prelude.rs`

### Integrations

- [Nominatim client](https://github.com/turtiesocks/koji/blob/main/server/nominatim/src/client.rs): `server/nominatim/src/client.rs`

### Other components

- **Map user**
- **API integrator**
- **Nominatim service**
- **Scanner database**

## Connections

- Map user → Interactive map: uses
- Interactive map → Geofence drawing: opens drawing
- Geofence drawing → Geometry state: edits geometry
- Interactive map → Geometry state: renders geometry
- Map user → Routing controls: configures
- Routing controls → API client: requests routing
- Import and export → API client: requests conversion
- API client → HTTP API: sends requests
- Server startup → HTTP API: starts
- API integrator → Public endpoints: integrates via
- HTTP API → Public endpoints: serves
- HTTP API → Admin endpoints: serves
- Public endpoints → Geospatial algorithms: invokes calculations
- Geospatial algorithms → Clustering algorithms: dispatches clustering
- Geospatial algorithms → Route algorithms: dispatches routing
- Admin panel → Geofence and route management: manages resources
- Admin panel → API client: requests data
- Admin endpoints → Domain models: uses models
- Public endpoints → Domain models: uses models
- Domain models → Application database: accesses persistence
- Nominatim client → Nominatim service: queries
- Import and export → Scanner database: can save export