# xtls/realitlscanner architecture

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

- Interactive diagram: https://gitdiagram.com/xtls/realitlscanner
- Repository: https://github.com/xtls/realitlscanner

## Overview

RealiTLScanner is a command-line TLS scanner. Its workflow selects one target source (address, file, or URL), turns targets into hosts, scans them concurrently, enriches successful TLS results with optional GeoIP, and writes CSV output. The sampled source shows the main orchestration and core scan path; URL crawling is implemented inline in main.go, so it is represented as a distinct responsibility at that path.

Main entry points: [`main.go`](https://github.com/xtls/realitlscanner/blob/main/main.go) (CLI Orchestrator), [`scanner.go`](https://github.com/xtls/realitlscanner/blob/main/scanner.go) (TLS Scanner), [`geo.go`](https://github.com/xtls/realitlscanner/blob/main/geo.go) (GeoIP Lookup), [`utils.go`](https://github.com/xtls/realitlscanner/blob/main/utils.go) (Address Iterator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Target Inputs"]
  node_address["Address Input"]
  node_target_file["Target File"]
  node_url_page["URL Page"]
  node_url_crawler["URL Crawler<br/>[main.go]"]
  node_target_parser["Target Parser<br/>[utils.go]"]
  node_address_iterator["Address Iterator<br/>[utils.go]"]
end

subgraph group_runtime["Scan Runtime"]
  node_cli["CLI Orchestrator<br/>[main.go]"]
  node_dns_lookup["DNS Lookup<br/>[utils.go]"]
  node_worker_pool["Scan Workers<br/>[main.go]"]
  node_tls_scanner["TLS Scanner<br/>[scanner.go]"]
  node_geoip["GeoIP Lookup<br/>[geo.go]"]
end

subgraph group_results["Results"]
  node_result_channel["Result Channel<br/>[utils.go]"]
  node_output_writer["Output Writer<br/>[utils.go]"]
  node_csv_file["CSV Output"]
  node_maxmind_db[("MaxMind Database")]
end

node_operator(("Operator"))
node_tls_targets["TLS Targets"]

node_operator -->|"configures"| node_cli
node_address -->|"selects"| node_cli
node_target_file -->|"selects"| node_cli
node_url_page -->|"fetches"| node_url_crawler
node_cli -->|"runs"| node_url_crawler
node_cli -->|"enumerates"| node_address_iterator
node_cli -->|"parses"| node_target_parser
node_url_crawler -->|"passes domains"| node_target_parser
node_address_iterator -->|"resolves"| node_dns_lookup
node_worker_pool -->|"dispatches hosts"| node_tls_scanner
node_cli -->|"starts workers"| node_worker_pool
node_tls_scanner -->|"resolves domains"| node_dns_lookup
node_tls_scanner -->|"dials and handshakes"| node_tls_targets
node_tls_scanner -->|"looks up country"| node_geoip
node_cli -->|"initializes"| node_geoip
node_maxmind_db -->|"provides country data"| node_geoip
node_cli -->|"creates"| node_output_writer
node_tls_scanner -->|"sends CSV rows"| node_result_channel
node_output_writer -->|"writes rows"| node_csv_file

click node_cli "https://github.com/xtls/realitlscanner/blob/main/main.go"
click node_url_crawler "https://github.com/xtls/realitlscanner/blob/main/main.go"
click node_target_parser "https://github.com/xtls/realitlscanner/blob/main/utils.go"
click node_address_iterator "https://github.com/xtls/realitlscanner/blob/main/utils.go"
click node_dns_lookup "https://github.com/xtls/realitlscanner/blob/main/utils.go"
click node_worker_pool "https://github.com/xtls/realitlscanner/blob/main/main.go"
click node_tls_scanner "https://github.com/xtls/realitlscanner/blob/main/scanner.go"
click node_geoip "https://github.com/xtls/realitlscanner/blob/main/geo.go"
click node_result_channel "https://github.com/xtls/realitlscanner/blob/main/utils.go"
click node_output_writer "https://github.com/xtls/realitlscanner/blob/main/utils.go"

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_address,node_target_file,node_url_page,node_url_crawler,node_target_parser,node_address_iterator toneBlue
class node_cli,node_dns_lookup,node_worker_pool,node_tls_scanner,node_geoip toneAmber
class node_result_channel,node_output_writer,node_csv_file,node_maxmind_db toneMint
class node_operator,node_tls_targets toneIndigo
```

## Components

### Target Inputs

- **Address Input**
- **Target File**
- **URL Page**
- [URL Crawler](https://github.com/xtls/realitlscanner/blob/main/main.go): `main.go`
- [Target Parser](https://github.com/xtls/realitlscanner/blob/main/utils.go): `utils.go`
- [Address Iterator](https://github.com/xtls/realitlscanner/blob/main/utils.go): `utils.go`

### Scan Runtime

- [CLI Orchestrator](https://github.com/xtls/realitlscanner/blob/main/main.go): `main.go`
- [DNS Lookup](https://github.com/xtls/realitlscanner/blob/main/utils.go): `utils.go`
- [Scan Workers](https://github.com/xtls/realitlscanner/blob/main/main.go): `main.go`
- [TLS Scanner](https://github.com/xtls/realitlscanner/blob/main/scanner.go): `scanner.go`
- [GeoIP Lookup](https://github.com/xtls/realitlscanner/blob/main/geo.go): `geo.go`

### Results

- [Result Channel](https://github.com/xtls/realitlscanner/blob/main/utils.go): `utils.go`
- [Output Writer](https://github.com/xtls/realitlscanner/blob/main/utils.go): `utils.go`
- **CSV Output**
- **MaxMind Database**

### Other components

- **Operator**
- **TLS Targets**

## Connections

- Operator → CLI Orchestrator: configures (evidence: `README.md`)
- Address Input → CLI Orchestrator: selects (evidence: `main.go`)
- Target File → CLI Orchestrator: selects (evidence: `main.go`)
- URL Page → URL Crawler: fetches (evidence: `main.go`)
- CLI Orchestrator → URL Crawler: runs (evidence: `main.go`)
- CLI Orchestrator → Address Iterator: enumerates (evidence: `main.go`)
- CLI Orchestrator → Target Parser: parses (evidence: `main.go`)
- URL Crawler → Target Parser: passes domains (evidence: `main.go`)
- Address Iterator → DNS Lookup: resolves (evidence: `utils.go`)
- Scan Workers → TLS Scanner: dispatches hosts (evidence: `main.go`)
- CLI Orchestrator → Scan Workers: starts workers (evidence: `main.go`)
- TLS Scanner → DNS Lookup: resolves domains (evidence: `scanner.go`)
- TLS Scanner → TLS Targets: dials and handshakes (evidence: `scanner.go`)
- TLS Scanner → GeoIP Lookup: looks up country (evidence: `scanner.go`)
- CLI Orchestrator → GeoIP Lookup: initializes (evidence: `main.go`)
- MaxMind Database → GeoIP Lookup: provides country data (evidence: `geo.go`)
- CLI Orchestrator → Output Writer: creates (evidence: `main.go`)
- TLS Scanner → Result Channel: sends CSV rows (evidence: `scanner.go`)
- Output Writer → CSV Output: writes rows
