# 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 ./...
```