# brandonyoungdev/tldx architecture

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

- Interactive diagram: https://gitdiagram.com/brandonyoungdev/tldx
- Repository: https://github.com/brandonyoungdev/tldx

## Overview

##### Project type and purpose
- tldx is a command-line tool (written in Go) that generates and checks domain-name permutations for availability.
- It’s neither a multi-tier web app nor a microservices system but a standalone CLI utility that orchestrates several internal components plus an external WHOIS lookup service.

##### File structure
- cmd/ + root.go
- Implements the CLI interface using the Cobra library. Parses flags (keywords, prefixes, suffixes, TLDs, filters).
- main.go
- Entrypoint that calls cmd.Execute() to start the CLI.
- internal/domain/
- domain.go, styles.go: core “permutation engine” that builds keyword + prefix/suffix/TLD combinations.
- domain_test.go: unit tests for the domain logic.
- assets/
- Static assets (logo). Not part of runtime logic.
- Makefile, .github/, goreleaser.yml, etc.
- tapes/
- Demo scripts/images illustrating example runs.

##### README for insights
- Uses flags to drive behavior (–prefixes, –suffixes, –only-available, etc.)
- Concurrent WHOIS checks
- Streams results as they’re found
- No external database – availability checks hit WHOIS servers or a DNS lookup API.

##### Main components & their interactions
a. CLI Parser (cmd/root.go + Cobra)
- Reads user input and flags → produces a configuration object.
b. Permutation Engine (internal/domain)
- Receives keywords + prefixes/suffixes/TLDs → generates a channel/stream of candidate domains.
c. Availability Checker
- Consumes domain stream → kicks off concurrent WHOIS/DNS lookups (via Go routines) → tags each domain AVAILABLE or NOT.
d. Filter / Stats Collector
- Optionally filters out unavailable domains and/or applies length constraints, collects stats if requested.
e. Output Streamer
- Formats and writes results to stdout as soon as they come in (✔️ or ❌).

External service:
- WHOIS or DNS query endpoints (public whois servers or DNS resolvers).

##### Architectural patterns & design principles
- Pipeline pattern: domain candidates flow from generator → checker → filter → output.
- Concurrency: Go routines + channels for fan-out WHOIS queries.
- Separation of concerns: CLI parsing vs. business logic (domain permutations) vs. I/O (network and console).

##### Elements
- “CLI Parser (Cobra)”
- “Permutation Engine (internal/domain)”
- “Availability Checker (concurrent WHOIS)”
- “Filter & Stats Collector”
- “Output Streamer”
CLI Parser → Permutation Engine → Availability Checker → Filter → Output Streamer → Console
Availability Checker ↔ WHOIS/DNS Servers
- Blue for internal modules
- Green for external services
- Orange for data stores or streams

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Pipeline"
        Entry["Application Entry Point\n(main.go)"]:::internal
        CLI_Parser["CLI Parser (Cobra)\n(cmd/root.go)"]:::internal
        Perm_Engine["Permutation Engine\n(internal/domain/domain.go)"]:::internal
        Availability["Availability Checker\n(concurrent WHOIS\nN workers)"]:::internal
        Filter["Filter & Stats Collector"]:::internal
        Output["Output Streamer"]:::internal
        Console["Console (stdout)"]:::data
        WHOIS["WHOIS/DNS Servers"]:::external

        Entry -->|starts CLI| CLI_Parser
        CLI_Parser -->|config object| Perm_Engine
        Perm_Engine -->|"domain name string"| Availability
        Availability -->|"tagged result"| Filter
        Filter -->|"filtered/result stream"| Output
        Output -->|writes| Console
        Availability -->|"WHOIS/DNS query"| WHOIS
        WHOIS -->|"availability data"| Availability
    end

    subgraph "Helpers & Tests"
        Styles["Output Styling Helpers\n(internal/domain/styles.go)"]:::internal
        Tests["Domain Logic Unit Tests\n(internal/domain/domain_test.go)"]:::internal
        Assets["Static Assets\n(assets/)"]:::internal

        Styles --> Output
    end

    click Entry "https://github.com/brandonyoungdev/tldx/blob/main/main.go"
    click CLI_Parser "https://github.com/brandonyoungdev/tldx/blob/main/cmd/root.go"
    click Perm_Engine "https://github.com/brandonyoungdev/tldx/blob/main/internal/domain/domain.go"
    click Styles "https://github.com/brandonyoungdev/tldx/blob/main/internal/domain/styles.go"
    click Tests "https://github.com/brandonyoungdev/tldx/blob/main/internal/domain/domain_test.go"
    click Assets "https://github.com/brandonyoungdev/tldx/tree/main/assets/"

    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
```
