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.

The main request surfaces are:

• GET / for the upload box UI.
• GET /box/:id for shared box pages.
• GET /box/:id/login and POST /box/:id/login for password-protected boxes.
• GET /box/:id/download for ZIP downloads.
• GET /box/:id/files/:filename for individual file downloads.
• GET /box/:id/thumbnails/:file_id for image previews.
• POST /box for new upload box creation.
• POST /box/:id/files/:file_id/upload for manifest-based uploads.
• POST /box/:id/files/:file_id/status for upload status updates.
• POST /box/:id/upload and POST /upload for legacy upload compatibility.
• /admin/* for the admin UI and settings.

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, popups, 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 for box data and BadgerDB for app metadata.

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. BadgerDB stores users, tags, sessions, and runtime settings overrides.

Upload Flow

sequenceDiagram
    participant Browser as Browser UI
    participant Server as Gin server
    participant Store as boxstore
    participant Disk as Local disk

    Browser->>Server: POST /box
    Server->>Store: create box directory + manifest
    Store->>Disk: write .warpbox.json
    Server-->>Browser: box id + upload URLs
    Browser->>Server: POST /box/:id/files/:file_id/upload
    Server->>Store: save file and update manifest
    Store->>Disk: write file + manifest
    Browser->>Server: POST /box/:id/files/:file_id/status
    Server->>Store: update file status
    Store->>Disk: rewrite manifest
    Browser->>Server: GET /box/:id/status
    Server-->>Browser: 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.

flowchart LR
    Shared[Shared box page]
    File[Individual file download]
    Zip[ZIP download]
    OneTime[One-time ZIP only]
    Delete[Delete box after success]

    Shared --> File
    Shared --> Zip
    OneTime --> Zip
    Zip --> Delete

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

Size limit settings accept _MB or _BYTES env names. WARPBOX_ADMIN_ENABLED accepts auto, true, or false.

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 cover config, storage, server security, and metastore behavior. Run them with:

go test ./...