# torproject/chutney architecture

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

- Interactive diagram: https://gitdiagram.com/torproject/chutney
- Repository: https://github.com/torproject/chutney

## Overview

##### Project Type and Purpose
- Chutney is a command‐line orchestration tool (an open-source Python “framework”)
for configuring, launching, monitoring, and verifying *test* Tor networks.
- It is not a web or mobile app; it’s a CLI tool that drives Tor binaries and test scripts.

##### File Structure
Top‐level components:
- `chutney` (CLI entry point)
- `lib/chutney/…` (core Python modules: Debug, Host, Templating, TorNet, Traffic, Util)
- `networks/` (network‐flavor configuration files)
- `torrc_templates/` (Tor configuration templates)
- `tools/` (bash scripts to bootstrap, test, diagnose)
- `scripts/chutney_tests/` (Python test scripts for custom verify logic)
- `net/` (runtime working directory where Tor instances and logs live)
- `tests/` (shell‐based smoke/unit tests)

##### README for Insights
- Chutney commands (`configure`, `start`, `status`, `verify`, etc.) map to core modules.
- External dependencies: Python 3, Tor (`tor`, `tor-gencert`).
- Data flow:
–  read a network config under `networks/`
–  feed into Templating to produce per‐node torrc files
–  spawn Tor processes via TorNet
–  run connection tests via Traffic and test scripts
–  collect logs, reports in `net/`

##### Main Components & Relationships
a. Components:
1. CLI Front End (`chutney` entry script)
2. Core Engine (`lib/chutney/*` modules):
–  Templating: renders `torrc_templates` + `networks/*` → per-node torrc
–  TorNet: manages lifecycle (spawn, stop, hup) of Tor processes
–  Host & Util: filesystem, environment, process abstractions
–  Debug & Traffic: logging, bootstrap monitoring, test traffic generation
3. Network Definitions (`networks/`)
4. Tor‐configuration Templates (`torrc_templates/`)
5. Working Directory (`net/`): generated torrc, data dirs, logs
6. External Binaries: `tor`, `tor-gencert`
7. Test Harness:
–  Built-in verify logic calls Traffic and Debug
–  Custom test scripts (`scripts/chutney_tests/`) that override/extend verify
8. Orchestrator Scripts (`tools/test-network.sh`): glue that invokes `chutney` and CI flags

b. Interactions:
- User invokes `chutney <command>` or `tools/test-network.sh`.
- CLI Front End dispatches to Core Engine.
- Core Engine reads network definition and template, writes torrc into `net/`.
- TorNet module launches multiple Tor processes (`tor` binary) using those torrcs.
- Tor processes form an isolated test network bound to localhost (v4/v6).
- After launch, Debug & Traffic modules (or custom scripts) connect through the network, measure bootstrap status and bandwidth.
- Results and logs are written under `net/`.
- Test harness or scripts analyze outputs and report pass/fail.

c. Architectural Patterns and Principles:
–  Modular CLI ⇒ clear separation between entry point and core logic
–  Plugin-style test scripts: custom behavior via `scripts/chutney_tests/`
–  Templating engine decouples static network definitions from generated configs
–  Process manager abstraction around external Tor binaries
–  Configuration-as-code: network flavors in `networks/` as inputs

d. Key Technologies & Libraries:
–  Python 3 standard libs (subprocess, os, tempfile)
–  Jinja-style or custom templating (Templating.py)
–  Shell scripts (bash) for higher‐level orchestration
–  External Tor binaries (`tor`, `tor-gencert`)

[ ] Show Templating output (per-node torrc files in `net/`) feeding into TorNet

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level entry points
    CLI["chutney CLI"]:::scripts
    Script["tools/test-network.sh"]:::scripts

    %% Configuration inputs
    subgraph "Config Inputs"
        Networks["networks/"]:::config
        Templates["torrc_templates/"]:::config
    end

    %% Core engine grouping
    subgraph "Core Engine"
        CoreEngine["Core Engine"]:::pythoncore
        Debug["Debug Module"]:::pythoncore
        Host["Host Abstraction"]:::pythoncore
        Templating["Templating Engine"]:::pythoncore
        TorNet["TorNet Manager"]:::pythoncore
        Traffic["Traffic & Testing"]:::pythoncore
        Util["Utilities"]:::pythoncore
    end

    %% Runtime directory
    NetDir["net/ (runtime working dir)"]:::config

    %% External binaries
    TorBin["tor & tor-gencert"]:::external

    %% Tor processes
    subgraph "Tor Processes"
        Node1["Node 1"]
        Node2["Node 2"]
        Node3["Node 3"]
    end

    %% Test scripts
    subgraph "Tests"
        BuiltIn["tests/*.sh"]:::scripts
        Custom["scripts/chutney_tests/verify.py"]:::scripts
    end

    %% Connections
    CLI -->|"invoke"| CoreEngine
    Script -->|"invoke"| CoreEngine

    CoreEngine --> Debug
    CoreEngine --> Host
    CoreEngine --> Templating
    CoreEngine --> TorNet
    CoreEngine --> Traffic
    CoreEngine --> Util

    Networks -->|"defines network"| Templating
    Templates -->|"provides templates"| Templating
    Templating -->|"renders torrc files"| NetDir

    NetDir -->|"reads torrcs"| TorNet
    TorNet -->|"spawns processes"| TorBin
    TorBin -->|"runs binaries"| Node1
    TorBin -->|"runs binaries"| Node2
    TorBin -->|"runs binaries"| Node3

    Node1 -->|"bootstrap data"| Traffic
    Node2 -->|"bootstrap data"| Traffic
    Node3 -->|"bootstrap data"| Traffic

    Traffic -->|"writes logs"| NetDir
    Debug -->|"logs and monitors"| NetDir

    BuiltIn -->|"executes standard tests"| Traffic
    Custom -.->|"overrides verify logic"| Traffic
    Custom -.->|"overrides debug hooks"| Debug

    %% Click events
    click CLI "https://github.com/torproject/chutney/tree/main/chutney"
    click Script "https://github.com/torproject/chutney/blob/main/tools/test-network.sh"
    click Debug "https://github.com/torproject/chutney/blob/main/lib/chutney/Debug.py"
    click Host "https://github.com/torproject/chutney/blob/main/lib/chutney/Host.py"
    click Templating "https://github.com/torproject/chutney/blob/main/lib/chutney/Templating.py"
    click TorNet "https://github.com/torproject/chutney/blob/main/lib/chutney/TorNet.py"
    click Traffic "https://github.com/torproject/chutney/blob/main/lib/chutney/Traffic.py"
    click Util "https://github.com/torproject/chutney/blob/main/lib/chutney/Util.py"
    click Networks "https://github.com/torproject/chutney/tree/main/networks/"
    click Templates "https://github.com/torproject/chutney/tree/main/torrc_templates/"
    click NetDir "https://github.com/torproject/chutney/tree/main/net/"
    click Custom "https://github.com/torproject/chutney/blob/main/scripts/chutney_tests/verify.py"
    click BuiltIn "https://github.com/torproject/chutney/blob/main/tests/unit-tests.sh"

    %% Styles
    classDef pythoncore fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef config fill:#E2F0D9,stroke:#333,stroke-width:1px
    classDef external fill:#FFE5CC,stroke:#333,stroke-width:1px
    classDef scripts fill:#FFF2CC,stroke:#333,stroke-width:1px
```
