update readme

Author: cenkalti

README.md

@@ -7,13 +7,17 @@ rain
 
 BitTorrent client and library in Go. Running in production at [put.io][putio-link] since 2019. Processing thousands of torrents every day.
 
+**High-performance BitTorrent client and library in Go.** Running in production at [put.io][putio-link] since 2019, processing thousands of torrents daily with minimal system resources.
+
 [![GoDoc](https://godoc.org/github.com/cenkalti/rain?status.svg)](https://pkg.go.dev/github.com/cenkalti/rain/torrent?tab=doc)
 [![GitHub Release](https://img.shields.io/github/release/cenkalti/rain.svg)](https://github.com/cenkalti/rain/releases)
 [![Coverage Status](https://coveralls.io/repos/github/cenkalti/rain/badge.svg)](https://coveralls.io/github/cenkalti/rain)
 [![Go Report Card](https://goreportcard.com/badge/github.com/cenkalti/rain)](https://goreportcard.com/report/github.com/cenkalti/rain)
 
 Features
 --------
+
+### Protocol Support
 - [Core protocol](http://bittorrent.org/beps/bep_0003.html)
 - [Fast extension](http://bittorrent.org/beps/bep_0006.html)
 - [Magnet links](http://bittorrent.org/beps/bep_0009.html)
@@ -23,11 +27,14 @@ Features
 - [PEX](http://bittorrent.org/beps/bep_0011.html)
 - [Message stream encryption](http://wiki.vuze.com/w/Message_Stream_Encryption)
 - [WebSeed](http://bittorrent.org/beps/bep_0019.html)
-- Fast resuming
-- IP blocklist
-- RPC server & client
-- Console UI
-- Tool for creating & reading .torrent files
+
+### Client Features
+- Fast resuming with BoltDB persistence
+- IP blocklist support
+- JSON-RPC 2.0 server & client
+- Interactive console UI
+- Tools for creating & reading .torrent files
+- Resource management (connections, memory, file handles)
 
 Screenshot
 ----------
@@ -36,36 +43,82 @@ Screenshot
 Installing
 ----------
 
-If you are on MacOS you can install from [brew](https://brew.sh/):
+### macOS
 ```sh
 brew install cenkalti/rain/rain
 ```
 
-Otherwise, get the latest binary from [releases page](https://github.com/cenkalti/rain/releases).
+### Other Platforms
+Download the latest binary from the [releases page](https://github.com/cenkalti/rain/releases).
+
+### From Source
+```sh
+go install github.com/cenkalti/rain/v2@latest
+```
+
+Quick Start
+-----------
+
+Rain operates as a client-server application with a single binary.
+
+### 1. Start the Server
+```sh
+# Start Rain server (creates default config if none exists)
+rain server
+```
+
+### 2. Add Your First Torrent
+```sh
+# Add a magnet link
+rain client add "magnet:?xt=urn:btih:..."
+
+# Or add a torrent file
+rain client add /path/to/file.torrent
+
+# Or add torrent from URL
+rain client add "https://example.com/file.torrent"
+```
+
+### 3. Monitor Progress
+```sh
+# List all torrents
+rain client list
+
+# Watch progress in console UI
+rain client console
+```
+
+### 4. Control Downloads
+```sh
+# Pause a torrent
+rain client stop <torrent-id>
+
+# Resume a torrent
+rain client start <torrent-id>
 
-Usage as torrent client
------------------------
+# Remove completed torrent
+rain client remove <torrent-id>
+```
 
-Rain is distributed as single binary file.
-The main use case is running `rain server` command and operating the server with `rain client <subcommand>` commands.
-Server consists of a BitTorrent client and a RPC server.
-`rain client` is used to give commands to the server.
-There is also `rain client console` command which opens up a text based UI that you can view and manage the torrents on the server.
-Run `rain help` to see other commands.
+Use `rain help` or `rain help <command>` for detailed information.
 
 Usage as library
 ----------------
 
+Rain can be embedded in Go applications as a powerful BitTorrent library.
+
 ```go
 import "github.com/cenkalti/rain/v2/torrent"
 
-// Create a session
+// Create session with default config
 ses, _ := torrent.NewSession(torrent.DefaultConfig)
+defer ses.Close()
 
-// Add magnet link
+// Add a magnet link
+magnetLink := "magnet:?xt=urn:btih:..."
 tor, _ := ses.AddURI(magnetLink, nil)
 
-// Watch the progress
+// Monitor download progress
 for range time.Tick(time.Second) {
 	s := tor.Stats()
 	log.Printf("Status: %s, Downloaded: %d, Peers: %d", s.Status.String(), s.Bytes.Completed, s.Peers.Total)
@@ -79,17 +132,72 @@ See [package documentation](https://pkg.go.dev/github.com/cenkalti/rain/torrent?
 Configuration
 -------------
 
-All values have sensible defaults, so you can run Rain with an empty config but if you want to customize it's behavior,
-you can pass a YAML config with `-config` flag. Config keys must be in lowercase.
-See the description of values in here: [config.go](https://github.com/cenkalti/rain/blob/master/torrent/config.go)
+Rain works out of the box with sensible defaults, but can be customized with a YAML configuration file.
+
+### Basic Configuration
+
+**Default config location:** `~/rain/config.yaml` (created automatically if missing)
+
+**Custom config:**
+```sh
+rain server -config /path/to/config.yaml
+```
+
+### Complete Reference
+
+For all available configuration options, see [config.go](https://github.com/cenkalti/rain/blob/master/torrent/config.go).
+
+**Note:** Configuration keys use dash-separated format (e.g., `port-begin`, not `portbegin`) starting from v2.
+
+Architecture
+------------
+
+Rain's architecture is designed specifically for high-performance server environments, with several unique characteristics:
+
+### Unique Design Decisions
+
+**Separate Port Per Torrent:** Unlike other BitTorrent clients, Rain allocates a separate peer port for each torrent. This enables:
+- Multiple downloads of the same torrent for different accounts on private trackers
+- Accurate ratio tracking per account
+- Better isolation between torrents
+
+**Server-First Design:** Rain prioritizes server-side performance over desktop features:
+- Optimized for hundreds of concurrent torrents
+- Minimal system resource usage
+- Production-ready stability (running at put.io since 2019)
+- JSON-RPC API for remote management
+
+### Project Structure
+```
+rain/
+├── torrent/       # Core BitTorrent session and torrent logic
+├── rainrpc/       # Shared types for JSON-RPC 2.0 API
+├── internal/      # Internal packages (networking, protocol, storage, etc.)
+└── main.go        # Entry point
+```
+
+### Component Architecture
+
+Rain follows a layered architecture with clear separation of concerns:
+
+**Core Layer:**
+- `torrent/session.go` - Main orchestrator managing torrents, DHT, and shared resources
+- `torrent/torrent.go` - Individual torrent lifecycle management
+
+**Protocol Layer:**
+- BitTorrent protocol implementation (`internal/peerprotocol/`)
+- Tracker communication (`internal/tracker/`, `internal/announcer/`)
+- DHT and PEX support (`internal/dht/`, `internal/pex/`)
 
-Difference from other clients
------------------------------
+**Network Layer:**
+- Connection management (`internal/peer/`, `internal/peerconn/`)
+- Message Stream Encryption (`internal/mse/`)
+- Resource limiting (`internal/resourcemanager/`)
 
-Rain is the main BitTorrent client used at [put.io][putio-link].
-It is designed to handle hundreds of torrents while using low system resources.
-One notable difference from other clients is that Rain uses a separate peer port for each torrent.
-This allows Rain to download same torrent for multiple accounts in same private tracker and keep reporting their ratio correctly.
+**Storage Layer:**
+- Piece management (`internal/piece/`, `internal/piececache/`)
+- File I/O optimization (`internal/storage/`)
+- Resume data persistence with BoltDB
 
 Missing features
 ----------------