# viettools/checkdomain architecture

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

- Interactive diagram: https://gitdiagram.com/viettools/checkdomain
- Repository: https://github.com/viettools/checkdomain

## Overview

##### Project Type and Purpose
- This is a full-stack, containerized domain-checking web application (“Check Domain”).
- It exposes an HTTP endpoint (port 6996) with a small web frontend (static assets + Jinja2 templates) and a Python backend that retrieves WHOIS or RDAP data, parses it, applies reserved-domain filters, and returns results.

##### Top-Level File Structure & Architectural Clues
- Config_File/: External config generators (Nginx, domain checks)
- Dockerfile + docker-compose-*.yml: Containerization and IPv4/IPv6 networking
- main.py / checkdomain.py: Entry points to start the HTTP server or CLI tool
- parse_whois_socket.py & whois.py: Raw WHOIS socket communication
- webwhois/: RDAP lookups per TLD
- verified/: Registrar-specific WHOIS fallbacks
- static/ & templates/: Web UI assets (JS/CSS/fonts) and HTML templates
- data/ + reserved_domains/: Flat-file data stores and regex filters
- tests/: Unit tests for each ccTLD module

##### Key Components to Capture
a. Clients & Interfaces
- Web Browser (UI)
- Optional CLI consumer (checkdomain.py)
b. Web/Application Server
- HTTP Server (Flask or built-in Python HTTP + Jinja2 engine)
- Routes:
- “/” → index template + static assets
- “/api/check” → controller invoking lookup logic
c. Domain-Lookup Engine
- Controller module (main.py)
- WHOIS Socket Pipeline (parse_whois_socket.py → whois.py → verified/)
- RDAP HTTP Pipeline (webwhois/ per-TLD clients)
- Reserved-domain filter (reserved_domains/*.txt)
- Data file loaders (data/domains.query.csv + regex)
d. External Dependencies
- Port 43 WHOIS servers (TCP)
- RDAP servers (HTTPS)
- Docker network (IPv4 & IPv6 bridge)
e. Deployment & Configuration
- Docker container
- docker-compose network overlay
- Nginx configs (Config_File/Nginx) if fronting with a reverse proxy

- Browser → HTTP Server (HTTP GET/POST)
- HTTP Server → Template Engine & Static Assets
- HTTP Server → Lookup Engine (search request)
- Lookup Engine → WHOIS Socket & → RDAP Clients
- WHOIS/RDAP → External WHOIS/RDAP Servers
- Lookup Engine → Reserved-domain filter → Response assembly
- Response → HTTP Server → Browser
- Blue cluster: “Web Layer” (templates, static, main.py)
- Green cluster: “Lookup Services” (parse_whois_socket.py, whois.py, webwhois/, verified/)
- Yellow cluster: “Data Sources” (data/, reserved_domains/)
- Gray cluster: “Deployment” (Docker, docker-compose, Config_File)

##### Architectural Patterns
- Layered architecture: Presentation (web UI), Application (HTTP controllers), Domain-Lookup service, Infrastructure (socket/HTTP clients), Configuration/Deployment
- Single-process, event-driven or thread-based HTTP server
- Flat-file data store (no database)
- TLD-specific client plugins (webwhois/<tld>.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Web Layer"
    direction TB
    Browser["Web Browser"]:::external
    HTTPServer["HTTP Server\n(main.py)"]:::frontend
    TemplateEngine["Templates"]:::frontend
    StaticAssets["Static Assets"]:::frontend
    CLITool["CLI Tool\n(cctld.py)"]:::frontend
  end

  subgraph "Lookup Services"
    direction TB
    LookupEngine["Lookup Engine"]:::backend
    WhoisSocketParser["parse_whois_socket.py"]:::backend
    WhoisClient["whois.py"]:::backend
    Verified["verified/"]:::backend
    RDAPClients["webwhois/"]:::backend
  end

  subgraph "Data Sources"
    direction TB
    ReservedFilter["reserved_domains/"]:::data
    DataCSV["domains.query.csv"]:::data
    DataRegex["domains.query.regex.csv"]:::data
  end

  subgraph "Deployment"
    direction TB
    DockerContainer["Docker Container"]:::deployment
    DockerfileNode["Dockerfile"]:::deployment
    Compose4["docker-compose-ipv4.yml"]:::deployment
    Compose6["docker-compose-ipv6.yml"]:::deployment
    ConfigFile["Config_File/"]:::deployment
  end

  subgraph "External Systems"
    direction TB
    WhoisServers["WHOIS Servers\n(TCP:43)"]:::external
    RDAPServers["RDAP Servers\n(HTTPS)"]:::external
  end

  Browser -->|"HTTP GET/POST"| HTTPServer
  HTTPServer -->|"renders"| TemplateEngine
  HTTPServer -->|"serves"| StaticAssets
  HTTPServer -->|"invokes"| LookupEngine
  CLITool -->|"invokes"| LookupEngine
  LookupEngine -->|"socket pipeline"| WhoisSocketParser
  WhoisSocketParser -->|"parses"| WhoisClient
  WhoisClient -->|"fallback"| Verified
  LookupEngine -->|"HTTP pipeline"| RDAPClients
  WhoisServers -->|"responds"| WhoisClient
  RDAPServers -->|"responds"| RDAPClients
  LookupEngine -->|"filters"| ReservedFilter
  LookupEngine -->|"loads"| DataCSV
  LookupEngine -->|"loads"| DataRegex
  LookupEngine -->|"returns data"| HTTPServer
  HTTPServer -->|"HTTP Response"| Browser

  DockerContainer --> HTTPServer
  DockerContainer --> LookupEngine
  DockerContainer --> DataCSV
  DockerContainer --> DataRegex
  DockerContainer --> ReservedFilter
  DockerContainer --> ConfigFile
  DockerContainer --> DockerfileNode
  DockerContainer --> Compose4
  DockerContainer --> Compose6

  classDef frontend fill:#D0E4F5,stroke:#333,stroke-width:1px
  classDef backend fill:#D5E8D4,stroke:#333,stroke-width:1px
  classDef data fill:#FFF2CC,stroke:#333,stroke-width:1px
  classDef deployment fill:#E8E8E8,stroke:#333,stroke-width:1px
  classDef external fill:#F8CECC,stroke:#333,stroke-width:1px

  click StaticAssets "https://github.com/viettools/checkdomain/tree/3.x.x/static/"
  click TemplateEngine "https://github.com/viettools/checkdomain/tree/3.x.x/templates/"
  click HTTPServer "https://github.com/viettools/checkdomain/blob/3.x.x/main.py"
  click CLITool "https://github.com/viettools/checkdomain/blob/3.x.x/cctld.py"
  click WhoisSocketParser "https://github.com/viettools/checkdomain/blob/3.x.x/parse_whois_socket.py"
  click WhoisClient "https://github.com/viettools/checkdomain/blob/3.x.x/whois.py"
  click Verified "https://github.com/viettools/checkdomain/tree/3.x.x/verified/"
  click RDAPClients "https://github.com/viettools/checkdomain/tree/3.x.x/webwhois/"
  click ReservedFilter "https://github.com/viettools/checkdomain/tree/3.x.x/reserved_domains/"
  click DataCSV "https://github.com/viettools/checkdomain/blob/3.x.x/data/domains.query.csv"
  click DataRegex "https://github.com/viettools/checkdomain/blob/3.x.x/data/domains.query.regex.csv"
  click DockerfileNode "https://github.com/viettools/checkdomain/tree/3.x.x/Dockerfile"
  click Compose4 "https://github.com/viettools/checkdomain/blob/3.x.x/docker-compose-ipv4.yml"
  click Compose6 "https://github.com/viettools/checkdomain/blob/3.x.x/docker-compose-ipv6.yml"
  click ConfigFile "https://github.com/viettools/checkdomain/tree/3.x.x/Config_File/"
```
