# 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).