# kincaidyang/whois architecture

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

- Interactive diagram: https://gitdiagram.com/kincaidyang/whois
- Repository: https://github.com/kincaidyang/whois

## Overview

a. Client Interface: Represent browsers or API clients sending GET requests on port 8043.
b. HTTP API Server: This is the entry point (main.go) that listens for incoming HTTP requests.
c. Request Routing & Handler Layer: Within your HTTP server, route requests into the proper logic paths based on whether the query is for a domain, IP, or ASN.
d. Configuration Management: A component (using config.yaml and the config package) that holds and supplies settings—like Redis connection information, rate limits, proxy, and port settings.
e. Query Processing Modules:
- WhoIs/RDAP Lookup Component – with two primary sub-components:
- rdap_tools: Manages RDAP queries and parsing (e.g., rdap_query.go, rdap_parse.go, and related structs organized by type).
- whois_tools: Handles traditional WHOIS query parsing and logic for cases where RDAP isn’t available.
- handle_resources: Provides resource-specific handling and normalization for the data (with separate files for ASN, domain, and IP).
- Server Lists: A module supplying lists of WHOIS and RDAP servers (server_lists) that inform which external endpoint to query.
f. Caching Layer: Integration with Redis (configured via YAML and integrated using the go-redis client). This component caches responses and enforces the rate limit for outbound queries to WHOIS servers.
g. External Dependencies: Mark external WHOIS/RDAP servers, Redis server, and optionally external proxy servers (as provided by configuration).

##### Relationships and data flow
- A client sends an HTTP GET request to the API server.
- The HTTP server, after reading the configuration (e.g., port, rate limits), routes the request to the appropriate query handler.
- The handler decides whether to process the query via RDAP (rdap_tools) or using traditional WHOIS (whois_tools) – possibly after weighing cache availability from Redis.
- Before sending an outbound query, consult the cache layer (Redis) to see if the information has been stored recently.
- If not in cache, the system uses the server lists to pick the right external WHOIS/RDAP servers and queries them.
- The raw response is then processed by the resource handling modules (handle_resources).
- The final JSON result is then provided back to the client.

##### Architectural patterns and details to highlight
- Separation of concerns: The code divides responsibilities by package (configuration, query routing, protocol-specific processing, caching, and server list management).
- Modularity: Each component (rdap_tools, whois_tools, handle_resources) focuses on a specific part of processing the query.
- External integration: Clearly mark the external Redis caching service, WHOIS/RDAP endpoints, and optional proxy usage.
- Rate limiting: Although enforced on the outgoing flows, you also provide a note in configuration indicating that an external tool (e.g., Nginx) should also rate limit incoming requests.
- Technology stack: The project is written in Go, and it leverages both standard libraries (net/http, context, etc.) and key external libraries (go-redis, YAML parsing via gopkg.in/yaml.v2).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    A["Client (Browser/API Client)"]:::client
    B["API Server (main.go)"]:::server
    C["Configuration Manager (config)"]:::config
    D["Cache Layer (Redis)"]:::cache
    I["External WHOIS/RDAP Servers"]:::external

    %% Query Processing subgraph
    subgraph "Query Processing Modules"
        E["RDAP Processing (rdap_tools)"]:::processing
        F["WHOIS Processing (whois_tools)"]:::processing
        G["Resource Handler (handle_resources)"]:::processing
    end

    %% External supportive module
    H["Server Lists (server_lists)"]:::processing

    %% Data Flow
    A -->|"GET"| B
    B -->|"LoadConfig"| C
    B -->|"CheckCache"| D
    D -- "Cache hit" --> B
    D -- "Cache miss" --> B

    %% Request Routing & Handler Layer within API Server directs queries
    B -->|"RouteRDAP"| E
    B -->|"RouteWHOIS"| F

    %% Both processing modules query server lists before external call
    E -->|"Lookup"| H
    F -->|"Lookup"| H

    %% Server lists directs to external WHOIS/RDAP servers
    H -->|"SelectServer"| I

    %% External servers return response to processing modules
    I -->|"Response"| E
    I -->|"Response"| F

    %% Processed data is normalized by Resource Handler
    E -->|"ProcessResult"| G
    F -->|"ProcessResult"| G

    %% Final processed result returns to API Server and then to Client
    G -->|"ReturnResult"| B
    B -->|"Send JSON"| A

    %% Annotations for external rate limiting (e.g., via Nginx) is configured in config
    B ---|"Note:ExternalRateLimiter"| C

    %% Click Events
    click B "https://github.com/kincaidyang/whois/blob/main/main.go"
    click C "https://github.com/kincaidyang/whois/blob/main/config.yaml"
    click C "https://github.com/kincaidyang/whois/blob/main/config/config.go"
    click E "https://github.com/kincaidyang/whois/tree/main/rdap_tools"
    click F "https://github.com/kincaidyang/whois/tree/main/whois_tools"
    click G "https://github.com/kincaidyang/whois/tree/main/handle_resources"
    click H "https://github.com/kincaidyang/whois/tree/main/server_lists"

    %% Styles
    classDef client fill:#bbdefb,stroke:#333,stroke-width:2px;
    classDef server fill:#c8e6c9,stroke:#333,stroke-width:2px;
    classDef config fill:#ffeb3b,stroke:#333,stroke-width:2px;
    classDef cache fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef processing fill:#ffe0b2,stroke:#333,stroke-width:2px;
    classDef external fill:#ef9a9a,stroke:#333,stroke-width:2px;
```
