# htrgouvea/nipe architecture

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

- Interactive diagram: https://gitdiagram.com/htrgouvea/nipe
- Repository: https://github.com/htrgouvea/nipe

## Overview

##### Main Components
- Command-Line Interface (CLI): Represented by the main script (nipe.pl) that accepts commands (install, start, stop, restart, status) from the user.
- Core Engine: Within the “lib/Nipe/Engine” directory, you see modules for Start, Stop, and Restart functionalities. These handle the logic for configuring, starting, stopping, and restarting the Tor-based routing process.
- Utility Modules: Located under “lib/Nipe/Utils” which encompass helper routines to manage network devices, installation processes, and status checks.
- Configuration Files: The “.configs” directory includes different torrc configuration files for various Linux distributions (CentOS, Debian, Fedora, etc.), representing the system-specific settings and rules needed to integrate with iptables and Tor.
- Tests: The “tests” directory with individual test files ensures each command/utility works correctly, indicating a commitment to quality and reliability.
- Infrastructure and CI/CD: The “.github” folder contains GitHub workflows, issue templates, and contributing guidelines, which demonstrate the practices for continuous integration, linting, testing, and community interaction.

##### Relationships and Interactions
- The CLI (nipe.pl) receives user commands and then routes those commands to the appropriate Engine module (for starting, stopping, etc.).
- The Engine modules interact with the underlying system (using iptables and configuration files from .configs) to set up network redirection.
- The Utility modules provide supporting functions such as checking network status, installing dependencies, and manipulating device settings.
- The entire system is supported by continuous integration flows that run tests and static analysis, ensuring that new changes do not break core functionality.

##### Architectural Patterns and Technologies
- Command Pattern: The different actions (install, start, stop, etc.) can be seen as commands that trigger specific engine modules.
- Modular Design: With a clean separation between engine logic and utility functions, followed by strong testing practices.
- System Integration: Interaction with system components like iptables and reliance on configuration tailored for various Linux distributions.
- Perl as the primary language, with dependencies installed via cpanm, suggests use of standard Perl module practices.
- CI/CD and static analysis (via GitHub workflows and configurations such as .editorconfig and .perlcriticrc) are important for maintaining code quality.

##### Final Assembly
- Optionally, add a separate section for testing and CI/CD to indicate quality assurance as part of the overall system lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["nipe.pl"]:::cli
    end

    %% Engine Layer
    subgraph "Engine Modules"
        ES["Engine: Start"]:::engine
        EStop["Engine: Stop"]:::engine
        ERestart["Engine: Restart"]:::engine
    end

    %% Utility Layer
    subgraph "Utility Modules"
        UD["Utils: Device"]:::utils
        UI["Utils: Install"]:::utils
        US["Utils: Status"]:::utils
        UH["Utils: Helper"]:::utils
    end

    %% Configuration Files Cluster
    subgraph "Configurations (.configs)"
        configArch["arch-torrc"]:::config
        configCentos["centos-torrc"]:::config
        configDebian["debian-torrc"]:::config
        configFedora["fedora-torrc"]:::config
        configOpensuse["opensuse-torrc"]:::config
        configVoid["void-torrc"]:::config
    end

    %% System Components
    subgraph "System Components"
        IPT["System (iptables & OS config)"]:::system
    end

    %% External Service
    Ext["Tor Network"]:::external

    %% Testing and CI/CD
    subgraph "Testing & CI/CD"
        subgraph "Tests"
            testDevice["Device.t"]:::testing
            testHelper["Helper.t"]:::testing
            testInstall["Install.t"]:::testing
            testRestart["Restart.t"]:::testing
            testStart["Start.t"]:::testing
            testStatus["Status.t"]:::testing
            testStop["Stop.t"]:::testing
        end
        CI_CD["CI/CD Workflows"]:::cicd
    end

    %% Connections from CLI to Engine Modules
    CLI -->|"command"| ES
    CLI -->|"command"| EStop
    CLI -->|"command"| ERestart

    %% Engine Modules load configuration (example using debian-torrc as representative)
    ES -->|"load_config"| configDebian
    EStop -->|"load_config"| configDebian
    ERestart -->|"load_config"| configDebian

    %% Engine Modules apply rules to system
    ES -->|"apply_rules"| IPT
    EStop -->|"apply_rules"| IPT
    ERestart -->|"apply_rules"| IPT

    %% System routes traffic to external Tor Network
    IPT -->|"route_traffic"| Ext

    %% Utility Modules support Engine Modules and System (dashed arrows)
    UD -.->|"supports"| ES
    UI -.->|"supports"| EStop
    US -.->|"supports"| ERestart
    UH -.->|"assists"| IPT

    %% CI/CD interactions for quality assurance
    CI_CD -->|"run_tests"| testDevice
    CI_CD -->|"run_tests"| testHelper
    CI_CD -->|"run_tests"| testInstall
    CI_CD -->|"run_tests"| testRestart
    CI_CD -->|"run_tests"| testStart
    CI_CD -->|"run_tests"| testStatus
    CI_CD -->|"run_tests"| testStop
    CI_CD -.->|"checks"| ES

    %% Click Events for CLI
    click CLI "https://github.com/htrgouvea/nipe/blob/main/nipe.pl"

    %% Click Events for Engine Modules
    click ES "https://github.com/htrgouvea/nipe/blob/main/lib/Nipe/Engine/Start.pm"
    click EStop "https://github.com/htrgouvea/nipe/blob/main/lib/Nipe/Engine/Stop.pm"
    click ERestart "https://github.com/htrgouvea/nipe/blob/main/lib/Nipe/Engine/Restart.pm"

    %% Click Events for Utility Modules
    click UD "https://github.com/htrgouvea/nipe/blob/main/lib/Nipe/Utils/Device.pm"
    click UI "https://github.com/htrgouvea/nipe/blob/main/lib/Nipe/Utils/Install.pm"
    click US "https://github.com/htrgouvea/nipe/blob/main/lib/Nipe/Utils/Status.pm"
    click UH "https://github.com/htrgouvea/nipe/blob/main/lib/Nipe/Utils/Helper.pm"

    %% Click Events for Configuration Files
    click configArch "https://github.com/htrgouvea/nipe/tree/main/.configs/arch-torrc"
    click configCentos "https://github.com/htrgouvea/nipe/tree/main/.configs/centos-torrc"
    click configDebian "https://github.com/htrgouvea/nipe/tree/main/.configs/debian-torrc"
    click configFedora "https://github.com/htrgouvea/nipe/tree/main/.configs/fedora-torrc"
    click configOpensuse "https://github.com/htrgouvea/nipe/tree/main/.configs/opensuse-torrc"
    click configVoid "https://github.com/htrgouvea/nipe/tree/main/.configs/void-torrc"

    %% Click Events for Tests
    click testDevice "https://github.com/htrgouvea/nipe/blob/main/tests/Device.t"
    click testHelper "https://github.com/htrgouvea/nipe/blob/main/tests/Helper.t"
    click testInstall "https://github.com/htrgouvea/nipe/blob/main/tests/Install.t"
    click testRestart "https://github.com/htrgouvea/nipe/blob/main/tests/Restart.t"
    click testStart "https://github.com/htrgouvea/nipe/blob/main/tests/Start.t"
    click testStatus "https://github.com/htrgouvea/nipe/blob/main/tests/Status.t"
    click testStop "https://github.com/htrgouvea/nipe/blob/main/tests/Stop.t"

    %% Click Event for CI/CD
    click CI_CD "https://github.com/htrgouvea/nipe/blob/main/.github"

    %% Styles
    classDef cli fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef engine fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef utils fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef config fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef system fill:#ffa500,stroke:#333,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef testing fill:#ee82ee,stroke:#333,stroke-width:2px;
    classDef cicd fill:#b0c4de,stroke:#333,stroke-width:2px;
```
