docs: add comprehensive README with features and setup guidedocs: add comprehensive README with features and setup guide

README.md

@@ -0,0 +1,133 @@
+# WarpBox
+
+WarpBox is a small, self-hosted file sharing app with temporary upload boxes,
+simple download links, optional passwords, ZIP downloads, and a very deliberate
+retro desktop mood.
+
+It is meant to feel quick: pick files, choose how long the box should live,
+upload, and share the link.
+
+```mermaid
+flowchart LR
+    A[Choose files] --> B[Create box]
+    B --> C[Upload to box]
+    C --> D[Share link]
+    D --> E[Download files or ZIP]
+    E --> F[Expire or one-time cleanup]
+```
+
+## Features
+
+- Multi-file uploads through a browser UI.
+- Temporary boxes with configurable retention choices.
+- Optional password protection per box.
+- Individual file downloads or a single ZIP download.
+- One-time download mode for ZIP-only handoff.
+- Background thumbnails for image files.
+- Plain filesystem storage, with JSON manifests next to uploaded files.
+- No database required.
+
+## How It Fits Together
+
+```mermaid
+flowchart TB
+    Browser[Browser UI]
+    Server[Go HTTP server]
+    Manifest[Box manifest JSON]
+    Files[Uploaded files]
+    Thumbs[Generated thumbnails]
+
+    Browser -->|create box / upload / poll| Server
+    Server --> Manifest
+    Server --> Files
+    Server --> Thumbs
+    Thumbs -->|preview URLs| Browser
+    Files -->|downloads / ZIP| Browser
+```
+
+## Quick Start
+
+Requirements:
+
+- Go 1.22 or newer.
+
+Run the app:
+
+```bash
+go run ./cmd run
+```
+
+Then open:
+
+```text
+http://localhost:8080
+```
+
+To listen somewhere else:
+
+```bash
+go run ./cmd run --addr :3000
+```
+
+## Configuration
+
+WarpBox mostly works with defaults. These environment variables tune polling
+and thumbnail generation.
+
+| Variable | Default | Minimum | What it does |
+| --- | ---: | ---: | --- |
+| `WARPBOX_BOX_POLL_INTERVAL_MS` | `5000` | `1000` | Browser polling interval for box/file status updates. |
+| `WARPBOX_THUMBNAIL_BATCH_SIZE` | `10` | `1` | Number of pending thumbnails processed per worker pass. |
+| `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` | `30` | `1` | Delay between thumbnail worker passes. |
+
+Example:
+
+```bash
+WARPBOX_BOX_POLL_INTERVAL_MS=2000 \
+WARPBOX_THUMBNAIL_BATCH_SIZE=20 \
+WARPBOX_THUMBNAIL_INTERVAL_SECONDS=10 \
+go run ./cmd run --addr :8080
+```
+
+## Storage
+
+Uploads are stored locally under:
+
+```text
+data/uploads/
+```
+
+Each box gets its own directory containing the uploaded files and a
+`.warpbox.json` manifest. Image thumbnails are stored inside a box-local
+`.thumbnails` directory.
+
+```text
+data/uploads/
++-- <box-id>/
+    +-- .warpbox.json
+    +-- file.txt
+    +-- .thumbnails/
+        +-- <file-id>.jpg
+```
+
+## Project Layout
+
+```text
+cmd/            CLI entrypoint
+lib/server/     HTTP handlers and server setup
+lib/routing/    Route registration
+lib/boxstore/   Box storage, manifests, downloads, thumbnails
+lib/helpers/    Small shared helpers
+lib/models/     Shared request/response models
+templates/      Server-rendered HTML
+static/         CSS, JavaScript, fonts, icons, and images
+docs/           Project documentation
+```
+
+## Notes
+
+WarpBox is intentionally simple. It uses the local filesystem as its backing
+store, relies on generated box IDs for share links, and keeps most behavior
+easy to follow from the Go handlers and the small browser scripts.
+
+For a short implementation overview, see [docs/tech.md](docs/tech.md).

docs/tech.md

@@ -0,0 +1,122 @@
+# WarpBox Tech Stack
+
+This document is a light technical map of WarpBox. It avoids deep internals,
+but should be enough to understand what the project is built from and where the
+main pieces live.
+
+## Backend
+
+WarpBox is written in Go.
+
+Main libraries:
+
+- `github.com/gin-gonic/gin` for HTTP routing, middleware, JSON responses, and
+  HTML template rendering.
+- `github.com/gin-contrib/gzip` for compressed static asset responses.
+- `github.com/spf13/cobra` for the small command-line interface.
+
+The app starts from `cmd/main.go`. The `warpbox run` command calls the server
+package, loads templates from `templates/*.html`, registers routes, mounts
+`/static`, starts the thumbnail worker, and serves HTTP.
+
+## Frontend
+
+The frontend is server-rendered HTML with vanilla JavaScript.
+
+- Templates live in `templates/`.
+- Browser behavior lives in `static/js/app.js` and `static/js/box.js`.
+- Styling lives in `static/css/`.
+- Visual assets, fonts, icons, cursors, and sprites live under `static/`.
+
+There is no frontend build step. The browser receives HTML from Gin templates
+and static assets directly from the Go server.
+
+## Storage
+
+WarpBox uses the local filesystem instead of a database.
+
+Uploaded boxes are stored under:
+
+```text
+data/uploads/
+```
+
+Each box directory contains uploaded files plus a `.warpbox.json` manifest.
+The manifest tracks file names, statuses, retention, password metadata,
+download options, and thumbnail state.
+
+## Upload Flow
+
+```mermaid
+sequenceDiagram
+    participant UI as Browser UI
+    participant API as Gin server
+    participant Store as boxstore
+    participant Disk as Local disk
+
+    UI->>API: POST /box
+    API->>Store: create manifest
+    Store->>Disk: write box directory + manifest
+    API-->>UI: box id + upload URLs
+    UI->>API: POST /box/:id/files/:file_id/upload
+    API->>Store: save file and update status
+    Store->>Disk: write file + manifest
+    UI->>API: GET /box/:id/status
+    API-->>UI: current file states
+```
+
+## Download Flow
+
+Shared boxes are served from `/box/:id`.
+
+Users can download individual files when the box allows it. ZIP downloads are
+created on demand from the files currently marked complete. One-time download
+boxes force ZIP download and delete the box after a successful ZIP response.
+
+## Thumbnail Worker
+
+The thumbnail worker is a background goroutine. On each pass it scans upload
+boxes, finds complete image files without thumbnails, generates small JPEG
+previews, and updates the manifest.
+
+Tuning is done with:
+
+- `WARPBOX_THUMBNAIL_BATCH_SIZE`
+- `WARPBOX_THUMBNAIL_INTERVAL_SECONDS`
+
+## Configuration
+
+Runtime configuration is intentionally small.
+
+| Variable | Default | Purpose |
+| --- | ---: | --- |
+| `WARPBOX_BOX_POLL_INTERVAL_MS` | `5000` | Status polling interval used by box pages. |
+| `WARPBOX_THUMBNAIL_BATCH_SIZE` | `10` | Number of thumbnail jobs per worker pass. |
+| `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` | `30` | Delay between thumbnail worker passes. |
+
+The HTTP listen address is configured through the CLI flag:
+
+```bash
+go run ./cmd run --addr :8080
+```
+
+## Code Map
+
+```text
+cmd/main.go              CLI setup
+lib/server/server.go     Gin engine setup and worker startup
+lib/server/handlers.go   HTTP handlers
+lib/routing/routes.go    Route table
+lib/boxstore/store.go    Box manifests, uploads, downloads, retention
+lib/boxstore/thumbnails.go
+                          Thumbnail scanning and generation
+lib/models/models.go     Shared data structures
+```
+
+## Tests
+
+Existing tests currently focus on the storage layer. Run them with:
+
+```bash
+go test ./...
+```