# dioptra-io/voyage architecture

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

- Interactive diagram: https://gitdiagram.com/dioptra-io/voyage
- Repository: https://github.com/dioptra-io/voyage

## Overview

##### High-Level Components
- User Interface (CLI)
- Configuration & Builder
- Probing Engine
- Sender (crafts and transmits packets via libpcap)
- Receiver (captures replies via libpcap)
- Algorithms
- Diamond Miner (probe scheduling, ‘sequential_mapper’, ‘probe_generator’, statistical estimation)
- Classic Traceroute (fallback/simple path tracing)
- Data Aggregation & Link Discovery
- Output Formatter
- Atlas, Iris, flat, scamper, internal, quiet
- Logging & Observability
- External Dependencies
- libpcap
- stirling_numbers crate (for estimator)
- env_logger

##### Relationships & Data Flows
- CLI parses arguments → populates a `PantraceBuilder` / config struct in `pantrace_builder.rs`
- Builder → instantiates Probing Engine
- Sender and Receiver run concurrently (threads/tasks)
- Sender uses `probe.rs` to generate packets
- Receiver in `receiver.rs` uses libpcap to listen for ICMP/UDP replies
- Probing Engine ↔ Algorithm modules
- Diamond Miner sub‐modules (in `src/algorithms/diamond_miner/*`) coordinate rounds, TTL ranges, confidence estimation
- Utilities (`utils.rs`, `stopping_point.rs`) support convergence checks
- Classic traceroute path logic in `classic_traceroute.rs`
- Captured probe results flow into link analysis (`links.rs`), building a graph of hops/interfaces
- Aggregated data passed to Output Formatter (in `src/lib.rs` or `main.rs`), which serializes into the chosen format
- Logging calls interwoven across modules via `env_logger`

##### Architectural Patterns & Principles
- Builder Pattern: `PantraceBuilder` centralizes configuration
- Modularization: Separate crates/modules for algorithms, utils, link handling, I/O
- Pipeline/Producer-Consumer: Sender and Receiver communicate via channels or shared structs
- Pluggable Output Formats: Strategy pattern for serialization

##### Technologies & Frameworks
- Rust/Cargo crate layout
- libpcap FFI binding (via `pantrace` or similar)
- `stirling_numbers` crate for statistical computations
- `env_logger` for log levels

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    CLI["CLI Parser"]:::ioext -->|"parses args"| Builder["PantraceBuilder"]:::utilities

    %% Core Runtime Services
    subgraph "Core Services"
        direction TB
        Sender["Probe Sender"]:::coreruntime
        Receiver["Probe Receiver"]:::coreruntime
    end
    Builder -->|instantiates| Sender
    Builder -->|instantiates| Receiver

    %% Algorithms Layer
    subgraph "Algorithms"
        direction TB
        subgraph "Diamond Miner"
            direction TB
            DMCore["Diamond Miner Core"]:::algorithms
            ProbeGen["Probe Generator"]:::algorithms
            SeqMap["Sequential Mapper"]:::algorithms
            DMTypes["Types & Data Structures"]:::algorithms
            DMCore --> ProbeGen
            DMCore --> SeqMap
            DMCore --> DMTypes
        end
        Classic["Classic Traceroute"]:::algorithms
    end
    Sender -->|"sends packets"| DMCore
    Receiver -->|"provides replies"| DMCore
    DMCore --> Classic
    Classic --> DMCore

    %% Utilities & Logging
    subgraph "Utilities & Logging"
        direction TB
        Utils["Algorithm Utilities"]:::utilities
        StopPoint["Stopping Point Utility"]:::utilities
        CoreTypes["Core Library Types & Traits"]:::utilities
        Logger["Logging & Observability"]:::utilities
    end
    DMCore --> Utils
    Utils --> StopPoint
    Builder --> CoreTypes
    CLI --> Logger
    Sender --> Logger
    Receiver --> Logger
    DMCore --> Logger
    Classic --> Logger

    %% Data Aggregation & Link Discovery
    LinkAgg["Data Aggregation & Link Discovery"]:::coreruntime
    DMCore --> LinkAgg
    Classic --> LinkAgg

    %% Output Formatter
    Output["Output Formatter"]:::ioext
    LinkAgg --> Output

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        LibPcap["libpcap FFI"]:::ioext
        Stirling["stirling_numbers crate"]:::algorithms
        EnvLog["env_logger"]:::utilities
    end
    Sender --> LibPcap
    Receiver --> LibPcap
    DMCore --> Stirling
    Logger --> EnvLog

    %% Click Events
    click CLI "https://github.com/dioptra-io/voyage/blob/main/src/main.rs"
    click Builder "https://github.com/dioptra-io/voyage/blob/main/src/pantrace_builder.rs"
    click Sender "https://github.com/dioptra-io/voyage/blob/main/src/probe.rs"
    click Receiver "https://github.com/dioptra-io/voyage/blob/main/src/receiver.rs"
    click DMCore "https://github.com/dioptra-io/voyage/blob/main/src/algorithms/diamond_miner.rs"
    click ProbeGen "https://github.com/dioptra-io/voyage/blob/main/src/algorithms/diamond_miner/probe_generator.rs"
    click SeqMap "https://github.com/dioptra-io/voyage/blob/main/src/algorithms/diamond_miner/sequential_mapper.rs"
    click DMTypes "https://github.com/dioptra-io/voyage/blob/main/src/algorithms/diamond_miner/types.rs"
    click Classic "https://github.com/dioptra-io/voyage/blob/main/src/classic_traceroute.rs"
    click Utils "https://github.com/dioptra-io/voyage/blob/main/src/algorithms/utils.rs"
    click StopPoint "https://github.com/dioptra-io/voyage/blob/main/src/algorithms/utils/stopping_point.rs"
    click LinkAgg "https://github.com/dioptra-io/voyage/blob/main/src/links.rs"
    click Output "https://github.com/dioptra-io/voyage/blob/main/src/lib.rs"
    click CoreTypes "https://github.com/dioptra-io/voyage/blob/main/src/types.rs"
    click Logger "https://github.com/dioptra-io/voyage/blob/main/src/main.rs"

    %% Styles
    classDef coreruntime fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef algorithms fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ioext fill:#FFA500,stroke:#000,stroke-width:1px
    classDef utilities fill:#D3D3D3,stroke:#000,stroke-width:1px
```
