openscribe/state/DECISIONS.md

# Decisions

> A dated, append only log of decisions and their rationale. Newest at the top. Never
> rewrite past entries; if a decision is reversed, add a new entry that says so.

## 2026-07-05 - Backend infra: self-host on the MS-02 cluster (provision later)

- **Decision:** The hosted service will run primarily on owned hardware - 3x Minisforum
  MS-02-class mini-workstations, one with an RTX 3050 6GB - fronted by a Cloudflare Tunnel.
  Node A (GPU) = AI worker (faster-whisper + local LLM), Node B = app/API/Postgres/Redis,
  Node C = MinIO storage + overflow + HA. Cloud VMs (Hetzner) are the fallback/hybrid.
  **Not provisioned yet**; stand up at first beta / paying users. Full plan:
  `docs/infrastructure.md`.
- **Context:** User has the MS-02 cluster on hand and prefers self-host for small scale.
- **Rationale:** The 3050 handles whisper easily and a 7-8B summary model fits 6GB; owned
  hardware is cheaper than cloud and strengthens the Private-tier privacy story (audio
  never leaves our premises). Cloud fallback covers uptime-sensitive growth.
- **Consequences:** Need Cloudflare Tunnel, backups/UPS, and to mind home-hosting uptime;
  6GB VRAM caps local LLMs at ~8B until a bigger GPU is added.

## 2026-07-05 - Commercialise via a managed "hosted" service + plan tiers

- **Decision:** 12 Hobbies Studio offers a managed backend so people can use Nightjar
  without self-hosting. Plans: Self-host (free), Cloud Starter (~GBP 6), Cloud Pro
  (~GBP 18) on commercial AI, and Private (~GBP 39) on self-hosted open models (audio never
  touches a third-party AI). Marketing site live; billing/signup not built yet (lead-gen
  only). See `docs/hosted-service.md`.
- **Context:** User asked for commercial options where they host the backend.
- **Rationale:** Open project + managed convenience; the two backends map to the two plan
  families. Cloud tiers keep good margin (cheap per-minute AI); Private is the privacy
  premium.
- **Consequences:** Need metering, billing (Stripe), provisioning, a DPA, real pricing, and
  a `hello@12hobbies.studio` mailbox before launch.

## 2026-07-05 - Rebrand product to "Nightjar" (repo stays `openscribe` for now)

- **Decision:** The product/commercial brand is **Nightjar** (site:
  nightjar.12hobbies.studio). The repository keeps the name `openscribe` until a full
  codebase rename is decided.
- **Context:** Due-diligence found "OpenScribe" unusable for a commercial brand (taken
  domains, heavy in-category GitHub collision, weak/uncleared trademark). See
  `docs/naming.md`.
- **Rationale:** "Nightjar" is distinctive, low-collision, and an arbitrary (strong)
  trademark for AI software. Rejected: Mockingjay (Lionsgate TM), Lyrebird/Fathom
  (in-category), dictionary words (taken/crowded), Recita (common).
- **Consequences:** Website rebranded. A full project/repo rename (SPDX, firmware
  namespaces, docs, Forgejo repo) is deferred. Formal trademark clearance still needed.

## 2026-07-03 - Pluggable AI providers (bring your own AI)

- **Decision:** Transcription and summarisation each select a provider via config. LLM:
  `ollama` (local, default) | `openai_compatible` (any base_url + key: OpenAI, Groq,
  OpenRouter, LocalAI, LM Studio, vLLM, Gemini's OpenAI endpoint) | `anthropic` (Claude via
  the official `anthropic` SDK). Transcription: `local_whisper` (faster-whisper) |
  `openai_compatible` (OpenAI Whisper, Groq, self-hosted whisper server). See
  `docs/ai-providers.md` and `server/app/providers/`.
- **Context:** User: "allow for connecting the device to any open standard AI, or even
  commercial ones." This is also OpenScribe's key differentiator vs Plaud's locked cloud.
- **Rationale:** One OpenAI-compatible client covers most of the ecosystem; Anthropic needs
  its own provider (different API shape, no OpenAI-compatible endpoint). AI dependencies are
  optional per chosen provider, keeping the default install lean and fully self-hostable.
- **Consequences:** No lock-in; the owner picks cost/quality/privacy trade-offs. Anthropic
  provider defaults to `claude-opus-4-8`. Local faster-whisper execution is wired in M5.

## 2026-07-03 - Licensing: copyleft, multi-part (REUSE-style)

- **Decision:** Code (firmware, server, app) under GPL-3.0-only; hardware design under
  CERN-OHL-S-2.0; case models and documentation under CC-BY-SA-4.0. Licence texts live in
  `LICENSES/`; top-level `LICENSE` is GPL-3.0 for forge detection; `LICENSING.md` explains
  the split. Apache-2.0 text kept for a possible future permissive client SDK.
- **Context:** User asked for "as open source as possible".
- **Rationale:** Strong copyleft keeps derivatives open (the point of the project); CERN
  and CC-BY-SA are the standard reciprocal licences for hardware and creative/docs.
- **Consequences:** Derivatives must stay open. If we later want wide third-party adoption
  of a client library, that specific component can be relicensed permissive (Apache-2.0).

## 2026-07-03 - Self-hosted tools throughout

- **Decision:** Forge = Forgejo (git.discworld.casa); CI = Forgejo Actions; STT =
  faster-whisper; summaries = Ollama (local LLM); object storage = MinIO (S3-compatible)
  or local FS / WebDAV. No required proprietary SaaS anywhere.
- **Context:** User: "using selfhosted tools where possible".
- **Rationale:** Matches the own-your-data goal and keeps running costs at zero beyond the
  user's own hardware.
- **Consequences:** User must run a server (NAS / mini-PC) for AI features; the device and
  app work without it for plain recording + transfer.

## 2026-07-03 - Self-hosted AI stack in scope for v1

- **Decision:** Build the full pipeline: record -> transcribe (faster-whisper) ->
  summarise (Ollama) -> export. AI runs on the server, not the device.
- **Context:** User chose "Full self-hosted AI stack" at the scope checkpoint.
- **Rationale:** Transcription + summary is Plaud's headline feature; server-side keeps the
  device cheap and low-power while staying fully self-hosted.
- **Consequences:** Larger build; server is required for AI features. Device stays simple.

## 2026-07-03 - Independent upload target: generic cloud storage

- **Decision:** When on charge / hard-powered, the device uploads to configurable generic
  storage: S3-compatible (default: self-hosted MinIO), with WebDAV/NAS as alternatives.
- **Context:** User chose "Generic cloud storage" for the independent WiFi path.
- **Rationale:** Decouples device from any bespoke always-on server; standard protocol;
  self-hostable.
- **Consequences:** Server ingests from the store (watch/notify/poll). Object-store
  credentials live in device NVS and must be scoped/rotatable.

## 2026-07-03 - Mobile app: Flutter (Android + iOS)

- **Decision:** One Flutter codebase targeting both platforms.
- **Context:** User chose Flutter (Android + iOS).
- **Rationale:** Single codebase, both stores.
- **Consequences:** iOS background BLE is restricted, so BLE = control/provisioning only;
  WiFi handles bulk transfer (already the design).

## 2026-07-03 - Hardware: ESP32-S3 + I2S MEMS mic + microSD (off-the-shelf, no PCB)

- **Decision:** Target ESP32-S3 (PSRAM, WiFi + BLE 5, USB). Mic: I2S MEMS (INMP441
  default, ICS-43434 upgrade). Storage: microSD. Power: LiPo + charge IC with charge/VBUS
  detect. v1 uses modules on a carrier/protoboard; no custom PCB. Full list in
  `hardware/BOM.md`.
- **Context:** User asked me to spec a BOM to buy; has ESP32 / Pico W / other boards.
- **Rationale:** ESP32-S3 does all three radios + audio buffering on one cheap chip; I2S
  MEMS gives clean digital audio; microSD removes length limits. Pico W and classic ESP32
  are viable fallbacks but weaker for audio/PSRAM.
- **Consequences:** Bigger enclosure than a commercial Plaud; a custom PCB is a later step.

## 2026-07-03 - Firmware toolchain: PlatformIO + Arduino-ESP32

- **Decision:** Build the firmware with PlatformIO using the Arduino-ESP32 framework.
- **Context:** Need approachable, reproducible builds and CI.
- **Rationale:** Lower barrier for contributors than raw ESP-IDF; good library support for
  I2S, SD, BLE, HTTP; PlatformIO gives pinned, CI-friendly builds.
- **Consequences:** If we hit Arduino limits (fine-grained power, advanced BLE), we can
  drop to ESP-IDF per-module or migrate; noted as a possible future change.

## 2026-07-03 - Project name and default audio format

- **Decision:** Name = "OpenScribe" (record + transcribe, open). Default recording format
  = WAV PCM 16 kHz mono 16-bit; compressed codecs (ADPCM/Opus) are a later optimisation.
- **Context:** Project bootstrap.
- **Rationale:** Clear, descriptive, unencumbered name; WAV is simple and high quality for
  speech and trivial to decode everywhere.
- **Consequences:** Larger files (~115 MB/hour) make WiFi the primary transfer path;
  revisit with Opus for battery-mode transfer and storage.