# mpetazzoni/ttorrent architecture

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

- Interactive diagram: https://gitdiagram.com/mpetazzoni/ttorrent
- Repository: https://github.com/mpetazzoni/ttorrent
- Video tour (about a minute): https://gitdiagram.com/mpetazzoni/ttorrent/video

## Overview

#### Purpose and entry points
Ttorrent is a Maven multi-module, pure-Java BitTorrent implementation usable as an embedded client, embedded tracker, or torrent-metainfo tool. Standalone CLI entry points are:
- `cli/src/main/java/com/turn/ttorrent/cli/ClientMain.java`
- `cli/src/main/java/com/turn/ttorrent/cli/TrackerMain.java`
- `cli/src/main/java/com/turn/ttorrent/cli/TorrentMain.java`

The main library APIs are `SimpleClient` for download/seeding and `Tracker` for serving announces.

#### Module boundaries
`common` owns protocol-neutral torrent metadata, peer identity/value types, and BitTorrent/tracker wire models. `bencoding` is the serialization substrate. `network` supplies reusable nonblocking channel management. `ttorrent-client` composes these into a peer client; `ttorrent-tracker` implements tracker state and HTTP request handling.
- `common/src/main/java/com/turn/ttorrent/common/TorrentParser.java`
- `bencoding/src/main/java/com/turn/ttorrent/bcodec/BDecoder.java`
- `network/src/main/java/com/turn/ttorrent/network/ConnectionManager.java`

#### Metainfo creation and parsing
Torrent creation reads source files, divides them into pieces, calculates hashes (single- or multi-threaded), builds metadata, and bencodes it. Parsing performs the inverse to expose immutable torrent metadata for clients and trackers.
- `common/src/main/java/com/turn/ttorrent/common/TorrentCreator.java`
- `common/src/main/java/com/turn/ttorrent/common/creation/MetadataBuilder.java`
- `common/src/main/java/com/turn/ttorrent/common/TorrentSerializer.java`

#### Client orchestration and lifecycle
`SimpleClient` is the embedding façade. It loads torrent metadata, creates/manages active torrents, dispatches lifecycle events, and coordinates tracker discovery, peer sessions, storage, and completion/seeding state.
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/SimpleClient.java`
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/TorrentManagerImpl.java`
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/SharedTorrent.java`

#### Tracker discovery and peer protocol
The client announces torrent status to HTTP or UDP tracker endpoints, consumes peer lists, then opens peer connections. Peer sessions exchange BitTorrent handshakes and messages; connection admission and session-state listeners form a boundary between generic NIO transport and torrent semantics.
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/announce/TrackerClientFactoryImpl.java`
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/network/HandshakeReceiver.java`
- `common/src/main/java/com/turn/ttorrent/common/protocol/PeerMessage.java`

#### Piece transfer, selection, and disk persistence
Peer messages drive piece availability and requests. Request strategies choose interesting pieces and end-game behavior; received blocks are assembled, validated against torrent hashes, and persisted to single-file or multi-file storage. Storage is a client-local filesystem boundary.
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/strategy/RequestStrategy.java`
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/Piece.java`
- `ttorrent-client/src/main/java/com/turn/ttorrent/client/storage/FileCollectionStorage.java`

#### Tracker service
The tracker accepts announce requests, resolves each info hash to a tracked torrent, records peers, expires stale peers, and returns compact peer lists. It can optionally admit previously unknown torrents. The service is stateful in process; no persistent datastore is represented in this tree.
- `ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/Tracker.java`
- `ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TorrentsRepository.java`
- `ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TrackerRequestProcessor.java`

#### Runtime and external interfaces
Runtime is Java with Maven reactor modules. External interfaces are local filesystem reads/writes, TCP peer connections through Java NIO selectors, and tracker HTTP/UDP protocols. The client supports UDP tracker announces; tracker protocol message models cover HTTP and UDP, while tracker service implementation is centered on request processing.
- `network/src/main/java/com/turn/ttorrent/network/ConnectionWorker.java`
- `common/src/main/java/com/turn/ttorrent/common/protocol/http/HTTPAnnounceRequestMessage.java`
- `common/src/main/java/com/turn/ttorrent/common/protocol/udp/UDPAnnounceRequestMessage.java`

Main entry points: [`ttorrent-client/src/main/java/com/turn/ttorrent/client/announce/TrackerClientFactoryImpl.java`](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/announce/TrackerClientFactoryImpl.java) (Tracker discovery), [`ttorrent-client/src/main/java/com/turn/ttorrent/client/network/HandshakeReceiver.java`](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/network/HandshakeReceiver.java) (Peer sessions), [`ttorrent-client/src/main/java/com/turn/ttorrent/client/SimpleClient.java`](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/SimpleClient.java) (SimpleClient), [`ttorrent-client/src/main/java/com/turn/ttorrent/client/Piece.java`](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/Piece.java) (Piece transfer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI entry points"]
  node_client_cli["Client CLI<br/>Java main<br/>[ClientMain.java]"]
  node_tracker_cli["Tracker CLI<br/>Java main<br/>[TrackerMain.java]"]
  node_torrent_cli["Torrent CLI<br/>Java main<br/>[TorrentMain.java]"]
end

subgraph group_shared["Shared modules"]
  node_bdecoder["Bencoding codec<br/>serialization<br/>[BDecoder.java]"]
  node_metainfo["Torrent metadata<br/>common model<br/>[TorrentParser.java]"]
  node_creation["Metainfo creation<br/>creation pipeline"]
  node_serializer["Torrent serializer<br/>serialization"]
  node_peer_messages["Peer wire messages<br/>protocol model<br/>[PeerMessage.java]"]
  node_tracker_messages["Tracker wire messages<br/>protocol model"]
  node_nio_transport["NIO transport<br/>network runtime"]
end

subgraph group_client["Peer client"]
  node_simple_client["SimpleClient<br/>embedding facade<br/>[SimpleClient.java]"]
  node_torrent_manager["Torrent manager<br/>lifecycle manager"]
  node_shared_torrent["Active torrent<br/>torrent state<br/>[SharedTorrent.java]"]
  node_tracker_client["Tracker discovery<br/>announce client"]
  node_peer_sessions["Peer sessions<br/>peer protocol"]
  node_piece_transfer["Piece transfer<br/>piece engine<br/>[Piece.java]"]
  node_storage[("File storage<br/>filesystem boundary")]
end

subgraph group_tracker["Tracker service"]
  node_tracker_service["Tracker<br/>[Tracker.java]"]
  node_announce_processor["Announce processor<br/>HTTP handler"]
  node_torrent_repository[("Tracked torrents<br/>in-memory state")]
end

node_client_cli -->|"runs"| node_simple_client
node_tracker_cli -->|"runs"| node_tracker_service
node_torrent_cli -->|"creates"| node_creation
node_creation -->|"builds metainfo"| node_serializer
node_serializer -.->|"bencoded format"| node_bdecoder
node_bdecoder -->|"parses into"| node_metainfo
node_simple_client -->|"manages"| node_torrent_manager
node_torrent_manager -->|"owns active"| node_shared_torrent
node_simple_client -->|"loads"| node_metainfo
node_shared_torrent -->|"announces status"| node_tracker_client
node_tracker_client -->|"uses HTTP/UDP"| node_tracker_messages
node_tracker_client -.->|"announce protocol"| node_tracker_service
node_tracker_client -->|"supplies peers"| node_peer_sessions
node_peer_sessions -->|"uses channels"| node_nio_transport
node_peer_sessions -->|"exchanges"| node_peer_messages
node_peer_sessions -->|"drives requests"| node_piece_transfer
node_piece_transfer -->|"validates hashes"| node_shared_torrent
node_piece_transfer -->|"persists blocks"| node_storage
node_tracker_service -->|"routes announces"| node_announce_processor
node_announce_processor -->|"parses and responds"| node_tracker_messages
node_announce_processor -->|"updates peers"| node_torrent_repository

click node_client_cli "https://github.com/mpetazzoni/ttorrent/blob/master/cli/src/main/java/com/turn/ttorrent/cli/ClientMain.java"
click node_tracker_cli "https://github.com/mpetazzoni/ttorrent/blob/master/cli/src/main/java/com/turn/ttorrent/cli/TrackerMain.java"
click node_torrent_cli "https://github.com/mpetazzoni/ttorrent/blob/master/cli/src/main/java/com/turn/ttorrent/cli/TorrentMain.java"
click node_bdecoder "https://github.com/mpetazzoni/ttorrent/blob/master/bencoding/src/main/java/com/turn/ttorrent/bcodec/BDecoder.java"
click node_metainfo "https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/TorrentParser.java"
click node_creation "https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/creation/MetadataBuilder.java"
click node_serializer "https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/TorrentSerializer.java"
click node_peer_messages "https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/protocol/PeerMessage.java"
click node_tracker_messages "https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/protocol/http/HTTPAnnounceRequestMessage.java"
click node_nio_transport "https://github.com/mpetazzoni/ttorrent/blob/master/network/src/main/java/com/turn/ttorrent/network/ConnectionManager.java"
click node_simple_client "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/SimpleClient.java"
click node_torrent_manager "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/TorrentManagerImpl.java"
click node_shared_torrent "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/SharedTorrent.java"
click node_tracker_client "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/announce/TrackerClientFactoryImpl.java"
click node_peer_sessions "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/network/HandshakeReceiver.java"
click node_piece_transfer "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/Piece.java"
click node_storage "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/storage/FileCollectionStorage.java"
click node_tracker_service "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/Tracker.java"
click node_announce_processor "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TrackerRequestProcessor.java"
click node_torrent_repository "https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TorrentsRepository.java"

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_client_cli,node_tracker_cli,node_torrent_cli toneBlue
class node_bdecoder,node_metainfo,node_creation,node_serializer,node_peer_messages,node_tracker_messages,node_nio_transport toneAmber
class node_simple_client,node_torrent_manager,node_shared_torrent,node_tracker_client,node_peer_sessions,node_piece_transfer,node_storage toneMint
class node_tracker_service,node_announce_processor,node_torrent_repository toneRose
```

## Components

### CLI entry points

- [Client CLI](https://github.com/mpetazzoni/ttorrent/blob/master/cli/src/main/java/com/turn/ttorrent/cli/ClientMain.java): Java main · `cli/src/main/java/com/turn/ttorrent/cli/ClientMain.java`
- [Tracker CLI](https://github.com/mpetazzoni/ttorrent/blob/master/cli/src/main/java/com/turn/ttorrent/cli/TrackerMain.java): Java main · `cli/src/main/java/com/turn/ttorrent/cli/TrackerMain.java`
- [Torrent CLI](https://github.com/mpetazzoni/ttorrent/blob/master/cli/src/main/java/com/turn/ttorrent/cli/TorrentMain.java): Java main · `cli/src/main/java/com/turn/ttorrent/cli/TorrentMain.java`

### Shared modules

- [Bencoding codec](https://github.com/mpetazzoni/ttorrent/blob/master/bencoding/src/main/java/com/turn/ttorrent/bcodec/BDecoder.java): serialization · `bencoding/src/main/java/com/turn/ttorrent/bcodec/BDecoder.java`
- [Torrent metadata](https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/TorrentParser.java): common model · Immutable metainfo and protocol-neutral value types. · `common/src/main/java/com/turn/ttorrent/common/TorrentParser.java`
- [Metainfo creation](https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/creation/MetadataBuilder.java): creation pipeline · Builds piece hashes and torrent metadata from source files. · `common/src/main/java/com/turn/ttorrent/common/creation/MetadataBuilder.java`
- [Torrent serializer](https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/TorrentSerializer.java): serialization · `common/src/main/java/com/turn/ttorrent/common/TorrentSerializer.java`
- [Peer wire messages](https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/protocol/PeerMessage.java): protocol model · `common/src/main/java/com/turn/ttorrent/common/protocol/PeerMessage.java`
- [Tracker wire messages](https://github.com/mpetazzoni/ttorrent/blob/master/common/src/main/java/com/turn/ttorrent/common/protocol/http/HTTPAnnounceRequestMessage.java): protocol model · HTTP and UDP announce models. · `common/src/main/java/com/turn/ttorrent/common/protocol/http/HTTPAnnounceRequestMessage.java`
- [NIO transport](https://github.com/mpetazzoni/ttorrent/blob/master/network/src/main/java/com/turn/ttorrent/network/ConnectionManager.java): network runtime · Reusable nonblocking channel management. · `network/src/main/java/com/turn/ttorrent/network/ConnectionManager.java`

### Peer client

- [SimpleClient](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/SimpleClient.java): embedding facade · Coordinates torrent lifecycle, sessions, discovery, and seeding. · `ttorrent-client/src/main/java/com/turn/ttorrent/client/SimpleClient.java`
- [Torrent manager](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/TorrentManagerImpl.java): lifecycle manager · `ttorrent-client/src/main/java/com/turn/ttorrent/client/TorrentManagerImpl.java`
- [Active torrent](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/SharedTorrent.java): torrent state · Tracks transfer, completion, and seeding state. · `ttorrent-client/src/main/java/com/turn/ttorrent/client/SharedTorrent.java`
- [Tracker discovery](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/announce/TrackerClientFactoryImpl.java): announce client · Announces over HTTP or UDP and consumes peers. · `ttorrent-client/src/main/java/com/turn/ttorrent/client/announce/TrackerClientFactoryImpl.java`
- [Peer sessions](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/network/HandshakeReceiver.java): peer protocol · Handles handshake admission and BitTorrent message exchange. · `ttorrent-client/src/main/java/com/turn/ttorrent/client/network/HandshakeReceiver.java`
- [Piece transfer](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/Piece.java): piece engine · Selects, assembles, and hash-validates received blocks. · `ttorrent-client/src/main/java/com/turn/ttorrent/client/Piece.java`
- [File storage](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-client/src/main/java/com/turn/ttorrent/client/storage/FileCollectionStorage.java): filesystem boundary · Persists single-file and multi-file torrent content. · `ttorrent-client/src/main/java/com/turn/ttorrent/client/storage/FileCollectionStorage.java`

### Tracker service

- [Tracker](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/Tracker.java): tracker API · Serves announces and optionally admits unknown torrents. · `ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/Tracker.java`
- [Announce processor](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TrackerRequestProcessor.java): HTTP handler · Records announcing peers and returns compact peer lists. · `ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TrackerRequestProcessor.java`
- [Tracked torrents](https://github.com/mpetazzoni/ttorrent/blob/master/ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TorrentsRepository.java): in-memory state · Maps info hashes to peer populations and expires stale peers. · `ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TorrentsRepository.java`

## Connections

- Client CLI → SimpleClient: runs
- Tracker CLI → Tracker: runs
- Torrent CLI → Metainfo creation: creates
- Metainfo creation → Torrent serializer: builds metainfo
- Torrent serializer → Bencoding codec: bencoded format
- Bencoding codec → Torrent metadata: parses into
- SimpleClient → Torrent manager: manages
- Torrent manager → Active torrent: owns active
- SimpleClient → Torrent metadata: loads
- Active torrent → Tracker discovery: announces status
- Tracker discovery → Tracker wire messages: uses HTTP/UDP
- Tracker discovery → Tracker: announce protocol
- Tracker discovery → Peer sessions: supplies peers
- Peer sessions → NIO transport: uses channels
- Peer sessions → Peer wire messages: exchanges
- Peer sessions → Piece transfer: drives requests
- Piece transfer → Active torrent: validates hashes
- Piece transfer → File storage: persists blocks
- Tracker → Announce processor: routes announces
- Announce processor → Tracker wire messages: parses and responds
- Announce processor → Tracked torrents: updates peers