# lionsoul2014/ip2region architecture

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

## Overview

ip2region combines an offline IPv4/IPv6 localization library with tools for managing its xdb data. The main user workflow is to submit an IP address to a language binding, search an xdb database, and receive region information. Separately, maker tools generate and maintain xdb from source IP data, including processing, editing, deduplication, and compression. The README documents broad language support; source excerpts are uneven, so some binding and maker relationships are shown only at the documented subsystem level.

Main entry points: [`binding`](https://github.com/lionsoul2014/ip2region/tree/master/binding) (Query bindings), [`binding/java/src/main/java/org/lionsoul/ip2region/service/Ip2Region.java`](https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/service/Ip2Region.java) (Java service), [`binding/golang/xdb/searcher.go`](https://github.com/lionsoul2014/ip2region/blob/master/binding/golang/xdb/searcher.go) (Go searcher), [`binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java`](https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java) (Java searcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["IP lookup"]
  node_api["Query bindings"]
  node_go_main["Go CLI<br/>[main.go]"]
  node_go_service["Go service"]
  node_java_service["Java service<br/>[Ip2Region.java]"]
  node_csharp_searcher["C&#35; searcher<br/>[Searcher.cs]"]
end

subgraph group_xdb["Query internals"]
  node_go_searcher["Go searcher<br/>[searcher.go]"]
  node_java_searcher["Java searcher<br/>[Searcher.java]"]
  node_cache_config["Cache configuration<br/>[Config.java]"]
  node_xdb_format[("xdb database")]
end

subgraph group_maker["Data management"]
  node_maker_cli["Maker commands<br/>[main.go]"]
  node_maker_edit["Edit and process"]
  node_maker_generate["xdb generation<br/>[maker.py]"]
end

subgraph group_sources["Language clients"]
  node_other_clients["Other bindings"]
end

node_caller(("Application"))
node_raw_data["Source IP data"]
node_region_result["Region result"]

node_caller -->|"submits IP"| node_api
node_api -.->|"uses binding"| node_go_main
node_go_main -->|"creates service"| node_go_service
node_go_service -->|"uses searcher"| node_go_searcher
node_api -.->|"uses binding"| node_java_service
node_java_service -->|"calls searcher"| node_java_searcher
node_java_service -->|"uses config"| node_cache_config
node_api -.->|"uses binding"| node_csharp_searcher
node_api -->|"offers clients"| node_other_clients
node_go_searcher -.->|"reads xdb"| node_xdb_format
node_java_searcher -->|"reads xdb"| node_xdb_format
node_csharp_searcher -.->|"reads xdb"| node_xdb_format
node_java_searcher -->|"returns region"| node_region_result
node_go_searcher -.->|"returns region"| node_region_result
node_raw_data -->|"provides input"| node_maker_cli
node_maker_cli -->|"dispatches commands"| node_maker_edit
node_maker_cli -->|"dispatches generation"| node_maker_generate
node_maker_generate -->|"generates xdb"| node_xdb_format
node_maker_edit -.->|"updates source"| node_raw_data

click node_api "https://github.com/lionsoul2014/ip2region/tree/master/binding"
click node_go_main "https://github.com/lionsoul2014/ip2region/blob/master/binding/golang/main.go"
click node_go_service "https://github.com/lionsoul2014/ip2region/tree/master/binding/golang/service"
click node_java_service "https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/service/Ip2Region.java"
click node_csharp_searcher "https://github.com/lionsoul2014/ip2region/blob/master/binding/csharp/IP2Region.Net/XDB/Searcher.cs"
click node_go_searcher "https://github.com/lionsoul2014/ip2region/blob/master/binding/golang/xdb/searcher.go"
click node_java_searcher "https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java"
click node_cache_config "https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/service/Config.java"
click node_other_clients "https://github.com/lionsoul2014/ip2region/tree/master/binding"
click node_maker_cli "https://github.com/lionsoul2014/ip2region/blob/master/maker/golang/main.go"
click node_maker_edit "https://github.com/lionsoul2014/ip2region/tree/master/maker/golang/cmd"
click node_maker_generate "https://github.com/lionsoul2014/ip2region/blob/master/maker/python/xdb/maker.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_api,node_go_main,node_go_service,node_java_service,node_csharp_searcher toneBlue
class node_go_searcher,node_java_searcher,node_cache_config,node_xdb_format toneAmber
class node_maker_cli,node_maker_edit,node_maker_generate toneMint
class node_other_clients toneRose
class node_caller,node_raw_data,node_region_result toneIndigo
```

## Components

### IP lookup

- [Query bindings](https://github.com/lionsoul2014/ip2region/tree/master/binding): `binding`
- [Go CLI](https://github.com/lionsoul2014/ip2region/blob/master/binding/golang/main.go): `binding/golang/main.go`
- [Go service](https://github.com/lionsoul2014/ip2region/tree/master/binding/golang/service): `binding/golang/service`
- [Java service](https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/service/Ip2Region.java): `binding/java/src/main/java/org/lionsoul/ip2region/service/Ip2Region.java`
- [C# searcher](https://github.com/lionsoul2014/ip2region/blob/master/binding/csharp/IP2Region.Net/XDB/Searcher.cs): `binding/csharp/IP2Region.Net/XDB/Searcher.cs`

### Query internals

- [Go searcher](https://github.com/lionsoul2014/ip2region/blob/master/binding/golang/xdb/searcher.go): `binding/golang/xdb/searcher.go`
- [Java searcher](https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java): `binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java`
- [Cache configuration](https://github.com/lionsoul2014/ip2region/blob/master/binding/java/src/main/java/org/lionsoul/ip2region/service/Config.java): `binding/java/src/main/java/org/lionsoul/ip2region/service/Config.java`
- **xdb database**

### Data management

- [Maker commands](https://github.com/lionsoul2014/ip2region/blob/master/maker/golang/main.go): `maker/golang/main.go`
- [Edit and process](https://github.com/lionsoul2014/ip2region/tree/master/maker/golang/cmd): `maker/golang/cmd`
- [xdb generation](https://github.com/lionsoul2014/ip2region/blob/master/maker/python/xdb/maker.py): `maker/python/xdb/maker.py`

### Language clients

- [Other bindings](https://github.com/lionsoul2014/ip2region/tree/master/binding): `binding`

### Other components

- **Application**
- **Source IP data**
- **Region result**

## Connections

- Application → Query bindings: submits IP (evidence: `README.md`)
- Query bindings → Go CLI: uses binding (evidence: `binding/golang/main.go`)
- Go CLI → Go service: creates service (evidence: `binding/golang/main.go`)
- Go service → Go searcher: uses searcher (evidence: `binding/golang/service/searcher_pool.go`)
- Query bindings → Java service: uses binding (evidence: `binding/java/src/main/java/org/lionsoul/ip2region/SearcherTest.java`)
- Java service → Java searcher: calls searcher (evidence: `binding/java/src/main/java/org/lionsoul/ip2region/service/Ip2Region.java`)
- Java service → Cache configuration: uses config (evidence: `binding/java/src/main/java/org/lionsoul/ip2region/service/Ip2Region.java`)
- Query bindings → C# searcher: uses binding (evidence: `binding/csharp/IP2Region.Net/Extensions/ServiceCollectionExtensions.cs`)
- Query bindings → Other bindings: offers clients (evidence: `README.md`)
- Go searcher → xdb database: reads xdb
- Java searcher → xdb database: reads xdb (evidence: `binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java`)
- C# searcher → xdb database: reads xdb
- Java searcher → Region result: returns region (evidence: `binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java`)
- Go searcher → Region result: returns region
- Source IP data → Maker commands: provides input (evidence: `README.md`)
- Maker commands → Edit and process: dispatches commands (evidence: `maker/golang/main.go`)
- Maker commands → xdb generation: dispatches generation (evidence: `maker/golang/main.go`)
- xdb generation → xdb database: generates xdb (evidence: `README.md`)
- Edit and process → Source IP data: updates source
