docs: add comprehensive README with features and setup guidedocs: add comprehensive README with features and setup guide

2026-04-28 20:35:29 +03:00
parent 9dececcc7d
commit fc3de58b5b
2 changed files with 255 additions and 0 deletions
--- a/docs/tech.md
+++ b/docs/tech.md
@@ -0,0 +1,122 @@
+# 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 ./...
+```