# gones75/nettracker-bot architecture

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

- Interactive diagram: https://gitdiagram.com/gones75/nettracker-bot
- Repository: https://github.com/gones75/nettracker-bot

## Overview

##### Project Type and Purpose
- This is a specialized Discord bot implemented in a single Python script (`nettracker.py`).
- Purpose: Provide network management and scanning tools (subnet scan, IP check, next-free IP lookup, IP details, network info) via Discord commands.

##### File Structure Analysis
- Top-level files only:
- `.env.example` – template for environment variables (Discord token, default network settings)
- `nettracker.py` – core application containing command handlers and scanning logic
- `README.md` – documentation and usage instructions
- `.gitignore` – standard ignore file
- No separate frontend/backend folders; it’s a single-process, event-driven application.
- Key libraries (from README): `discord.py`, `python-dotenv`, `ipaddress`. Scanning via ARP, ICMP ping, and TCP port checks.

##### Components
a. External Services and Data Sources
- Discord Gateway/API (external cloud service)
- Local network infrastructure (switches, routers, devices providing ARP tables, ICMP responses, open TCP ports)
b. Bot Application
- Environment/Configuration Loader (reads `.env`)
- Discord Client & Event Loop (`discord.py` event handlers)
- Command Dispatcher (parses `!scan_subnet`, `!check_ip`, etc.)
- Network Scanning Modules:
- ARP Scanner
- ICMP Pinger
- TCP Port Checker
- Response Formatter (builds messages, embeds results)
c. Communication Flows
- User → Discord API → Bot
- Bot → OS network stack → Network Devices → Bot
- Bot → Discord API → User (channel or DM)

##### Relationships and Interactions
- On startup: Configuration Loader reads environment variables from `.env`.
- The Discord Client connects to the Discord Gateway and listens for messages.
- When a user issues a command:
1. Event Loop receives message from Discord API.
2. Command Dispatcher routes to appropriate scanning routine.
3. Scanning Module(s) invoke the OS networking stack for ARP table lookup, ICMP echo, and/or TCP port attempts.
4. Scanning results are collected, formatted, and sent back via the Discord Client.
- Optionally: Command outputs are cleaned up or deleted after processing for privacy.

##### Architectural Patterns and Principles
- Event-driven architecture (Discord.py event loop).
- Modular separation between “command parsing” and “network scanning logic.”
- Single-process design with external dependencies handled via well-defined Python libraries.
- No persistent data store; ephemeral data flows from network scan to Discord message.

##### Detail and Clarity
- Block is clearly labeled with component name and key technology (e.g., “Discord Client (discord.py)”).
- `.env` file feeding into the Configuration Loader.
- OS network stack boundary between scanning modules and the external network.
- Retry logic or scanning fallbacks (ARP → Ping → TCP) to show the sequence of scan methods.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users and Services
    User["User"]:::external
    DiscordAPI["Discord Gateway/API"]:::external

    %% Bot Process Container
    subgraph "Bot Process"
        ConfigLoader["Configuration Loader (.env loader)"]:::config
        DiscordClient["Discord Client & Event Loop (discord.py)"]:::internal
        CommandDispatcher["Command Dispatcher"]:::internal
        subgraph "Scanning Modules"
            ARPScanner["ARP Scanner"]:::module
            ICMPPinger["ICMP Pinger"]:::module
            TCPChecker["TCP Port Checker"]:::module
        end
        ResponseFormatter["Response Formatter"]:::internal
    end

    %% OS Networking and Local Network
    OSStack["OS Networking Stack"]:::network
    LocalNetwork["Local Network Devices"]:::network

    %% Documentation and Config Files
    README["Documentation (README.md)"]:::config
    GitIgnore["Git Ignore Rules (.gitignore)"]:::config

    %% Communication Flows
    User -->|"Command"| DiscordAPI
    DiscordAPI -->|"Command JSON"| DiscordClient
    ConfigLoader --> DiscordClient
    DiscordClient -->|Event| CommandDispatcher
    CommandDispatcher -->|invoke| ARPScanner
    CommandDispatcher -->|invoke| ICMPPinger
    CommandDispatcher -->|invoke| TCPChecker
    ARPScanner -->|"ARP query"| OSStack
    ICMPPinger -->|"Ping request"| OSStack
    TCPChecker -->|"TCP probe"| OSStack
    OSStack -->|"ARP response"| ARPScanner
    OSStack -->|"Ping reply"| ICMPPinger
    OSStack -->|"Port open/closed"| TCPChecker
    ARPScanner -->|results| ResponseFormatter
    ICMPPinger -->|results| ResponseFormatter
    TCPChecker -->|results| ResponseFormatter
    ResponseFormatter -->|Message Embed| DiscordClient
    DiscordClient -->|"Message"| DiscordAPI
    DiscordAPI -->|Deliver| User

    %% Config file flow
    README -.-> ConfigLoader
    GitIgnore -.-> ConfigLoader

    %% Click Events
    click ConfigLoader "https://github.com/gones75/nettracker-bot/blob/main/.env.example"
    click DiscordClient "https://github.com/gones75/nettracker-bot/blob/main/nettracker.py"
    click CommandDispatcher "https://github.com/gones75/nettracker-bot/blob/main/nettracker.py"
    click ARPScanner "https://github.com/gones75/nettracker-bot/blob/main/nettracker.py"
    click ICMPPinger "https://github.com/gones75/nettracker-bot/blob/main/nettracker.py"
    click TCPChecker "https://github.com/gones75/nettracker-bot/blob/main/nettracker.py"
    click ResponseFormatter "https://github.com/gones75/nettracker-bot/blob/main/nettracker.py"
    click README "https://github.com/gones75/nettracker-bot/blob/main/README.md"
    click GitIgnore "https://github.com/gones75/nettracker-bot/blob/main/.gitignore"

    %% Styles
    classDef external fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef internal fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef module fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef config fill:#E0E0E0,stroke:#9E9E9E,color:#424242
    classDef network fill:#F5F5F5,stroke:#BDBDBD,color:#616161
```
