kato/warpbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README and tech docs for BadgerDB and thumbnails

Browse Source 
- Reflect BadgerDB integration for metadata storage in features and
  architecture diagrams
- Add thumbnail generation and static asset subdirectories to project
  layout
- Document _MB configuration variants for size limits
- List main API request surfaces in docs/tech.md for better developer
  reference
- Align documentation with recent architectural and routing changes
This commit is contained in:
Daniel Legt
2026-04-30 02:32:45 +03:00
parent ac6e8c591b
commit 903b4eeed8
2 changed files with 96 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
README.md
View File

@@ -1,19 +1,30 @@
# WarpBox # WarpBox
WarpBox is a small, self-hosted file sharing app with temporary upload boxes, WarpBox is a small, self-hosted file sharing app with temporary upload boxes,
simple download links, optional passwords, ZIP downloads, and a very deliberate simple download links, optional passwords, ZIP downloads, generated image
retro desktop mood. thumbnails, and a very deliberate retro desktop mood.
It is meant to feel quick: pick files, choose how long the box should live, It is meant to feel quick: pick files, choose how long the box should live,
upload, and share the link. upload, and share the link.
```mermaid ```mermaid
flowchart LR flowchart LR
A[Choose files] --> B[Create box] User[Person in browser]
B --> C[Upload to box] UI[WarpBox UI]
C --> D[Share link] API[Go HTTP server]
D --> E[Download files or ZIP] Manifest[(Box manifest JSON)]
E --> F[Expire or one-time cleanup] Files[(Uploaded files)]
Thumbs[(Thumbnail JPEGs)]
DB[(BadgerDB metadata)]
User --> UI
UI -->|create box / upload / poll status| API
API --> Manifest
API --> Files
API --> DB
Files -->|download files or build ZIP| API
Thumbs -->|preview URLs| UI
Files -->|scan image files| Thumbs
``` ```
## Features ## Features
@@ -25,7 +36,8 @@ flowchart LR
- One-time download mode for ZIP-only handoff. - One-time download mode for ZIP-only handoff.
- Background thumbnails for image files. - Background thumbnails for image files.
- Plain filesystem storage, with JSON manifests next to uploaded files. - Plain filesystem storage, with JSON manifests next to uploaded files.
- No database required. - Local BadgerDB metadata store for users, tags, sessions, and settings.
- No external database service required.
## How It Fits Together ## How It Fits Together
@@ -36,11 +48,13 @@ flowchart TB
Manifest[Box manifest JSON] Manifest[Box manifest JSON]
Files[Uploaded files] Files[Uploaded files]
Thumbs[Generated thumbnails] Thumbs[Generated thumbnails]
DB[(BadgerDB metadata)]
Browser -->|create box / upload / poll| Server Browser -->|POST /box, uploads, status polls| Server
Server --> Manifest Server --> Manifest
Server --> Files Server --> Files
Server --> Thumbs Server --> Thumbs
Server --> DB
Thumbs -->|preview URLs| Browser Thumbs -->|preview URLs| Browser
Files -->|downloads / ZIP| Browser Files -->|downloads / ZIP| Browser
``` ```
@@ -101,6 +115,8 @@ settings remain environment controlled.
| `WARPBOX_THUMBNAIL_BATCH_SIZE` | `10` | Number of pending thumbnails processed per worker pass. | | `WARPBOX_THUMBNAIL_BATCH_SIZE` | `10` | Number of pending thumbnails processed per worker pass. |
| `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` | `30` | Delay between thumbnail worker passes. | | `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` | `30` | Delay between thumbnail worker passes. |
Size limits also accept `_MB` variants for the same settings.
Example: Example:
```bash ```bash
@@ -144,23 +160,29 @@ data/db/
## Project Layout ## Project Layout
```text ```text
cmd/ CLI entrypoint cmd/ CLI entrypoint
lib/server/ HTTP handlers and server setup lib/server/ HTTP handlers and server setup
lib/routing/ Route registration lib/routing/ Route registration
lib/boxstore/ Box storage, manifests, downloads, thumbnails lib/boxstore/ Box storage, manifests, downloads, thumbnails
lib/config/ Typed environment and runtime settings config lib/config/ Typed environment and runtime settings config
lib/metastore/ BadgerDB metadata store for users, tags, settings, sessions lib/metastore/ BadgerDB metadata store for users, tags, settings, sessions
lib/helpers/ Small shared helpers lib/helpers/ Small shared helpers
lib/models/ Shared request/response models lib/models/ Shared request/response models
templates/ Server-rendered HTML templates/ Server-rendered HTML
static/ CSS, JavaScript, fonts, icons, and images static/css/ Stylesheets
docs/ Project documentation static/js/ Browser scripts
static/img/ Icons, sprites, and backgrounds
static/fonts/ Bitmap/pixel fonts
static/cursors/ Custom cursor packs
static/popups/ HTML popup content
docs/ Project documentation
``` ```
## Notes ## Notes
WarpBox is intentionally simple. It uses the local filesystem as its backing WarpBox is intentionally simple. It uses the local filesystem for box data,
store, relies on generated box IDs for share links, and keeps most behavior BadgerDB for app metadata, relies on generated box IDs for share links, and
easy to follow from the Go handlers and the small browser scripts. keeps most behavior easy to follow from the Go handlers and the small browser
scripts.
For a short implementation overview, see [docs/tech.md](docs/tech.md). For a short implementation overview, see [docs/tech.md](docs/tech.md).

65
docs/tech.md
View File

@@ -19,6 +19,20 @@ The app starts from `cmd/main.go`. The `warpbox run` command calls the server
package, loads templates from `templates/*.html`, registers routes, mounts package, loads templates from `templates/*.html`, registers routes, mounts
`/static`, starts the thumbnail worker, and serves HTTP. `/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 ## Frontend
The frontend is server-rendered HTML with vanilla JavaScript. The frontend is server-rendered HTML with vanilla JavaScript.
@@ -26,14 +40,15 @@ The frontend is server-rendered HTML with vanilla JavaScript.
- Templates live in `templates/`. - Templates live in `templates/`.
- Browser behavior lives in `static/js/app.js` and `static/js/box.js`. - Browser behavior lives in `static/js/app.js` and `static/js/box.js`.
- Styling lives in `static/css/`. - Styling lives in `static/css/`.
- Visual assets, fonts, icons, cursors, and sprites live under `static/`. - Visual assets, fonts, icons, cursors, popups, and sprites live under
`static/`.
There is no frontend build step. The browser receives HTML from Gin templates There is no frontend build step. The browser receives HTML from Gin templates
and static assets directly from the Go server. and static assets directly from the Go server.
## Storage ## Storage
WarpBox uses the local filesystem instead of a database. WarpBox uses the local filesystem for box data and BadgerDB for app metadata.
Uploaded boxes are stored under: Uploaded boxes are stored under:
@@ -43,26 +58,30 @@ data/uploads/
Each box directory contains uploaded files plus a `.warpbox.json` manifest. Each box directory contains uploaded files plus a `.warpbox.json` manifest.
The manifest tracks file names, statuses, retention, password metadata, The manifest tracks file names, statuses, retention, password metadata,
download options, and thumbnail state. download options, and thumbnail state. BadgerDB stores users, tags, sessions,
and runtime settings overrides.
## Upload Flow ## Upload Flow
```mermaid ```mermaid
sequenceDiagram sequenceDiagram
participant UI as Browser UI participant Browser as Browser UI
participant API as Gin server participant Server as Gin server
participant Store as boxstore participant Store as boxstore
participant Disk as Local disk participant Disk as Local disk
UI->>API: POST /box Browser->>Server: POST /box
API->>Store: create manifest Server->>Store: create box directory + manifest
Store->>Disk: write box directory + manifest Store->>Disk: write .warpbox.json
API-->>UI: box id + upload URLs Server-->>Browser: box id + upload URLs
UI->>API: POST /box/:id/files/:file_id/upload Browser->>Server: POST /box/:id/files/:file_id/upload
API->>Store: save file and update status Server->>Store: save file and update manifest
Store->>Disk: write file + manifest Store->>Disk: write file + manifest
UI->>API: GET /box/:id/status Browser->>Server: POST /box/:id/files/:file_id/status
API-->>UI: current file states Server->>Store: update file status
Store->>Disk: rewrite manifest
Browser->>Server: GET /box/:id/status
Server-->>Browser: current file states
``` ```
## Download Flow ## Download Flow
@@ -73,6 +92,20 @@ 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 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. boxes force ZIP download and delete the box after a successful ZIP response.
```mermaid
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 ## Thumbnail Worker
The thumbnail worker is a background goroutine. On each pass it scans upload The thumbnail worker is a background goroutine. On each pass it scans upload
@@ -126,6 +159,9 @@ Primary environment variables:
- `WARPBOX_THUMBNAIL_BATCH_SIZE` - `WARPBOX_THUMBNAIL_BATCH_SIZE`
- `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` - `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: The HTTP listen address is configured through the CLI flag:
```bash ```bash
@@ -150,7 +186,8 @@ lib/models/models.go Shared data structures
## Tests ## Tests
Existing tests currently focus on the storage layer. Run them with: Existing tests cover config, storage, server security, and metastore behavior.
Run them with:
```bash ```bash
go test ./... go test ./...