# swyamsharma/calculatency architecture

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

- Interactive diagram: https://gitdiagram.com/swyamsharma/calculatency
- Repository: https://github.com/swyamsharma/calculatency

## Overview

##### Project Type and Purpose
- It’s a network diagnostic/measurement tool that compares round-trip times (RTT) obtained through WebSocket pings and low-level ICMP/TCP probe-based techniques.
- Its main goal is to detect the presence of network proxies and differentiate between direct and possibly proxied connections by comparing RTTs.

##### Analyzing the File Structure
- The project comprises mainly two directory trees: Single_client and Multi_client. These folders mirror one another, sharing the same set of files (config.py, server.py, static content, static_server.py, tracer.py, websocket_ping.py).
- Both directories use shared client-side components (HTML, JavaScript) served by the static server.
- The “config.py” contains key configuration parameters for port numbers, probe counts, and thresholds.
- “websocket_ping.py” handles the WebSocket-based RTT measurement, while “tracer.py” encapsulates the 0trace measurement logic.
- “server.py” in each client folder is responsible for initializing the WebSocket server, handling client connections, and integrating both measurement methods.

##### Key Project Components
a. Client Side:
- Web Browser: This loads the static files (index.html and script.js) via the static file server.
- Static File Server: Dedicated to serving the web interface and the JavaScript that initiates tests.

b. Server Side:
- Main Server (server.py): Listens for WebSocket connections and coordinates the RTT measurement process.
- WebSocket RTT Measurement Module: Represented by the “websocket_ping.py” script which sends pings and calculates round-trip time.
- Tracer/0trace Module: Represented by “tracer.py”. It sends raw TCP ACK packets with increasing TTL values using Scapy, listens for ICMP responses, and calculates RTT based on hops.
- Configuration Module: “config.py” which defines operational parameters.

c. Underlying Technologies/Frameworks:
- Python 3 runtime.
- WebSocket library for handling bidirectional communication.
- Scapy for raw packet processing and network probing.
- netifaces for network interface details.
- Concurrency mechanisms (in the Multi_client version using thread-safe shared dictionaries/locks).

##### Relationships and Interactions
- A client (via the web browser) accesses the static server to load the user interface.
- From the UI, the client initiates a test that establishes a WebSocket connection to the main server.
- On the server, the WebSocket RTT measurement module engages the client in a ping-pong exchange to record RTT.
- Simultaneously, the tracer module executes 0trace’s two phases:
- Phase 1: Sending incrementally TTL-dependant packets and sniffing for ICMP messages.
- Phase 2: Sending multiple probes to the final hop and determining the accurate RTT.
- The main server compares both RTT values. If the WebSocket RTT exceeds the 0trace RTT by a configured threshold (as set in “config.py”), it concludes a proxy is likely present.
- The detection results are then relayed back to the client over the established WebSocket connection.

##### Architectural Patterns and Design Principles
- Modular Design: The separation of measurement methods (WebSocket vs. 0trace) into their own Python modules facilitates code reuse and clarity.
- Concurrency/Scalability (Multi_client): The Multi_client folder implements concurrent handling by using shared state with thread safety so that multiple client sessions do not interfere with each other.
- Separation of Concerns: Client-facing static content (HTML, JS) is decoupled from the server logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Web Browser"]:::client

    subgraph "Single_client Variant"
        G["Client Static Content"]:::client
        B["Static File Server"]:::server
        C["Main Server"]:::server
        D["WebSocket RTT Module"]:::module
        E["Tracer/0trace Module"]:::module
        F["Configuration"]:::config

        A -->|"HTTP_Request"| G
        G -->|"Served_by"| B
        A -->|"WebSocket_Connection"| C
        C -->|"Initiates"| D
        C -->|"Initiates"| E
        F -->|"Configures"| D
        F -->|"Configures"| E
        D -->|"RTT_Result"| C
        E -->|"RTT_Result"| C
        C -->|"Returns_Results"| A
    end

    subgraph "Multi_client Variant"
        M["Client Static Content"]:::client
        H["Static File Server"]:::server
        I["Main Server"]:::server
        J["WebSocket RTT Module"]:::module
        K["Tracer/0trace Module"]:::module
        L["Configuration"]:::config
        N["Shared State Manager (Locks&Dictionaries)"]:::concurrency

        A -->|"HTTP_Request"| M
        M -->|"Served_by"| H
        A -->|"WebSocket_Connection"| I
        I -->|"Initiates"| J
        I -->|"Initiates"| K
        L -->|"Configures"| J
        L -->|"Configures"| K
        I -->|"Uses"| N
        J -->|"RTT_Result"| I
        K -->|"RTT_Result"| I
        I -->|"Returns_Results"| A
    end

    classDef client fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef server fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef module fill:#ffdab9,stroke:#000,stroke-width:1px;
    classDef config fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef concurrency fill:#dda0dd,stroke:#000,stroke-width:1px;

    click G "https://github.com/swyamsharma/calculatency/tree/master/Single_client/static"
    click B "https://github.com/swyamsharma/calculatency/blob/master/Single_client/static_server.py"
    click C "https://github.com/swyamsharma/calculatency/blob/master/Single_client/server.py"
    click D "https://github.com/swyamsharma/calculatency/blob/master/Single_client/websocket_ping.py"
    click E "https://github.com/swyamsharma/calculatency/blob/master/Single_client/tracer.py"
    click F "https://github.com/swyamsharma/calculatency/blob/master/Single_client/config.py"

    click M "https://github.com/swyamsharma/calculatency/tree/master/Multi_client/static"
    click H "https://github.com/swyamsharma/calculatency/blob/master/Multi_client/static_server.py"
    click I "https://github.com/swyamsharma/calculatency/blob/master/Multi_client/server.py"
    click J "https://github.com/swyamsharma/calculatency/blob/master/Multi_client/websocket_ping.py"
    click K "https://github.com/swyamsharma/calculatency/blob/master/Multi_client/tracer.py"
    click L "https://github.com/swyamsharma/calculatency/blob/master/Multi_client/config.py"
```
