first commit

README.md

@@ -0,0 +1,59 @@
+# q-buffer
+
+A production-ready monorepo that orchestrates qBittorrent torrents in a controlled playback loop with strict peer enforcement.
+
+## Overview
+
+- Backend: Node.js + TypeScript + Express + socket.io
+- Frontend: React + Vite + TypeScript (shadcn-style UI)
+- Storage: JSON file DB with atomic writes and mutex
+- Docker: dev (two containers) and prod (single container)
+
+## Quick Start
+
+1. Copy `.env.example` to `.env` and fill values.
+2. Start dev stack:
+
+```bash
+docker-compose -f docker-compose.dev.yml up --build
+```
+
+3. Open:
+
+- Web: http://localhost:5173
+- API/Socket: http://localhost:3001
+
+## Production
+
+```bash
+docker-compose up --build
+```
+
+Open http://localhost:3001
+
+## Features
+
+- Login with env-configured credentials (JWT httpOnly cookie)
+- Torrent list and selection
+- Torrent archive to `/data/torrents/{hash}.torrent`
+- Loop engine with delete/re-add between runs
+- Aggressive allow-IP enforcement (peer ban when supported)
+- Dry run report and profiles
+- Real-time status/logs via socket.io
+
+## Environment Variables
+
+- `QBIT_BASE_URL`, `QBIT_USERNAME`, `QBIT_PASSWORD`
+- `APP_USERNAME`, `APP_PASSWORD`, `JWT_SECRET`
+- `POLL_INTERVAL_MS`, `ENFORCE_INTERVAL_MS`, `DEFAULT_DELAY_MS`, `MAX_LOOP_LIMIT`
+
+## Folder Layout
+
+- `apps/server`: Express API + socket.io
+- `apps/web`: Vite React UI
+- `data`: JSON DB, logs, torrent archive
+
+## Notes
+
+- If magnet metadata generation fails, use Advanced upload to provide `.torrent` manually.
+- The loop engine deletes downloaded data between loops.