# 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 centralized in `lib/config`. Startup applies built-in
defaults, environment variables, then safe BadgerDB settings overrides.

Storage paths are derived from `WARPBOX_DATA_DIR`:

```text
<WARPBOX_DATA_DIR>/uploads
<WARPBOX_DATA_DIR>/db
```

The admin account is bootstrapped from `WARPBOX_ADMIN_PASSWORD` when no admin
user exists. If the password is empty, admin login stays disabled unless an
admin user already exists in BadgerDB.

Primary environment variables:

- `WARPBOX_DATA_DIR`
- `WARPBOX_ADMIN_PASSWORD`
- `WARPBOX_ADMIN_USERNAME`
- `WARPBOX_ADMIN_EMAIL`
- `WARPBOX_ADMIN_ENABLED`
- `WARPBOX_ALLOW_ADMIN_SETTINGS_OVERRIDE`
- `WARPBOX_ADMIN_COOKIE_SECURE`
- `WARPBOX_GUEST_UPLOADS_ENABLED`
- `WARPBOX_API_ENABLED`
- `WARPBOX_ZIP_DOWNLOADS_ENABLED`
- `WARPBOX_ONE_TIME_DOWNLOADS_ENABLED`
- `WARPBOX_RENEW_ON_ACCESS_ENABLED`
- `WARPBOX_RENEW_ON_DOWNLOAD_ENABLED`
- `WARPBOX_DEFAULT_GUEST_EXPIRY_SECONDS`
- `WARPBOX_MAX_GUEST_EXPIRY_SECONDS`
- `WARPBOX_GLOBAL_MAX_FILE_SIZE_BYTES`
- `WARPBOX_GLOBAL_MAX_BOX_SIZE_BYTES`
- `WARPBOX_DEFAULT_USER_MAX_FILE_SIZE_BYTES`
- `WARPBOX_DEFAULT_USER_MAX_BOX_SIZE_BYTES`
- `WARPBOX_SESSION_TTL_SECONDS`
- `WARPBOX_BOX_POLL_INTERVAL_MS`
- `WARPBOX_THUMBNAIL_BATCH_SIZE`
- `WARPBOX_THUMBNAIL_INTERVAL_SECONDS`

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/server/admin.go      Admin 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/config/config.go     Typed config and settings definitions
lib/metastore/           BadgerDB metadata store
lib/models/models.go     Shared data structures
```

## Tests

Existing tests currently focus on the storage layer. Run them with:

```bash
go test ./...
```