warpbox-dev/README.md

# Warpbox.dev

This repository contains the Go backend base for `warpbox.dev`, a self-hosted transfer-first file sharing application.

## Run

```bash
./scripts/run/dev.sh
```

The default server listens on `:8080`.

Upload size limits are configured in megabytes through `WARPBOX_MAX_UPLOAD_SIZE_MB`.
Fractions are supported, so `0.5Mb` is 512 KiB and `1.5Mb` is 1536 KiB.

Runtime data is configured with `WARPBOX_DATA_DIR` and defaults to `./data` in the dev environment.
The dev script resolves that path from the repository root.

The basic admin console is available at `/admin`. Set `WARPBOX_ADMIN_TOKEN` and use that value to sign in.

For one-off Go commands, run them from the backend module:

```bash
cd backend
go run ./cmd/warpbox
```

## Layout

- `backend/cmd/warpbox` - main application entry point.
- `backend/libs/config` - environment-backed configuration.
- `backend/libs/httpserver` - server construction and route composition.
- `backend/libs/handlers` - HTTP handlers for pages, API, health, static files.
- `backend/libs/middleware` - request logging, recovery, security headers, gzip, request IDs.
- `backend/libs/services` - business logic boundaries, starting with upload limits.
- `backend/libs/helpers` - small reusable helpers.
- `backend/libs/web` - Go template renderer.
- `backend/templates` - server-rendered Go templates.
- `backend/static/css`, `backend/static/js`, `backend/static/img`, `backend/static/fonts` - public assets served from `/static/`.
- `scripts/run/dev.sh` - local development runner.
- `scripts/env/dev.env.example` - tracked development environment template.
- `scripts/env/dev.env` - local development environment, ignored by git.

## Stage 2 Operator Tools

- `/admin/login` - token-based admin login.
- `/admin` - overview metrics: boxes, files, storage, recent uploads, protected/expired boxes.
- `/admin/files` - recent upload table with view and delete actions.
- Expired boxes are cleaned on startup and then every `WARPBOX_CLEANUP_EVERY`.
- Missing image/video thumbnails are generated in a background worker every `WARPBOX_THUMBNAIL_EVERY`.

## Runtime Data

Warpbox keeps local runtime data under the configured data directory:

- `data/files/{box_id}/@each@{file_id}.ext` - uploaded file contents.
- `data/files/{box_id}/@thumb@{file_id}.jpg` - generated previews where available.
- `data/db/warpbox.bbolt` - bbolt metadata database for boxes and file records.
- `data/logs/{YYYY-MM-DD}.log` - JSONL logs, one event per line.

## Static Asset Policy

The static handler sets long-lived immutable caching for images, video, audio, and fonts, shorter caching for CSS/JS, and gzip compression for compressible responses.