Architecture

ffd is organized into separate packages, with each package responsible for a specific part of the downloader.

ffd/
├── .github/
│   └── workflows/
├── cmd/
├── internal/
│   ├── disk/
│   ├── engine/
│   ├── formatter/
│   ├── metadata/
│   ├── proxy/
│   ├── scheduler/
│   ├── tracker/
│   └── validator/
├── scripts/
├── main.go
├── go.mod
└── ...

main.go

The entry point of ffd. It starts the Cobra CLI by calling the root command.

cmd/

Contains the CLI commands and their configuration.

  • root.go — handles CLI arguments, download flags, multiple URLs, protocols, workers, chunks, retries, and output paths.
  • version.go — contains the build-time version used byffd --version.

internal/engine/

Responsible for the actual download process.

  • HTTP requests and range downloads
  • Workers and concurrent downloads
  • Writing downloaded data
  • Retries
  • HTTP client configuration

The engine receives the download plan from the scheduler and executes it.

internal/scheduler/

Responsible for deciding how the download should be performed.

  • Splitting files into chunks
  • Selecting the number of workers
  • Testing HTTP protocols
  • Selecting the preferred protocol
  • Creating download ranges

The scheduler produces the work that the engine executes.

URL
 │
 ▼
Scheduler
 │
 ├── Protocol
 ├── Workers
 └── Chunks
 │
 ▼
Engine
 │
 ▼
Downloaded File

internal/proxy/

Contains the ffd forward proxy.

  • Incoming proxy requests
  • HTTP requests
  • HTTPS CONNECT tunnels
  • Checking range support
  • Forwarding requests
  • Accelerated downloads when possible

scripts/

Contains installation scripts used by the updater.

  • install.sh — Linux and macOS installation.
  • install.ps1 — Windows PowerShell installation.

Build & Configuration

  • go.mod — Go module and dependencies.
  • go.sum — dependency checksums.
  • .goreleaser.yaml — build and release configuration.
  • .github/workflows/ — automated CI and release workflows.