# 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-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.