diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000..ffe243d --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,61 @@ +# Product + + + +## Platform + +web + +(Implementation is Compose Multi/Desktop — JVM desktop app; recorded as `web` per schema since no native mobile target. The desktop app is the only shipped surface.) + +## Users + +Primary: the creator himself — heavy voice-memo user (meetings, phone calls, dictated thoughts) on a Framework laptop running Omarchy/Hyprland. Situation: a growing pile of audio files on disk that he never has time to re-listen to. Job: turn recordings into trustworthy text (transcripts) and useful summaries without any cloud involvement. + +Secondary (confirmed intent): other people may install it later, so the UI must stay presentable and self-explanatory to an outsider — no private-joke labels, no undocumented setup steps buried in code. + +## Product Purpose + +Shonar Desktop watches a local recordings folder, transcribes each file with Whisper and writes a summary with an LLM, then presents everything as a browsable, searchable library with playback. Success = the user opens any recording and gets its summary/sections (key points, decisions, action items, details) in seconds, and can re-summarize in different voices, with zero data leaving his network. + +## Positioning + +Local-first pipeline: audio never leaves the machine or LAN. Transcription is Whisper (Base default, Large v3 downloadable); summarization rides the private LAN GPU (H200 via 10.x network) when available, with automatic rescue onto the laptop's own Ollama when the LAN server fails — and the UI names which summarizer wrote each summary. A cloud SaaS competitor cannot copy "your recordings were never on anyone's server." + +## Operating Context + +- Library = files on disk (~/Music/Recordings), not a database; the engine mirrors them. Sidecar files (`*.shonar.json`, `*.transcript.md`) live next to the audio. +- Bundled FastAPI engine on 127.0.0.1:8000 with SQLite + an inline job queue; auto-transcribe pump processes new files. +- Real usage loop: record on phone → files sync in → app transcribes/summarizes → user skims summaries, re-summarizes in a voice (Neutral / Sarcastic / Funny / Dry wit), copies summary or action items into notes/messages. +- In-app mpv playback with seek; delete is undoable (trash + 10s undo). + +## Capabilities and Constraints + +- Privacy is the binding product promise: no INTERNET permission on the sibling Android app; the desktop engine binds 127.0.0.1; the LAN LLM is a private 10.x address, never public internet. Any UI or feature must not imply or require cloud connectivity. +- Voice personas are exactly four (Neutral, Sarcastic, Funny, Dry wit) — user-fixed, do not grow the list. +- Honest status is a standing user demand: progress labels must reflect truth (transcribe shows real %; summarize shows "working · m:ss" because the LLM gives no real fraction); unfinished integrations are hidden/labeled, never left configurable. +- Per-recording model override; tone rides the job; user-edited transcripts are final (re-transcribe never overwrites them). +- Compose Desktop (Kotlin/Material3) + FastAPI backend; SQLite; engine state in ~/.config/shonar-desktop/. + +## Brand Commitments + +- Name "Shonar" is fixed. The current deep-sea sonar look (deep navy + teal, sonar-ping logo) is the incumbent identity but explicitly NOT binding — the visual world may evolve in a future redesign. +- Voice of the UI: plain, honest, human sentences ("Summary ready — ", "Fix: open Settings → Summarizer…"). No marketing tone. + +## Evidence on Hand + +- Real transcript reports in ~/Music/Recordings (`*.transcript.md`) — genuine user content; never display, share, or fabricate from it. +- Working end-to-end pipeline exercised daily (transcribe → summarize → rescue fallback → voice re-summarize), verified via engine DB in dev sessions. +- Absences to not fabricate: no other users, no testimonials, no benchmarks, no pricing, no hosted service, no mobile app shipping from this repo (the Android sibling is a separate local-only product). + +## Product Principles + +1. Privacy is the product — every design decision must visibly keep data on the user's network. +2. Never lie about state: progress, errors, and which model did what are stated plainly. +3. One button deep: the common loop (open → read summary → copy) needs no manual. +4. The machine may fail, the workflow may not — rescue paths (fallback summarizer, retry, undo) are surfaced in-UI, not buried in logs. +5. Built for one, legible to many — personal tool now, but nothing that only its author could decode. + +## Accessibility & Inclusion + +No formal standard required yet; keep controls keyboard-reachable (detail screen already uses Alt+arrows/Esc) and status text real text, not color-only.