laurence/openscribe
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openscribe/state/DECISIONS.md
Laurence 8fd9b694f8
Some checks failed
ci / firmware (pull_request) Failing after 31s
Details
ci / openapi (pull_request) Failing after 33s
Details
ci / emulator (pull_request) Failing after 24s
Details
ci / server (pull_request) Failing after 37s
Details
docs+site: Nightjar brand, hosted service, infrastructure plan, saved site 
Persists the branding/commercial/infrastructure work (previously only in chat and
on the live site) into version control.

What changed:
- docs/naming.md: due-diligence and the decision to brand the product Nightjar
  (OpenScribe domain/GitHub/trademark collisions; alternatives screened; why Nightjar).
- docs/hosted-service.md: the commercial model - plan tiers (Self-host / Cloud
  Starter / Cloud Pro / Private), indicative pricing, backend mapping, and the
  build-to-sell roadmap (metering, billing, provisioning, DPA).
- docs/infrastructure.md: backend infra plan. Primary option = self-host on the
  3x Minisforum MS-02 cluster (one with an RTX 3050 6GB) fronted by a Cloudflare
  Tunnel, with node roles, the 3050 capacity reality, caveats, and a Hetzner cloud
  fallback. Provision-later.
- site/: reproducible marketing-site source - block content for all 11 pages
  (rebranded to Nightjar), the navigation, the Contact Form 7 config (honeypot),
  the ApisCP SOAP helper (tools/apiscp.php, no secret), and a README on how the
  WordPress site is built and managed via the API.
- state/: DECISIONS (Nightjar rebrand, hosted service, MS-02 backend), PROJECT
  (brand + commercial section), TODO (rename decision, trademark, mailbox, pricing,
  hosted-service build, infra provisioning).

Why:
- User asked to save everything to the repo. Captures the product rebrand, the
  commercialisation plan, and the infrastructure decision so a cold session has the
  full picture.

Notes:
- The repo is still named `openscribe`; the product/brand is Nightjar. A full
  codebase rename is deferred (tracked in TODO + docs/naming.md).
- No secrets committed: the ApisCP API key is read from a local scratch file, never
  the repo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-05 22:24:24 +01:00

8.7 KiB
Raw Blame History

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.