# kotajakarta/wilindo architecture

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

- Interactive diagram: https://gitdiagram.com/kotajakarta/wilindo
- Repository: https://github.com/kotajakarta/wilindo

## Overview

Wilindo is a full-stack Indonesian administrative-region registry: public hierarchical lookup and search, address selection, and API-key-protected CRUD. The main flow runs from a browser or API consumer through Express routes and service logic to MariaDB. A separate BPS extraction-and-sync branch refreshes registry data. Several client pages and API wrappers are represented from the README and tree; their internal wiring is not fully evidenced by sampled source.

Main entry points: [`server/src/wilayah.routes.ts`](https://github.com/kotajakarta/wilindo/blob/master/server/src/wilayah.routes.ts) (Region routes), [`client/src/pages/AddressPage.tsx`](https://github.com/kotajakarta/wilindo/blob/master/client/src/pages/AddressPage.tsx) (Address page), [`server/src/app.ts`](https://github.com/kotajakarta/wilindo/blob/master/server/src/app.ts) (Express application), [`client/src/App.tsx`](https://github.com/kotajakarta/wilindo/blob/master/client/src/App.tsx) (Client app router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Client app router<br/>[App.tsx]"]
  node_address["Address page<br/>[AddressPage.tsx]"]
  node_address_widgets["Address selectors"]
  node_selection["Hierarchy selection"]
  node_admin_page["Admin page<br/>[AdminPage.tsx]"]
  node_admin_manager["Admin manager"]
  node_admin_rows["Admin level rows<br/>[AdminLevelRow.tsx]"]
  node_api_docs["API guide<br/>[ApiDocsPage.tsx]"]
  node_read_api["Read API client<br/>[wilayah.ts]"]
  node_admin_api["Admin API client<br/>[wilayahAdmin.ts]"]
end

subgraph group_api["HTTP API"]
  node_server["Express application<br/>[app.ts]"]
  node_routes["Region routes<br/>[wilayah.routes.ts]"]
  node_auth["API-key check<br/>[auth.ts]"]
end

subgraph group_registry["Region registry"]
  node_service["Region service<br/>[wilayah.service.ts]"]
  node_db_pool["DB connection<br/>[db.ts]"]
  node_mariadb[("MariaDB registry")]
end

subgraph group_refresh["BPS data refresh"]
  node_extractor["BPS extractor<br/>[bps.js]"]
  node_bps_api["BPS source"]
  node_bps_files["Extracted region data"]
  node_sync["Registry sync<br/>[sync-bps.js]"]
end

node_visitor(("Address user"))
node_api_consumer(("API consumer"))

node_visitor -->|"uses"| node_address
node_visitor -->|"manages"| node_admin_page
node_api_consumer -->|"requests API"| node_server
node_app -->|"routes to"| node_address
node_app -->|"routes to"| node_admin_page
node_app -->|"routes to"| node_api_docs
node_address -->|"renders"| node_address_widgets
node_address -->|"tracks levels"| node_selection
node_address_widgets -->|"loads regions"| node_read_api
node_admin_page -->|"renders"| node_admin_manager
node_admin_manager -->|"renders levels"| node_admin_rows
node_admin_rows -->|"loads regions"| node_read_api
node_admin_rows -->|"mutates regions"| node_admin_api
node_read_api -->|"fetches"| node_server
node_admin_api -->|"fetches"| node_server
node_server -->|"mounts API"| node_routes
node_routes -->|"checks mutations"| node_auth
node_routes -->|"calls"| node_service
node_routes -->|"passes pool"| node_db_pool
node_service -->|"queries"| node_mariadb
node_db_pool -->|"connects"| node_mariadb
node_extractor -->|"fetches levels"| node_bps_api
node_extractor -->|"writes hierarchy"| node_bps_files
node_sync -->|"reads data"| node_bps_files
node_sync -->|"compares and updates"| node_mariadb

click node_app "https://github.com/kotajakarta/wilindo/blob/master/client/src/App.tsx"
click node_address "https://github.com/kotajakarta/wilindo/blob/master/client/src/pages/AddressPage.tsx"
click node_address_widgets "https://github.com/kotajakarta/wilindo/tree/master/client/src/components"
click node_selection "https://github.com/kotajakarta/wilindo/blob/master/client/src/hooks/useWilayahSelection.ts"
click node_admin_page "https://github.com/kotajakarta/wilindo/blob/master/client/src/pages/AdminPage.tsx"
click node_admin_manager "https://github.com/kotajakarta/wilindo/blob/master/client/src/components/WilayahAdminManager.tsx"
click node_admin_rows "https://github.com/kotajakarta/wilindo/blob/master/client/src/components/AdminLevelRow.tsx"
click node_api_docs "https://github.com/kotajakarta/wilindo/blob/master/client/src/pages/ApiDocsPage.tsx"
click node_read_api "https://github.com/kotajakarta/wilindo/blob/master/client/src/api/wilayah.ts"
click node_admin_api "https://github.com/kotajakarta/wilindo/blob/master/client/src/api/wilayahAdmin.ts"
click node_server "https://github.com/kotajakarta/wilindo/blob/master/server/src/app.ts"
click node_routes "https://github.com/kotajakarta/wilindo/blob/master/server/src/wilayah.routes.ts"
click node_auth "https://github.com/kotajakarta/wilindo/blob/master/server/src/auth.ts"
click node_service "https://github.com/kotajakarta/wilindo/blob/master/server/src/wilayah.service.ts"
click node_db_pool "https://github.com/kotajakarta/wilindo/blob/master/server/src/db.ts"
click node_extractor "https://github.com/kotajakarta/wilindo/blob/master/bps/bps.js"
click node_bps_files "https://github.com/kotajakarta/wilindo/tree/master/bps"
click node_sync "https://github.com/kotajakarta/wilindo/blob/master/server/sync-bps.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_app,node_address,node_address_widgets,node_selection,node_admin_page,node_admin_manager,node_admin_rows,node_api_docs,node_read_api,node_admin_api,node_visitor toneBlue
class node_server,node_routes,node_auth toneAmber
class node_service,node_db_pool,node_mariadb,node_api_consumer toneMint
class node_extractor,node_bps_api,node_bps_files,node_sync toneRose
```

## Components

### Web client

- [Client app router](https://github.com/kotajakarta/wilindo/blob/master/client/src/App.tsx): `client/src/App.tsx`
- [Address page](https://github.com/kotajakarta/wilindo/blob/master/client/src/pages/AddressPage.tsx): `client/src/pages/AddressPage.tsx`
- [Address selectors](https://github.com/kotajakarta/wilindo/tree/master/client/src/components): `client/src/components`
- [Hierarchy selection](https://github.com/kotajakarta/wilindo/blob/master/client/src/hooks/useWilayahSelection.ts): `client/src/hooks/useWilayahSelection.ts`
- [Admin page](https://github.com/kotajakarta/wilindo/blob/master/client/src/pages/AdminPage.tsx): `client/src/pages/AdminPage.tsx`
- [Admin manager](https://github.com/kotajakarta/wilindo/blob/master/client/src/components/WilayahAdminManager.tsx): `client/src/components/WilayahAdminManager.tsx`
- [Admin level rows](https://github.com/kotajakarta/wilindo/blob/master/client/src/components/AdminLevelRow.tsx): `client/src/components/AdminLevelRow.tsx`
- [API guide](https://github.com/kotajakarta/wilindo/blob/master/client/src/pages/ApiDocsPage.tsx): `client/src/pages/ApiDocsPage.tsx`
- [Read API client](https://github.com/kotajakarta/wilindo/blob/master/client/src/api/wilayah.ts): `client/src/api/wilayah.ts`
- [Admin API client](https://github.com/kotajakarta/wilindo/blob/master/client/src/api/wilayahAdmin.ts): `client/src/api/wilayahAdmin.ts`

### HTTP API

- [Express application](https://github.com/kotajakarta/wilindo/blob/master/server/src/app.ts): `server/src/app.ts`
- [Region routes](https://github.com/kotajakarta/wilindo/blob/master/server/src/wilayah.routes.ts): `server/src/wilayah.routes.ts`
- [API-key check](https://github.com/kotajakarta/wilindo/blob/master/server/src/auth.ts): `server/src/auth.ts`

### Region registry

- [Region service](https://github.com/kotajakarta/wilindo/blob/master/server/src/wilayah.service.ts): `server/src/wilayah.service.ts`
- [DB connection](https://github.com/kotajakarta/wilindo/blob/master/server/src/db.ts): `server/src/db.ts`
- **MariaDB registry**

### BPS data refresh

- [BPS extractor](https://github.com/kotajakarta/wilindo/blob/master/bps/bps.js): `bps/bps.js`
- **BPS source**
- [Extracted region data](https://github.com/kotajakarta/wilindo/tree/master/bps): `bps`
- [Registry sync](https://github.com/kotajakarta/wilindo/blob/master/server/sync-bps.js): `server/sync-bps.js`

### Other components

- **Address user**
- **API consumer**

## Connections

- Address user → Address page: uses
- Address user → Admin page: manages
- API consumer → Express application: requests API
- Client app router → Address page: routes to
- Client app router → Admin page: routes to
- Client app router → API guide: routes to
- Address page → Address selectors: renders
- Address page → Hierarchy selection: tracks levels
- Address selectors → Read API client: loads regions
- Admin page → Admin manager: renders
- Admin manager → Admin level rows: renders levels
- Admin level rows → Read API client: loads regions
- Admin level rows → Admin API client: mutates regions
- Read API client → Express application: fetches
- Admin API client → Express application: fetches
- Express application → Region routes: mounts API
- Region routes → API-key check: checks mutations
- Region routes → Region service: calls
- Region routes → DB connection: passes pool
- Region service → MariaDB registry: queries
- DB connection → MariaDB registry: connects
- BPS extractor → BPS source: fetches levels
- BPS extractor → Extracted region data: writes hierarchy
- Registry sync → Extracted region data: reads data
- Registry sync → MariaDB registry: compares and updates