100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
# Transmission Manager — AGENTS.md
|
|
|
|
## Project Overview
|
|
A lightweight single-binary Go web app that provides a beautiful dark-mode SPA for managing/viewing torrents in a Transmission RPC client.
|
|
|
|
## Architecture
|
|
- **Backend**: Go (stdlib net/http only, no external dependencies). Serves on port 8080.
|
|
- `GET /` → serves embedded static files (index.html, app.js, styles.css)
|
|
- `GET /api/torrents` → proxies to Transmission RPC, returns clean JSON
|
|
- `GET /api/stats` → global session stats
|
|
- **Frontend**: Vanilla HTML + CSS + JS. No frameworks. Single page. Dark mode only.
|
|
|
|
## Transmission RPC Details
|
|
- RPC URL: `http://192.168.20.22:3210/transmission/rpc`
|
|
- No auth required (open on LAN)
|
|
- The RPC requires a session-ID handshake:
|
|
1. POST to the RPC URL
|
|
2. If response is 409, read the `X-Transmission-Session-Id` header from the response
|
|
3. Re-send the request with that header
|
|
4. Cache the session-ID for future requests
|
|
- For torrent list, request these fields:
|
|
```
|
|
id, name, totalSize, downloadedEver, uploadedEver, uploadRatio,
|
|
percentDone, status, eta, error, errorString, doneDate, isFinished,
|
|
rateDownload, rateUpload, peersConnected, peersGettingFromUs, peersSendingToUs,
|
|
peers (array of {address, clientName, progress, isDownloadingFrom, isUploadingTo, rateToClient, rateToPeer})
|
|
```
|
|
- "Peers with 100%" = count of peers in the `peers` array where `progress === 1.0`
|
|
- "Finished date" = `doneDate` (Unix timestamp, 0 means not finished)
|
|
|
|
## Design Requirements (CRITICAL)
|
|
- **Dark mode only** — deep dark background (#0a0a0f or similar)
|
|
- **Modern, stylish, clean** — think Linear, Vercel, Raycast aesthetic
|
|
- **Accent color**: Use a vibrant accent (cyan/teal #00d4ff or purple #8b5cf6)
|
|
- **Typography**: System font stack, -apple-system, Inter-like
|
|
- **Torrent cards or rows** with:
|
|
- Name (truncated with ellipsis if long)
|
|
- Size (human-readable: GB, MB, etc.)
|
|
- Progress bar (animated, smooth)
|
|
- Percentage done
|
|
- Ratio (uploadRatio)
|
|
- Downloaded / Uploaded amounts
|
|
- Download/Upload speeds
|
|
- ETA (when downloading)
|
|
- Status badge (downloading, seeding, paused, finished, error)
|
|
- Finish date (formatted nicely, e.g. "Jul 8, 2026")
|
|
- Peer count with 100% (e.g. "3/7 peers at 100%")
|
|
- **Auto-refresh** every 3 seconds
|
|
- **Header** with app title and global stats (total download/upload speed, torrent count)
|
|
- **Responsive** — works on mobile and desktop
|
|
- Use CSS variables for theming
|
|
- Smooth transitions and micro-animations
|
|
- Cards with subtle borders and hover effects
|
|
|
|
## Code Structure
|
|
```
|
|
main.go — Go backend (HTTP server, Transmission RPC proxy, static file serving via embed)
|
|
web/
|
|
index.html — SPA shell
|
|
app.js — Frontend logic (fetch API, render, auto-refresh)
|
|
styles.css — All styling
|
|
Dockerfile — Multi-stage: golang:1.24-alpine (build) → alpine:latest (runtime)
|
|
go.mod — module transmission-manager, go 1.24
|
|
```
|
|
|
|
## Go Implementation Notes
|
|
- Use `embed` package to embed web/ directory into the binary
|
|
- Transmission RPC communication via net/http client
|
|
- Implement session-ID handshake with retry on 409
|
|
- Use sync.Mutex to protect session-ID cache
|
|
- Format numbers nicely (human-readable sizes) in the frontend, not backend
|
|
- CORS not needed (same origin)
|
|
- The Go server should be minimal and fast
|
|
|
|
## Dockerfile
|
|
```dockerfile
|
|
FROM golang:1.24-alpine AS builder
|
|
WORKDIR /app
|
|
COPY go.mod ./
|
|
RUN go mod download
|
|
COPY . .
|
|
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o transmission-manager .
|
|
|
|
FROM alpine:latest
|
|
RUN apk add --no-cache ca-certificates
|
|
WORKDIR /app
|
|
COPY --from=builder /app/transmission-manager .
|
|
EXPOSE 8080
|
|
CMD ["./transmission-manager"]
|
|
```
|
|
|
|
## Do NOT
|
|
- Do not use any Go web framework (gin, fiber, etc.) — stdlib only
|
|
- Do not use any JS framework (React, Vue, etc.) — vanilla only
|
|
- Do not add authentication
|
|
- Do not add CI/CD or GitHub Actions
|
|
- Do not create any GitHub repository
|
|
- Do not add vendored dependencies
|
|
- Do not add tests unless necessary — keep it simple
|