# keroserene/snowflake architecture

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

- Interactive diagram: https://gitdiagram.com/keroserene/snowflake
- Repository: https://github.com/keroserene/snowflake

## Overview

##### Project Type and Purpose
- Snowflake is a pluggable transport system for Tor, built in Go.
- It consists of these main pieces:
a. Broker: a domain-fronted signaling server that matches Tor clients with volunteer proxies.
b. Client: a Tor pluggable transport client library and binary that initiates WebRTC connections via the Broker.
c. Proxy: volunteers’ Snowflake proxies (browser or standalone Go) that accept WebRTC connections, proxy traffic into Tor.
d. Server: Tor pluggable transport server code for turn-style relaying of WebRTC traffic to the Tor network.
e. Common libraries: shared components (AMP framing, rendezvous, NAT handling, metrics, etc.)
f. Probetest (optional): a containerized NAT probing service used in tests.

##### Main Components and Their Interactions
- Tor Client (pluggable-transport client)
- Reads torrc, loads the client binary.
- Connects over HTTPS (domain-fronted) to the Broker’s HTTP API to fetch proxy offers.
- Initiates WebRTC ICE negotiation with a volunteer Proxy.
- Once the DataChannel is open, tunnels Tor cell data over WebRTC.
- Broker
- Exposes HTTP(S) endpoints using domain fronting.
- Maintains in-memory peer lists (bridge-list.go).
- Handles AMP-framed requests (amp.go) and plain HTTP rendezvous (http.go).
- Exposes Prometheus metrics.
- Volunteer Proxy (browser or Go binary)
- Registers with Broker by sending “I’m available” messages.
- Listens for ICE offers from Tor clients via the Broker.
- On WebRTC DataChannel establishment, proxies traffic to a Tor relay or a built-in Tor client.
- Tor Pluggable-Transport Server
- Listens for incoming WebRTC DataChannels from proxies.
- Acts as the final hop into the Tor network.
- Common Libraries
- AMP framing, rendezvous protocols, NAT utilities, turbotunnel queueing, metrics, encapsulation.
- Shared by broker, client, proxy, and server.
- (Optional) Probetest
- Dockerized service to test NAT traversal, used only for development/test rigs.

##### Architectural Patterns and Design Principles
- Microservice-like separation: each role (broker, client, proxy, server) is a standalone Go module.
- Shared “common” code to avoid duplication of transport logic, framing, and utilities.
- Clean separation of signaling (Broker/HTTP+AMP) vs. data plane (WebRTC DataChannels).
- Instrumentation: Prometheus metrics in Broker and server.
- Testing: each component has unit tests under its folder; integration tests in “probetest.”

##### Detailed Elements
- Clear labels: e.g., “Broker HTTP API (domain-fronted), port 443”
- Protocol annotations: “WebRTC ICE Negotiation,” “DataChannel (DTLS/SCTP)”
- On metrics export endpoints (Broker → /metrics)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    DomainFront["Domain Fronting CDN"]:::external
    TorNetwork["Tor Network (Relays)"]:::external

    %% Broker Component
    subgraph "Broker Service"
        Broker["Broker HTTP API (domain-fronted), port 443"]:::signaling
    end

    %% Client and Proxy and Server
    subgraph "Snowflake Components"
        TorClient["Tor Pluggable-Transport Client"]:::datapath
        VolunteerProxy["Volunteer Proxy (Browser/Go)"]:::datapath
        TorPTServer["Tor PT Server (WebRTC Relay)"]:::serverlayer
    end

    %% Common Libraries
    CommonLib["Common Libraries"]:::common

    %% Optional Probetest
    Probetest["Probetest NAT Probe Service"]:::test

    %% Flows
    DomainFront -->|"HTTPS/AMP Signaling"| Broker
    Broker -->|"Proxy Offers (ICE candidates)"| TorClient
    TorClient -->|"WebRTC ICE Negotiation"| VolunteerProxy
    TorClient <-->|"DataChannel (DTLS/SCTP)"| VolunteerProxy
    VolunteerProxy -->|"Tor cells over WebRTC"| TorPTServer
    TorPTServer -->|"Tor cells"| TorNetwork

    %% Dependencies on common libraries
    CommonLib --> Broker
    CommonLib --> TorClient
    CommonLib --> VolunteerProxy
    CommonLib --> TorPTServer

    %% Probetest Connection
    Probetest -.->|"NAT probing tests"| CommonLib

    %% Click Events
    click Broker "https://github.com/keroserene/snowflake/blob/master/broker/broker.go"
    click TorClient "https://github.com/keroserene/snowflake/blob/master/client/snowflake.go"
    click VolunteerProxy "https://github.com/keroserene/snowflake/blob/master/proxy/main.go"
    click TorPTServer "https://github.com/keroserene/snowflake/blob/master/server/server.go"
    click CommonLib "https://github.com/keroserene/snowflake/tree/master/common/"
    click Probetest "https://github.com/keroserene/snowflake/blob/master/probetest/probetest.go"

    %% Styles
    classDef signaling fill:#cce5ff,stroke:#004085,color:#004085
    classDef datapath fill:#d4edda,stroke:#155724,color:#155724
    classDef serverlayer fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef common fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef test fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
