# realgam3/pymultitor architecture

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

- Interactive diagram: https://gitdiagram.com/realgam3/pymultitor
- Repository: https://github.com/realgam3/pymultitor

## Overview

##### Main Components
- CLI/Entry Point: The project’s primary script, “pymultitor.py”, serves as the command-line interface. This component parses user arguments (e.g., --on-string, --tor-processes, etc.) and launches the service.
- Proxy Listener: The program listens on a specified host:port (default 127.0.0.1:8080) and handles incoming requests. It acts as an intermediary between the user’s tools and the Tor proxy logic.
- Tor Process Manager: Responsible for managing the pool of Tor processes (as defined by the “--tor-processes” argument and configured by “-c”/“--tor-cmd” and further settings). It starts, monitors, and rotates Tor instances per the user’s conditions.
- Request/Condition Handler: A core module that inspects each HTTP response for conditions like:
- A specific string (using --on-string)
- A regex match (--on-regex)
- A specific count of requests (--on-count)
- TCP RST or specific status codes
This component triggers the Tor Process Manager to rotate the proxy IP.
- Dependencies and External Components:
- mitmproxy: Although not directly visible in the file tree, it is a required dependency listed in the README.
- Tor: The executable used to route traffic as per user configuration.
- Docker Containerization (Deployment Aspect): The Dockerfile and related examples show how to run the entire service containerized.

##### Relationships and Interactions
- The Proxy Listener (running as a server) receives and processes the requests.
- The Request/Condition Handler inspects the responses to decide if a Tor rotation is needed.
- If a rotation condition triggers, the request is routed to the Tor Process Manager, which handles starting or switching among the active Tor processes.
- The Tor Process Manager interfaces with the Tor daemon (or uses the provided tor command) to establish a new circuit.
- Docker and CI/CD (as seen in the .github/workflows directory) represent deployment and automation pipelines, which are external to runtime but important for the maintenance lifecycle.

##### Architectural Patterns and Design Principles
- Modularity: Different responsibilities (command-line parsing, request handling, Tor process management) are separated clearly.
- Pipeline/Flow-based Architecture: The request lifecycle flows from the incoming request, through condition checks, to potential Tor process rotation.
- Dependency Injection: Through CLI arguments (e.g., tor command, configuration JSON) the design allows easy modification or replacement of underlying Tor instance management.
- Containerization: Docker is provided as an alternative deployment method, illustrating separation between development and production environments.

##### Relevant Technologies and Frameworks
- Python 3.10+ as the core language.
- mitmproxy for inspecting and manipulating HTTP traffic.
- Tor as the network anonymity and routing solution.
- Docker for containerization and deployment.
- CI/CD integration (GitHub Actions workflows found under “.github/workflows”) for automated testing/publishing.

##### Final Assembly
- “Proxy Listener” at the center, linked to the “Request/Condition Handler” and “Tor Process Manager”.
- “Tor Process Instances” as a grouped component below or beside the Tor Manager.
- Side nodes for “Docker/CI Pipeline” to show how the codebase is built/deployed, which, while not runtime, provide context on project maintenance.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% External client
    Client["Client Tools/Requests"]:::client

    %% Core Service Subgraph
    subgraph "Core Service"
        CLI_Entry["CLI/Entry Point"]:::core
        Proxy["Proxy Listener (127.0.0.1:8080)"]:::core
        ReqHandler["Request/Condition Handler (--on-string, --on-regex, --on-count, etc.)"]:::core
        Tor_Manager["Tor Process Manager"]:::core
        Tor_Instance["Tor Process Instance(s)"]:::core
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        Mitm["mitmproxy"]:::external
        Tor_Daemon["Tor Daemon (Tor)"]:::external
    end

    %% Deployment & Automation Subgraph
    subgraph "Deployment & Automation"
        Docker["Docker Container"]:::deployment
        CICD["CI/CD Pipelines"]:::deployment
        Examples["Example Use Cases"]:::deployment
    end

    %% Connections
    Client -->|"HTTPRequest"| Proxy
    CLI_Entry -->|"LaunchService"| Proxy
    Proxy -->|"InterceptTraffic"| Mitm
    Proxy -->|"ForwardRequest"| ReqHandler
    ReqHandler -->|"ConditionMet"| Tor_Manager
    Tor_Manager -->|"RotateProcess"| Tor_Instance
    Tor_Manager -->|"InitiateCircuit"| Tor_Daemon

    Docker -.->|"Containerizes"| CLI_Entry
    CICD -.->|"AutomatesDeploy"| CLI_Entry
    Examples -.->|"DemonstratesUsage"| CLI_Entry

    %% Click Events
    click CLI_Entry "https://github.com/realgam3/pymultitor/blob/master/pymultitor.py"
    click Proxy "https://github.com/realgam3/pymultitor/blob/master/pymultitor.py"
    click ReqHandler "https://github.com/realgam3/pymultitor/blob/master/pymultitor.py"
    click Tor_Manager "https://github.com/realgam3/pymultitor/blob/master/pymultitor.py"
    click Docker "https://github.com/realgam3/pymultitor/tree/master/Dockerfile"
    click CICD "https://github.com/realgam3/pymultitor/tree/master/.github/workflows/"
    click Examples "https://github.com/realgam3/pymultitor/tree/master/examples/"

    %% Styling Classes
    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef deployment fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
