From fc3de58b5b99aaef0cf1f09eb13e6b3e02952ab8 Mon Sep 17 00:00:00 2001 From: Daniel Legt Date: Tue, 28 Apr 2026 20:35:29 +0300 Subject: [PATCH] docs: add comprehensive README with features and setup guidedocs: add comprehensive README with features and setup guide --- README.md | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/tech.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 255 insertions(+) create mode 100644 docs/tech.md diff --git a/README.md b/README.md index e69de29..117e61a 100644 --- a/README.md +++ b/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/ ++-- / + +-- .warpbox.json + +-- file.txt + +-- .thumbnails/ + +-- .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). diff --git a/docs/tech.md b/docs/tech.md new file mode 100644 index 0000000..9a6d40c --- /dev/null +++ b/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 ./... +```