# invgate/pytun architecture

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

- Interactive diagram: https://gitdiagram.com/invgate/pytun
- Repository: https://github.com/invgate/pytun

## Overview

##### Main Components
- Main Application Entry Point: The main script (pytun.py) is used to start the tunnel. It parses command-line parameters and loads a configuration (an ini file) to get tunnel settings.
- Configuration Management: The project uses configuration files located in the “configs” directory and additional ini files (e.g., pytun.ini) to define tunnel settings.
- Tunnel Infrastructure: The “tunnel_infra” directory includes key modules like Tunnel.py, TunnelProcess.py, and pathtype.py responsible for setting up the actual tunnel processes, managing connections, and handling different paths/types.
- Alerting Subsystem: The “alerts” directory (with files like alert_sender.py, email_alert.py, http_post_alert.py, etc.) handles sending notifications when issues or events occur.
- Observation / Monitoring Module: The “observation” directory contains modules (such as connection_check.py, http_server.py, status.py) to monitor the tunnel’s health, provide connection status, and possibly serve a web interface for status.
- Supporting Utilities and Libraries: Other files like “configure_logger.py”, “lib/ratelimit.py”, “utils.py”, “device.py”, and “version.py” provide helper functions, logging configuration, rate limiting, device identification aspects, and versioning.
- GitHub Configuration: The “.github” directory (with workflows like codeql-analysis.yml) is present for CI/CD and static code analysis.

##### Relationships and Interactions
- Start Point (pytun.py): This is the application entry that reads user-provided configuration (the ini file) and then instantiates tunnel connectors based on “tunnel_infra”.
- Configuration Files: The configuration files in “configs” act as the central source of truth for connector parameters such as the server endpoint, ports, SSH keys, etc. The main script reads these and passes the details to the tunnel infrastructure.
- Tunnel Infrastructure: Once configuration is loaded, the components under “tunnel_infra” are responsible for setting up the tunnel connection between the local service and the remote cloud endpoint. They abstract the initiation of a tunnel process, manage its life-cycle, and determine the proper “pathtype”.
- Alerting System: During the connection life cycle, if any error or important event occurs, the appropriate module from “alerts” is called (e.g., email or HTTP POST alerts) to notify the relevant parties.
- Observation & Health Check: Periodically, or on-demand, the modules under “observation” perform connection checks, expose statuses (possibly via an embedded HTTP server), and log connection health.
- Logger & Rate Limiting: The logging setup using “configure_logger.py” and other utilities ensure that all actions are properly logged. “lib/ratelimit.py” might be used to limit the frequency of certain operations, such as sending alerts.

##### Architectural Patterns and Design Principles
- Modularity: The project is separated into clearly defined modules (tunnel infrastructure, alerting, observation, configuration, utilities) which promotes separation of concerns.
- Configuration-driven Behavior: The use of external configuration (ini) files, along with a directory of configs, shows that the behavior is highly customizable.
- Extensibility: The presence of multiple alert types and observation methods indicates that the system is designed to be extended easily to incorporate more protocols or monitoring strategies.
- Process Management: The tunnel infrastructure likely uses subprocesses (or similar mechanisms) to manage separate tunnel processes for isolation and resilience.

- “Configuration Module” (reads from files in /configs)
- “Tunnel Infrastructure” (from /tunnel_infra)
- Under “Tunnel Infrastructure”, break it down further to highlight:
- Process Initialization (Tunnel.py, TunnelProcess.py)
- Protocol/Path Management (pathtype.py)
- “Alerting Module” (with subcomponents like email_alert, http_post_alert, pooled_alerter)
- “Observation Module” (including connection_check, http_server, status)
- “Utilities & Helpers” (e.g., logging configuration, ratelimit, utils) that support each main component.
- A note for the CI/CD pipelines inside the .github folder indicating the existence of automated analysis and workflows, though these are peripheral to system operation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Application Layer
    subgraph "Main Application"
        A["pytun.py"]:::app
    end

    %% Configuration Layer
    subgraph "Configuration Management"
        B["Configuration Files (configs/)"]:::config
        B2["pytun.ini"]:::config
    end

    %% Tunnel Infrastructure Layer
    subgraph "Tunnel Infrastructure"
        C1["Tunnel.py"]:::infra
        C2["TunnelProcess.py"]:::infra
        C3["pathtype.py"]:::infra
    end

    %% Alerting Subsystem Layer
    subgraph "Alerting Subsystem"
        D1["alert_sender.py"]:::alerts
        D2["email_alert.py"]:::alerts
        D3["http_post_alert.py"]:::alerts
        D4["pooled_alerter.py"]:::alerts
    end

    %% Observation Module Layer
    subgraph "Observation Module"
        E1["connection_check.py"]:::observation
        E2["http_server.py"]:::observation
        E3["status.py"]:::observation
    end

    %% Utilities & Helpers Layer
    subgraph "Utilities & Helpers"
        F1["configure_logger.py"]:::utilities
        F2["ratelimit.py"]:::utilities
        F3["device.py"]:::utilities
        F4["utils.py"]:::utilities
        F5["version.py"]:::utilities
    end

    %% GitHub CI/CD Layer
    subgraph "GitHub CI/CD"
        G[".github"]:::github
    end

    %% Connections
    A -->|"reads"| B
    A -->|"reads"| B2
    B2 -->|"configures"| C1
    A -->|"initiates"| C1
    C1 -->|"triggers"| D1
    C1 -->|"updates"| E1
    C1 -->|"logs"| F1
    F2 -->|"limits"| C1

    %% Styling Classes
    classDef app fill:#f9c,stroke:#333,stroke-width:2px;
    classDef config fill:#ff9,stroke:#333,stroke-width:2px;
    classDef infra fill:#9f9,stroke:#333,stroke-width:2px;
    classDef alerts fill:#f99,stroke:#333,stroke-width:2px;
    classDef observation fill:#99f,stroke:#333,stroke-width:2px;
    classDef utilities fill:#fc9,stroke:#333,stroke-width:2px;
    classDef github fill:#ccc,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/invgate/pytun/blob/master/pytun.py"
    click B "https://github.com/invgate/pytun/tree/master/configs/"
    click B2 "https://github.com/invgate/pytun/blob/master/pytun.ini"
    click C1 "https://github.com/invgate/pytun/blob/master/tunnel_infra/Tunnel.py"
    click C2 "https://github.com/invgate/pytun/blob/master/tunnel_infra/TunnelProcess.py"
    click C3 "https://github.com/invgate/pytun/blob/master/tunnel_infra/pathtype.py"
    click D1 "https://github.com/invgate/pytun/blob/master/alerts/alert_sender.py"
    click D2 "https://github.com/invgate/pytun/blob/master/alerts/email_alert.py"
    click D3 "https://github.com/invgate/pytun/blob/master/alerts/http_post_alert.py"
    click D4 "https://github.com/invgate/pytun/blob/master/alerts/pooled_alerter.py"
    click E1 "https://github.com/invgate/pytun/blob/master/observation/connection_check.py"
    click E2 "https://github.com/invgate/pytun/blob/master/observation/http_server.py"
    click E3 "https://github.com/invgate/pytun/blob/master/observation/status.py"
    click F1 "https://github.com/invgate/pytun/blob/master/configure_logger.py"
    click F2 "https://github.com/invgate/pytun/blob/master/lib/ratelimit.py"
    click F3 "https://github.com/invgate/pytun/blob/master/device.py"
    click F4 "https://github.com/invgate/pytun/blob/master/utils.py"
    click F5 "https://github.com/invgate/pytun/blob/master/version.py"
    click G "https://github.com/invgate/pytun/tree/master/.github/"
```
