WarpBox/docs/tech.md

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:

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

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:

<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:

go run ./cmd run --addr :8080

Code Map

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:

go test ./...