# veggiedefender/torrent-client architecture

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

- Interactive diagram: https://gitdiagram.com/veggiedefender/torrent-client
- Repository: https://github.com/veggiedefender/torrent-client

## Overview

This Go CLI downloads a single-file torrent from a `.torrent` file to a destination path. Its main workflow parses torrent metadata, asks an HTTP tracker for peers, downloads and verifies pieces over BitTorrent peer connections, then writes the assembled bytes. The architecture separates tracker discovery, peer-protocol handling, and piece scheduling/assembly. The README also documents the product’s limits: no magnet links, multi-file torrents, or uploading. The graph follows the sampled call paths; unsampled behavior is not inferred.

Main entry points: [`p2p/p2p.go`](https://github.com/veggiedefender/torrent-client/blob/master/p2p/p2p.go) (Download coordinator), [`torrentfile/torrentfile.go`](https://github.com/veggiedefender/torrent-client/blob/master/torrentfile/torrentfile.go) (Torrent file), [`client/client.go`](https://github.com/veggiedefender/torrent-client/blob/master/client/client.go) (Peer connection), [`torrentfile/tracker.go`](https://github.com/veggiedefender/torrent-client/blob/master/torrentfile/tracker.go) (HTTP tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI workflow"]
  node_cli["CLI entry<br/>[main.go]"]
end

subgraph group_metadata["Torrent metadata"]
  node_torrentfile["Torrent file<br/>[torrentfile.go]"]
end

subgraph group_discovery["Peer discovery"]
  node_tracker["HTTP tracker<br/>[tracker.go]"]
  node_peerlist["Peer addresses<br/>[peers.go]"]
end

subgraph group_transfer["Peer transfer"]
  node_torrent["Download coordinator<br/>[p2p.go]"]
  node_client["Peer connection<br/>[client.go]"]
  node_handshake["Peer handshake<br/>[handshake.go]"]
  node_message["Wire messages<br/>[message.go]"]
  node_bitfield["Piece availability<br/>[bitfield.go]"]
end

node_user(("User"))
node_httptracker(("HTTP tracker service"))
node_peer(("BitTorrent peer"))
node_output["Downloaded file"]

node_user -->|"runs command"| node_cli
node_cli -->|"opens torrent"| node_torrentfile
node_torrentfile -->|"requests peers"| node_tracker
node_tracker -->|"queries"| node_httptracker
node_tracker -->|"decodes addresses"| node_peerlist
node_torrentfile -->|"starts download"| node_torrent
node_torrent -->|"requests pieces"| node_peer
node_torrent -->|"connects to peer"| node_client
node_client -->|"exchanges handshake"| node_handshake
node_client -->|"reads and sends"| node_message
node_client -->|"formats address"| node_peerlist
node_torrent -->|"checks availability"| node_bitfield
node_torrent -->|"parses peer data"| node_message
node_torrent -->|"assembles bytes"| node_output
node_torrentfile -->|"writes file"| node_output

click node_cli "https://github.com/veggiedefender/torrent-client/blob/master/main.go"
click node_torrentfile "https://github.com/veggiedefender/torrent-client/blob/master/torrentfile/torrentfile.go"
click node_tracker "https://github.com/veggiedefender/torrent-client/blob/master/torrentfile/tracker.go"
click node_peerlist "https://github.com/veggiedefender/torrent-client/blob/master/peers/peers.go"
click node_torrent "https://github.com/veggiedefender/torrent-client/blob/master/p2p/p2p.go"
click node_client "https://github.com/veggiedefender/torrent-client/blob/master/client/client.go"
click node_handshake "https://github.com/veggiedefender/torrent-client/blob/master/handshake/handshake.go"
click node_message "https://github.com/veggiedefender/torrent-client/blob/master/message/message.go"
click node_bitfield "https://github.com/veggiedefender/torrent-client/blob/master/bitfield/bitfield.go"

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_cli,node_user toneBlue
class node_torrentfile toneAmber
class node_tracker,node_peerlist toneMint
class node_torrent,node_client,node_handshake,node_message,node_bitfield toneRose
class node_httptracker,node_peer,node_output toneIndigo
```

## Components

### CLI workflow

- [CLI entry](https://github.com/veggiedefender/torrent-client/blob/master/main.go): `main.go`

### Torrent metadata

- [Torrent file](https://github.com/veggiedefender/torrent-client/blob/master/torrentfile/torrentfile.go): `torrentfile/torrentfile.go`

### Peer discovery

- [HTTP tracker](https://github.com/veggiedefender/torrent-client/blob/master/torrentfile/tracker.go): `torrentfile/tracker.go`
- [Peer addresses](https://github.com/veggiedefender/torrent-client/blob/master/peers/peers.go): `peers/peers.go`

### Peer transfer

- [Download coordinator](https://github.com/veggiedefender/torrent-client/blob/master/p2p/p2p.go): `p2p/p2p.go`
- [Peer connection](https://github.com/veggiedefender/torrent-client/blob/master/client/client.go): `client/client.go`
- [Peer handshake](https://github.com/veggiedefender/torrent-client/blob/master/handshake/handshake.go): `handshake/handshake.go`
- [Wire messages](https://github.com/veggiedefender/torrent-client/blob/master/message/message.go): `message/message.go`
- [Piece availability](https://github.com/veggiedefender/torrent-client/blob/master/bitfield/bitfield.go): `bitfield/bitfield.go`

### Other components

- **User**
- **HTTP tracker service**
- **BitTorrent peer**
- **Downloaded file**

## Connections

- User → CLI entry: runs command
- CLI entry → Torrent file: opens torrent
- Torrent file → HTTP tracker: requests peers
- HTTP tracker → HTTP tracker service: queries
- HTTP tracker → Peer addresses: decodes addresses
- Torrent file → Download coordinator: starts download
- Download coordinator → BitTorrent peer: requests pieces
- Download coordinator → Peer connection: connects to peer
- Peer connection → Peer handshake: exchanges handshake
- Peer connection → Wire messages: reads and sends
- Peer connection → Peer addresses: formats address
- Download coordinator → Piece availability: checks availability
- Download coordinator → Wire messages: parses peer data
- Download coordinator → Downloaded file: assembles bytes
- Torrent file → Downloaded file: writes file