# thuan-hyp-1605/iroh architecture

> Architecture diagram of the GitHub repository thuan-hyp-1605/iroh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thuan-hyp-1605/iroh
- Repository: https://github.com/thuan-hyp-1605/iroh

## Overview

Iroh is a Rust workspace for authenticated peer-to-peer QUIC connectivity, with relay and DNS/Pkarr discovery services. An application binds an endpoint, dials a peer by identity and address information, and uses QUIC streams; iroh discovers addresses and prefers direct connectivity, using relays as a fallback and attempting hole punching. The workspace also includes signed DNS address publication/resolution and standalone relay and DNS servers. The README and sampled excerpts support these principal roles; some internal wiring is omitted where source excerpts do not establish it.

Main entry points: [`iroh/src/endpoint.rs`](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/endpoint.rs) (Endpoint API), [`iroh/src/address_lookup.rs`](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/address_lookup.rs) (Address Lookup), [`iroh/src/socket/transports.rs`](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/socket/transports.rs) (Transport Selection), [`iroh-relay/src/client.rs`](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/client.rs) (Relay Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connectivity["Peer Connectivity"]
  node_endpoint["Endpoint API<br/>[endpoint.rs]"]
  node_lookup["Address Lookup<br/>[address_lookup.rs]"]
  node_dns_lookup["DNS Lookup<br/>[dns.rs]"]
  node_pkarr_lookup["Pkarr Lookup<br/>[pkarr.rs]"]
  node_conn["QUIC Connection<br/>[connection.rs]"]
  node_socket["Transport Selection<br/>[transports.rs]"]
  node_direct["IP Transport<br/>[ip.rs]"]
  node_relay_transport["Relay Transport<br/>[relay.rs]"]
  node_net_report["Network Probes<br/>[net_report.rs]"]
end

subgraph group_relay["Relay Service"]
  node_relay_client["Relay Client<br/>[client.rs]"]
  node_relay_server["Relay Server<br/>[server.rs]"]
  node_relay_clients[("Client Registry<br/>[clients.rs]")]
  node_relay_actor["Client Forwarding<br/>[client.rs]"]
end

subgraph group_discovery["DNS Discovery"]
  node_dns_api["DNS Types<br/>[lib.rs]"]
  node_signed_packet["Signed Packets<br/>[pkarr.rs]"]
  node_dns_server["DNS Server<br/>[server.rs]"]
  node_dns_http["HTTP Services<br/>[http.rs]"]
  node_dns_handler["DNS Handler"]
  node_zone_store[("Zone Store<br/>[store.rs]")]
end

subgraph group_foundation["Shared Types"]
  node_base_types["Identity Types<br/>[lib.rs]"]
end

node_app(("Application"))
node_peer(("Remote Peer"))
node_relay_service{{"Relay Service"}}
node_dns_service{{"DNS Service"}}

node_app -->|"binds and dials"| node_endpoint
node_endpoint -->|"resolves addresses"| node_lookup
node_lookup -->|"uses DNS"| node_dns_lookup
node_lookup -->|"uses Pkarr"| node_pkarr_lookup
node_endpoint -->|"establishes QUIC"| node_conn
node_conn -->|"selects transport"| node_socket
node_socket -->|"tries direct"| node_direct
node_socket -->|"falls back"| node_relay_transport
node_endpoint -->|"measures paths"| node_net_report
node_relay_transport -->|"sends relay traffic"| node_relay_client
node_relay_client -->|"connects to"| node_relay_service
node_peer -->|"sends encrypted traffic"| node_relay_service
node_relay_service -->|"forwards traffic"| node_peer
node_relay_server -->|"registers clients"| node_relay_clients
node_relay_actor -->|"forwards packets"| node_relay_clients
node_dns_lookup -->|"queries records"| node_dns_service
node_pkarr_lookup -->|"resolves records"| node_dns_service
node_dns_server -->|"serves DNS"| node_dns_handler
node_dns_server -->|"starts HTTP services"| node_dns_http
node_dns_handler -->|"resolves zones"| node_zone_store
node_dns_api -->|"defines packet format"| node_signed_packet
node_zone_store -->|"stores packets"| node_signed_packet
node_dns_service -->|"hosts lookup service"| node_dns_server
node_endpoint -->|"uses identities"| node_base_types
node_relay_client -->|"uses relay identity types"| node_base_types

click node_endpoint "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/endpoint.rs"
click node_lookup "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/address_lookup.rs"
click node_dns_lookup "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/address_lookup/dns.rs"
click node_pkarr_lookup "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/address_lookup/pkarr.rs"
click node_conn "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/endpoint/connection.rs"
click node_socket "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/socket/transports.rs"
click node_direct "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/socket/transports/ip.rs"
click node_relay_transport "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/socket/transports/relay.rs"
click node_net_report "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/net_report.rs"
click node_relay_client "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/client.rs"
click node_relay_server "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/server.rs"
click node_relay_clients "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/server/clients.rs"
click node_relay_actor "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/server/client.rs"
click node_dns_api "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns/src/lib.rs"
click node_signed_packet "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns/src/pkarr.rs"
click node_dns_server "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/server.rs"
click node_dns_http "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/http.rs"
click node_dns_handler "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/dns/node_zone_handler.rs"
click node_zone_store "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/store.rs"
click node_base_types "https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-base/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_endpoint,node_lookup,node_dns_lookup,node_pkarr_lookup,node_conn,node_socket,node_direct,node_relay_transport,node_net_report toneBlue
class node_relay_client,node_relay_server,node_relay_clients,node_relay_actor toneAmber
class node_dns_api,node_signed_packet,node_dns_server,node_dns_http,node_dns_handler,node_zone_store toneMint
class node_base_types toneRose
class node_app,node_peer,node_relay_service,node_dns_service toneIndigo
```

## Components

### Peer Connectivity

- [Endpoint API](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/endpoint.rs): `iroh/src/endpoint.rs`
- [Address Lookup](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/address_lookup.rs): `iroh/src/address_lookup.rs`
- [DNS Lookup](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/address_lookup/dns.rs): `iroh/src/address_lookup/dns.rs`
- [Pkarr Lookup](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/address_lookup/pkarr.rs): `iroh/src/address_lookup/pkarr.rs`
- [QUIC Connection](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/endpoint/connection.rs): `iroh/src/endpoint/connection.rs`
- [Transport Selection](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/socket/transports.rs): `iroh/src/socket/transports.rs`
- [IP Transport](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/socket/transports/ip.rs): `iroh/src/socket/transports/ip.rs`
- [Relay Transport](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/socket/transports/relay.rs): `iroh/src/socket/transports/relay.rs`
- [Network Probes](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh/src/net_report.rs): `iroh/src/net_report.rs`

### Relay Service

- [Relay Client](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/client.rs): `iroh-relay/src/client.rs`
- [Relay Server](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/server.rs): `iroh-relay/src/server.rs`
- [Client Registry](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/server/clients.rs): `iroh-relay/src/server/clients.rs`
- [Client Forwarding](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-relay/src/server/client.rs): `iroh-relay/src/server/client.rs`

### DNS Discovery

- [DNS Types](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns/src/lib.rs): `iroh-dns/src/lib.rs`
- [Signed Packets](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns/src/pkarr.rs): `iroh-dns/src/pkarr.rs`
- [DNS Server](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/server.rs): `iroh-dns-server/src/server.rs`
- [HTTP Services](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/http.rs): `iroh-dns-server/src/http.rs`
- [DNS Handler](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/dns/node_zone_handler.rs): `iroh-dns-server/src/dns/node_zone_handler.rs`
- [Zone Store](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-dns-server/src/store.rs): `iroh-dns-server/src/store.rs`

### Shared Types

- [Identity Types](https://github.com/thuan-hyp-1605/iroh/blob/main/iroh-base/src/lib.rs): `iroh-base/src/lib.rs`

### Other components

- **Application**
- **Remote Peer**
- **Relay Service**
- **DNS Service**

## Connections

- Application → Endpoint API: binds and dials
- Endpoint API → Address Lookup: resolves addresses
- Address Lookup → DNS Lookup: uses DNS
- Address Lookup → Pkarr Lookup: uses Pkarr
- Endpoint API → QUIC Connection: establishes QUIC
- QUIC Connection → Transport Selection: selects transport
- Transport Selection → IP Transport: tries direct
- Transport Selection → Relay Transport: falls back
- Endpoint API → Network Probes: measures paths
- Relay Transport → Relay Client: sends relay traffic
- Relay Client → Relay Service: connects to
- Remote Peer → Relay Service: sends encrypted traffic
- Relay Service → Remote Peer: forwards traffic
- Relay Server → Client Registry: registers clients
- Client Forwarding → Client Registry: forwards packets
- DNS Lookup → DNS Service: queries records
- Pkarr Lookup → DNS Service: resolves records
- DNS Server → DNS Handler: serves DNS
- DNS Server → HTTP Services: starts HTTP services
- DNS Handler → Zone Store: resolves zones
- DNS Types → Signed Packets: defines packet format
- Zone Store → Signed Packets: stores packets
- DNS Service → DNS Server: hosts lookup service
- Endpoint API → Identity Types: uses identities
- Relay Client → Identity Types: uses relay identity types