123 lines
3.5 KiB
Markdown
123 lines
3.5 KiB
Markdown
|
# 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 ./...
|
||
|
|
```
|