# Black Hole Share – AI Guide

- Purpose: lightweight Actix-Web service for ephemeral image/text sharing; uploads saved as JSON files on disk and purged after their TTL.
- **Base directory is `data/`**: the server uses relative paths `data/html/`, `data/logs/`, `data/storage/`. Run from repo root locally; Docker mounts `./data:/data`.
- HTTP entrypoint and routing live in [src/main.rs](../src/main.rs): `/` serves `index.html`, `/bhs/{id}` serves `view.html`, `/api/upload` and `/api/content/{id}` registered from the API module, catch-all serves other static files under `html/` (list cached at startup via `STATIC_PAGES`).
- Request JSON bodies capped at ~3 MiB via `web::JsonConfig`. Background cleanup task runs every 60s to delete expired assets in `storage/`.
- Upload API in [src/api.rs](../src/api.rs): accepts JSON `{ duration: minutes, content_type, content }`; `text/plain` content is stored raw bytes, other types are base64-decoded. On success returns `{ "link": "/bhs/<uuid>" }`.
- Fetch API in [src/api.rs](../src/api.rs): loads `{id}` from `storage/`, rejects missing or expired assets, responds with original MIME and bytes.
- Asset model and persistence in [src/data_mgt.rs](../src/data_mgt.rs): assets serialized as JSON files named by UUID, with `expires_at` computed from `share_duration` (minutes). Cleanup logs removals to stdout.
- Logging helper in [src/logs.rs](../src/logs.rs): appends access lines with timing, IPs, scheme, UA to `logs/access.log`; runs for every handled request.
- Frontend upload page [data/html/index.html](../data/html/index.html): JS handles drag/drop, paste, or file picker; converts images to base64 or keeps text, POSTs to `/api/upload`, shows returned link and copies to clipboard. Styling/theme in [data/html/style.css](../data/html/style.css).
- Viewer page [data/html/view.html](../data/html/view.html): fetches `/api/content/{id}`, renders images with zoom overlay or text with zoomable modal; shows error when content missing/expired.
- Environment: `BIND_ADDR` and `BIND_PORT` (defaults 0.0.0.0:8080) are read via `LazyLock` on startup; `tokio` multi-thread runtime used.
- Build/dev: `cargo run --release` from repo root (ensure `data/` exists with `html/`, `logs/`, `storage/`), or use Dockerfile (Arch base + rustup build) and docker-compose (Traefik labels, port 8080→80, volume `./data:/data`).
- No test suite present; verify changes by running the server and exercising `/api/upload` and `/api/content/{id}` via the provided UI or curl.
- When adding features, keep payload sizes small or adjust the JSON limit in [src/main.rs](../src/main.rs); ensure new routes log via `log_to_file` for observability; clean up expired artifacts consistently with `clear_assets()` patterns.