# zengzhan/qqzeng-ip architecture

> Architecture diagram of the GitHub repository zengzhan/qqzeng-ip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zengzhan/qqzeng-ip
- Repository: https://github.com/zengzhan/qqzeng-ip

## Overview

##### Major Components
- IP Database Storage & Formats:
– A central data repository (DAT, TXT, .db files) that contains the IP data in highly optimized binary and text formats.
– Include details on the CIDR vs. IP Range representations as described (grand metadata about regions, carriers, etc.).
- Query / Lookup Engine:
– The core logic that processes queries. This is represented via various language-specific implementations (look for directories like “qqzeng-ip-c”, “qqzeng-ip-netcore”, “qqzeng-ip-go”, “qqzeng-ip-java”, “qqzeng-ip-python”, etc.)
- Phone Number Lookup Component:
– A similar architectural segment for phone number queries is provided across different versions (as seen in “qqzeng-phone-” directories). This component handles phone attribution using similar principles.
- Supporting Utilities & Test Data:
– Demo data files (e.g., qqzeng-ip-range.txt), SQL scripts for various databases (MSSQL, MySQL, PgSQL).
– These help set up, test, and integrate the system into different environments.
- External Integrations:
– Although not a full-stack web app, the README mentions use-cases (traffic management, DNS, ad targeting, etc.), so it’s useful to represent that clients (web servers, mobile apps, or external services) use these libraries for real-time lookups.
– API clients or service wrappers can be depicted as consumers of the lookup libraries.

##### Relationships and Interactions
- Data Flow:
– At the center, show the IP (and phone) data repository.
– Optionally, show “SQL Import Scripts” feeding data into various RDBMS or Redis if used downstream.
- Separation between IP and phone mechanisms:
– Use separate modules (or distinct shaded areas) for “IP Lookup” and “Phone Lookup,” since they share similar design principles but serve different query types.
- Role of “High-Performance Query Engine”:
– Label that each implementation is designed for near O(1) time complexity lookups and high concurrency with minimal memory usage.

##### Architectural Patterns and Design Principles
- Multi-Language / Polyglot Toolkit:
– The project is an extensible toolkit supporting many runtime environments. Highlight each language’s library as an independent component that implements the same core lookup algorithm.
- Data-Centric Performance:
– Emphasize the importance of binary DAT format and CIDR representations. Indicate that computations are optimized for high throughput (e.g., “解析速度: 超5,000万次/秒”).
- Modular Design:
– Separate core lookup logic from auxiliary data import/management scripts (such as SQL scripts in directories like “mssql”, “mysql”, “pgsql”).
- Versioning Support:

##### Relevant Technologies/Frameworks
- Languages: Each library component is implemented in languages like C/C++, Java, C#, Python, Go, Rust, NodeJs, PHP.
- Database Scripts: SQL files (MSSQL, MySQL, PgSQL) indicate integration with standard relational databases.
- Build Tools: For example, Cargo for Rust projects and go.mod for Go modules.
- File Formats: DAT for binary file performance and TXT for flexibility.

##### Detail and Clarity
- Avoid unnecessary abstraction; instead, separate the project into as many components as possible to match the granularity seen in the file tree.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Central Data
    subgraph "Central Data"
        IPDB["IP Database Storage (CIDR DAT Format)"]:::core
    end

    %% IP Lookup Libraries
    subgraph "IP Lookup Libraries"
        IP_C["IP Lookup - C"]:::lookup
        IP_DotNet["IP Lookup - .NET"]:::lookup
        IP_Go["IP Lookup - Go"]:::lookup
        IP_Java["IP Lookup - Java"]:::lookup
        IP_Node["IP Lookup - NodeJs"]:::lookup
        IP_PHP["IP Lookup - PHP"]:::lookup
        IP_Python["IP Lookup - Python"]:::lookup
        IP_Rust["IP Lookup - Rust"]:::lookup
    end

    %% Phone Lookup Libraries
    subgraph "Phone Lookup Libraries"
        Phone_CPP["Phone Lookup - C++"]:::lookup_phone
        Phone_DotNet["Phone Lookup - .NET"]:::lookup_phone
        Phone_Java["Phone Lookup - Java"]:::lookup_phone
        Phone_Node["Phone Lookup - NodeJs"]:::lookup_phone
        Phone_PHP["Phone Lookup - PHP"]:::lookup_phone
        Phone_Python["Phone Lookup - Python"]:::lookup_phone
        Phone_Go["Phone Lookup - Go"]:::lookup_phone
        Phone_Rust["Phone Lookup - Rust"]:::lookup_phone
    end

    %% Utilities & Integration
    subgraph "Utilities & Integration"
        SQL["SQL Scripts / Data Import Modules"]:::aux
        Demo["Demo Data Files"]:::aux
        Redis_IP["Redis IP Lookup"]:::aux
        Redis_Phone["Redis Phone Lookup"]:::aux
        External["External Clients / Applications"]:::external
    end

    %% Connections from IP Database to IP Lookup Libraries
    IPDB -->|"reads data"| IP_C
    IPDB -->|"reads data"| IP_DotNet
    IPDB -->|"reads data"| IP_Go
    IPDB -->|"reads data"| IP_Java
    IPDB -->|"reads data"| IP_Node
    IPDB -->|"reads data"| IP_PHP
    IPDB -->|"reads data"| IP_Python
    IPDB -->|"reads data"| IP_Rust

    %% External Clients consuming from both IP and Phone Lookup Libraries
    IP_C -->|"lookup"| External
    IP_DotNet -->|"lookup"| External
    IP_Go -->|"lookup"| External
    IP_Java -->|"lookup"| External
    IP_Node -->|"lookup"| External
    IP_PHP -->|"lookup"| External
    IP_Python -->|"lookup"| External
    IP_Rust -->|"lookup"| External

    Phone_CPP -->|"lookup"| External
    Phone_DotNet -->|"lookup"| External
    Phone_Java -->|"lookup"| External
    Phone_Node -->|"lookup"| External
    Phone_PHP -->|"lookup"| External
    Phone_Python -->|"lookup"| External
    Phone_Go -->|"lookup"| External
    Phone_Rust -->|"lookup"| External

    %% Utilities feeding data or integrating with modules
    Demo -->|"provides sample"| IPDB
    SQL -->|"imports data"| IPDB
    Redis_IP -->|"caches"| External
    Redis_Phone -->|"caches"| External

    %% Click Events for IP Database Storage & Formats
    click IPDB "https://github.com/zengzhan/qqzeng-ip/blob/master/demo-data/qqzeng-ip-utf8.dat"

    %% Click Events for Query / Lookup Engine – IP Lookup Libraries
    click IP_C "https://github.com/zengzhan/qqzeng-ip/tree/master/3.0/qqzeng-ip-c"
    click IP_DotNet "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-ip-c#"
    click IP_Go "https://github.com/zengzhan/qqzeng-ip/tree/master/3.0/qqzeng-ip-go"
    click IP_Java "https://github.com/zengzhan/qqzeng-ip/tree/master/3.0/qqzeng-ip-java"
    click IP_Node "https://github.com/zengzhan/qqzeng-ip/tree/master/3.0/qqzeng-ip-nodejs"
    click IP_PHP "https://github.com/zengzhan/qqzeng-ip/tree/master/3.0/qqzeng-ip-php"
    click IP_Python "https://github.com/zengzhan/qqzeng-ip/tree/master/3.0/qqzeng-ip-python"
    click IP_Rust "https://github.com/zengzhan/qqzeng-ip/tree/master/3.0/qqzeng_ip_rust"

    %% Click Events for Phone Lookup Component – 3.0 Implementations
    click Phone_CPP "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/c++"
    click Phone_DotNet "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/dotnet"
    click Phone_Java "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/java"
    click Phone_Node "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/nodejs"
    click Phone_PHP "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/php"
    click Phone_Python "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/python"
    click Phone_Go "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/qqzeng_phone_go"
    click Phone_Rust "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-phone-3.0/qqzeng_phone_rust"

    %% Click Events for Supporting Utilities & Test Data
    click SQL "https://github.com/zengzhan/qqzeng-ip/blob/master/mssql/ip.sql"
    click Demo "https://github.com/zengzhan/qqzeng-ip/blob/master/demo-data/qqzeng-ip-range.txt"
    click Redis_IP "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-redis-ip"
    click Redis_Phone "https://github.com/zengzhan/qqzeng-ip/tree/master/qqzeng-redis-phone"

    %% Class Definitions for styling
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef lookup fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef lookup_phone fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef aux fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
