# SOUL.md — Project Character

## Product Name

`live.f12.rocks`

## One-Liner

Event photo pep pipeline: organizer Android app -> gmic/rembg -> web.
Upload a photo at the event, get back weird/fun filtered variants seconds
later.

## Vision

At an event (f12 meetup/party), the organizer shares a photo into the
Android app. The phone converts it to a 2000px JPEG, uploads it, a worker
rips the background off, runs it through a random gmic filter/blend chain,
and a handful of variants show up on a shared web page almost immediately —
guests need no app, no login, no "process the photos later". If a variant
is fun, remix it with different filters right there. Finished jobs land on
the organizer's phone (gallery + local notification) and stay on the web
for everyone with the link.

## Audience

Event organizers (upload via the Android app) and attendees on their
phones, often on bad venue wifi. Nobody signs up, nobody logs in. Guests
with the link see everything; only the organizer's app can upload.

## Tone & Wording

- **Voice:** direct, casual, no explaining-the-obvious. It's a fun tool
  for an event, not enterprise software.
- **Formality:** du. Short German labels in the UI (Ansehen, Remix,
  Download, Varianten, Zwischenschritte, Warteschlange, Fertig).
- **Error messages:** say what broke, don't blame the visitor — most
  errors here are gmic filter flakiness, not user error.
- **Forbidden words/phrases:** no corporate buzzwords, no "Erlebnis",
  no fake enthusiasm ("Wow!", "Amazing!"). Keep it matter-of-fact.

### Wording Examples

| Context | Good | Bad |
|---------|------|-----|
| Success | `Remix erzeugt.` | `Dein Kunstwerk ist fertig! 🎉` |
| Error | `Foreground-Filter fehlgeschlagen: Timeout nach 120s` | `Etwas ist schiefgelaufen.` |
| Empty state | `Noch keine Jobs. Foto in der App teilen, dann kurz warten.` | `Hier ist noch nichts los... lade doch was hoch! 😊` |

## Design

- **Palette:** dark background (`#14161a`), off-white text, one warm
  accent color (`#ff5a1f`) for primary actions/links. No gradients.
- **Feel:** utilitarian, mobile-first, touch-friendly. Think backstage
  tool, not a consumer photo app. Deliberately avoids the generic
  "purple AI gradient + rounded blob" look.

## Non-Goals

- No web auth / accounts / login product — anyone with the link **sees**
  everything, by design. Upload is a separate shared token in the
  organizer app, not a user account.
- No Play Store / FCM / ntfy dependency. Notifications are local Android.
- No beamer/projector product built into this repo.
- Not a DAM (digital asset manager) — no albums, tagging, search,
  retention policies. `incoming/`, `variants/`, and `intermediates/`
  are the whole data model.
- No auto-deletion of incoming uploads. Ever. The worker only reads/copies.
- No Syncthing container in this compose. A host Syncthing share can
  still write `incoming/` as a fallback; it is not the product path.

## Infrastructure (project-local)

- Workdir on server: `/home/frank/live.f12.rocks`
- Data volume: `${DATA_HOST_DIR}` — prod default
  `/home/frank/sync.schwenk.online/data/livef12`, local override `./data`.
  Bind-mounted into `worker` and `web` at `/data` (see `compose.yml`).
- Layout:
  - `incoming/` — HTTP upload (and optional Syncthing drop)
  - `variants/` — `{stem}_original.jpg`, `{stem}_rembg.png`, `{stem}_vN.png`
  - `intermediates/` — `{stem}_vN_*.png` (incl. `_post_0` …)
  - `meta/` — status + manifest JSON
  - `processed.json`
- Domain: `live.f12.rocks`, routed via the shared external `traefik`
  network, TLS via `myresolver` (see `INFRASTRUCTURE.md`).
- rembg model cache lives in the named Docker volume `rembg_cache`.
- Organizer Android app lives in `android/` (sideload APK).
- `UPLOAD_TOKEN` in server `.env` — required for `POST /api/jobs`.

## Project-Specific Rules

```markdown
- Never delete or move files under incoming/ from worker code — the
  upload API (and optional Syncthing) is the writer there. (reason:
  uploads are the one copy of the original that exists outside a
  phone's camera roll)
- Keep every intermediate image under intermediates/ — don't clean them
  up automatically. (reason: useful for debugging bad filter picks,
  disk is cheap compared to re-running gmic)
- gmic/rembg subprocess calls always run under `nice` (see NICE_LEVEL) —
  the worker box needs to stay responsive for other things during an
  event. (reason: explicit requirement, avoid CPU starvation)
- POST /api/jobs is fail-closed: empty UPLOAD_TOKEN disables uploads.
  The public web UI stays read-only.
```

---

## Agent Instructions

When updating this file:

- Keep rules **unambiguous** — formality of tone doesn't matter, clarity does
- Include **wording** for user-facing text; colors are optional
- When Fränky says *"in this project, never X"*, add it here or in `BOUNDARIES.md` (agent proposes which)