# rh-mae/port-scanner architecture

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

- Interactive diagram: https://gitdiagram.com/rh-mae/port-scanner
- Repository: https://github.com/rh-mae/port-scanner

## Overview

##### Project type and purpose
- This is a standalone CLI tool (Rust Port Scanner) whose sole job is to asynchronously scan a range of TCP ports on a target IP and report which are open.
- It uses the Tokio async runtime for concurrency and Clap for command-line argument parsing.

##### File structure
- Top level:
- Cargo.toml / Cargo.lock – Rust package definition, dependencies (tokio, clap).
- src/main.rs – the entire application entry point and logic.
- README.md – documentation.

##### Extract key details from README
- Features: asynchronous scanning, timeout handling, cross-platform.
- Invocation: `cargo run -- --ip <IP> --start-port <START> --end-port <END>`.
- Under the hood: Clap handles CLI arguments → Tokio runtime drives asynchronous TCP connect attempts.

##### Main components
a. User / CLI Interface
- Entity: End user invokes the binary from a shell.
- Subcomponent: Clap parser reads `--ip`, `--start-port`, `--end-port`.
b. Application Core
- Component: Scanner Manager
– Initializes Tokio runtime
– Converts port range into a list of port numbers
– Schedules async tasks
- Component: Port Check Task (replicated for each port)
– Uses Tokio’s `TcpStream::connect` with a timeout (e.g., via `tokio::time::timeout`)
– Returns “open” or “closed/timeout”
c. Networking Layer
- Represents the OS’s TCP stack and network I/O
- Each Task issues a non-blocking connect request
d. Result Aggregator & Output
- Gathers successful task results
- Formats output lines to STDOUT

##### Relationships and data flow
- CLI Parser → Scanner Manager (init parameters)
- Scanner Manager → many Port Check Tasks (fan-out concurrency)
- Port Check Tasks → Networking Layer (async connect calls)
- Networking Layer → Port Check Tasks (ok/err result)
- Port Check Tasks → Aggregator → STDOUT

##### Architectural patterns and design principles
- Asynchronous concurrency (Tokio runtime, futures)
- Fan-out/fan-in pattern (spawn tasks for each port, then collect)
- Single binary, minimal layers
- Separation of concerns: argument parsing vs. scanning logic vs. output

##### Technologies / frameworks to annotate
- Rust (language)
- Tokio (async runtime & I/O)
- Clap (CLI argument parsing)
- std::net / tokio::net (TCP connect)
- tokio::time::timeout (timeout logic)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and external entities
    User(("End User")):::external
    Docs["Documentation\n(README.md)"]:::meta
    ProjectMeta["Project Metadata\n& Dependencies"]:::meta

    %% CLI layer
    CLI["CLI Parser\n(Clap)"]:::cli

    %% Core scanning logic
    Scanner["Scanner Manager"]:::core

    subgraph "Tokio Runtime"
        Task["Port Check Task\n(x N ports)\nwith timeout"]:::core
    end

    %% Networking layer
    Network[(OS TCP Stack)]:::network

    %% Output layer
    Aggregator["Result Aggregator\n& Output"]:::output
    STDOUT(("STDOUT\nConsole Output")):::output

    %% Data flow
    User -->|invokes binary| CLI
    CLI -->|"parses args"| Scanner
    Scanner -->|"spawn tasks"| Task
    Task -->|"connect request"| Network
    Network -->|"ok/err result"| Task
    Task -->|"task result"| Aggregator
    Aggregator -->|"print results"| STDOUT

    %% Project docs & metadata (external references)
    User -.->|reads| Docs
    Docs -.->|mentions deps| ProjectMeta

    %% Click events
    click CLI "https://github.com/rh-mae/port-scanner/blob/master/src/main.rs"
    click CLI "https://github.com/rh-mae/port-scanner/blob/master/Cargo.toml"
    click Scanner "https://github.com/rh-mae/port-scanner/blob/master/src/main.rs"
    click Task "https://github.com/rh-mae/port-scanner/blob/master/src/main.rs"
    click Network "https://github.com/rh-mae/port-scanner/blob/master/src/main.rs"
    click Network "https://github.com/rh-mae/port-scanner/blob/master/Cargo.toml"
    click Aggregator "https://github.com/rh-mae/port-scanner/blob/master/src/main.rs"
    click ProjectMeta "https://github.com/rh-mae/port-scanner/blob/master/Cargo.toml"
    click ProjectMeta "https://github.com/rh-mae/port-scanner/blob/master/Cargo.lock"
    click Docs "https://github.com/rh-mae/port-scanner/blob/master/README.md"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef network fill:#fff3cd,stroke:#856404,stroke-width:2px
    classDef output fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
    classDef meta fill:#f0f0f0,stroke:#888,stroke-width:1px,dasharray: 5 5
```
