docs: update README and tech docs for BadgerDB and thumbnails
- 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:
68
README.md
68
README.md
@@ -1,19 +1,30 @@
|
||||
# WarpBox
|
||||
|
||||
WarpBox is a small, self-hosted file sharing app with temporary upload boxes,
|
||||
simple download links, optional passwords, ZIP downloads, and a very deliberate
|
||||
retro desktop mood.
|
||||
simple download links, optional passwords, ZIP downloads, generated image
|
||||
thumbnails, and a very deliberate retro desktop mood.
|
||||
|
||||
It is meant to feel quick: pick files, choose how long the box should live,
|
||||
upload, and share the link.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Choose files] --> B[Create box]
|
||||
B --> C[Upload to box]
|
||||
C --> D[Share link]
|
||||
D --> E[Download files or ZIP]
|
||||
E --> F[Expire or one-time cleanup]
|
||||
User[Person in browser]
|
||||
UI[WarpBox UI]
|
||||
API[Go HTTP server]
|
||||
Manifest[(Box manifest JSON)]
|
||||
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
|
||||
@@ -25,7 +36,8 @@ flowchart LR
|
||||
- One-time download mode for ZIP-only handoff.
|
||||
- Background thumbnails for image 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
|
||||
|
||||
@@ -36,11 +48,13 @@ flowchart TB
|
||||
Manifest[Box manifest JSON]
|
||||
Files[Uploaded files]
|
||||
Thumbs[Generated thumbnails]
|
||||
DB[(BadgerDB metadata)]
|
||||
|
||||
Browser -->|create box / upload / poll| Server
|
||||
Browser -->|POST /box, uploads, status polls| Server
|
||||
Server --> Manifest
|
||||
Server --> Files
|
||||
Server --> Thumbs
|
||||
Server --> DB
|
||||
Thumbs -->|preview URLs| 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_INTERVAL_SECONDS` | `30` | Delay between thumbnail worker passes. |
|
||||
|
||||
Size limits also accept `_MB` variants for the same settings.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
@@ -144,23 +160,29 @@ data/db/
|
||||
## Project Layout
|
||||
|
||||
```text
|
||||
cmd/ CLI entrypoint
|
||||
lib/server/ HTTP handlers and server setup
|
||||
lib/routing/ Route registration
|
||||
lib/boxstore/ Box storage, manifests, downloads, thumbnails
|
||||
lib/config/ Typed environment and runtime settings config
|
||||
lib/metastore/ BadgerDB metadata store for users, tags, settings, sessions
|
||||
lib/helpers/ Small shared helpers
|
||||
lib/models/ Shared request/response models
|
||||
templates/ Server-rendered HTML
|
||||
static/ CSS, JavaScript, fonts, icons, and images
|
||||
docs/ Project documentation
|
||||
cmd/ CLI entrypoint
|
||||
lib/server/ HTTP handlers and server setup
|
||||
lib/routing/ Route registration
|
||||
lib/boxstore/ Box storage, manifests, downloads, thumbnails
|
||||
lib/config/ Typed environment and runtime settings config
|
||||
lib/metastore/ BadgerDB metadata store for users, tags, settings, sessions
|
||||
lib/helpers/ Small shared helpers
|
||||
lib/models/ Shared request/response models
|
||||
templates/ Server-rendered HTML
|
||||
static/css/ Stylesheets
|
||||
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
|
||||
|
||||
WarpBox is intentionally simple. It uses the local filesystem as its backing
|
||||
store, relies on generated box IDs for share links, and keeps most behavior
|
||||
easy to follow from the Go handlers and the small browser scripts.
|
||||
WarpBox is intentionally simple. It uses the local filesystem for box data,
|
||||
BadgerDB for app metadata, relies on generated box IDs for share links, and
|
||||
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).
|
||||
|
||||
65
docs/tech.md
65
docs/tech.md
@@ -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
|
||||
`/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.
|
||||
@@ -26,14 +40,15 @@ 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/`.
|
||||
- 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 instead of a database.
|
||||
WarpBox uses the local filesystem for box data and BadgerDB for app metadata.
|
||||
|
||||
Uploaded boxes are stored under:
|
||||
|
||||
@@ -43,26 +58,30 @@ 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.
|
||||
download options, and thumbnail state. BadgerDB stores users, tags, sessions,
|
||||
and runtime settings overrides.
|
||||
|
||||
## Upload Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as Browser UI
|
||||
participant API as Gin server
|
||||
participant Browser as Browser UI
|
||||
participant Server 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
|
||||
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
|
||||
UI->>API: GET /box/:id/status
|
||||
API-->>UI: current file states
|
||||
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
|
||||
@@ -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
|
||||
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
|
||||
|
||||
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_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:
|
||||
|
||||
```bash
|
||||
@@ -150,7 +186,8 @@ lib/models/models.go Shared data structures
|
||||
|
||||
## 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
|
||||
go test ./...
|
||||
|
||||
Reference in New Issue
Block a user