# Project: OpenScribe

> The anchor document. A session that reads only this, TODO.md and DECISIONS.md should
> understand what the project is and what to do next. Keep it current.

## Objective

An open-source, self-hosted AI voice recorder in the style of the Plaud Note / NotePin:
a small wearable device that records audio to local storage, syncs to a mobile app and
to a self-hosted server, and produces transcripts and summaries, with a completely open
API so the owner controls their data end to end. No proprietary cloud, no lock-in.

## Scope

- In scope:
  - Firmware for an ESP32-S3 recorder (audio capture, storage, power, controls).
  - Three sync paths: BLE control, WiFi bulk transfer to the app, and independent WiFi
    upload to cloud storage when on charge / hard-powered (no phone present).
  - A completely open, documented REST API (device and server) with an OpenAPI spec.
  - A self-hosted AI stack: transcription (faster-whisper) and summarisation (local LLM
    via Ollama), plus export in multiple formats.
  - A Flutter mobile app (Android + iOS).
  - A parametric 3D-printed case (OpenSCAD) plus a hardware BOM and wiring guide.
- Out of scope (for now):
  - A custom PCB (v1 uses off-the-shelf modules on protoboard / carrier).
  - Cloud SaaS hosting. Everything runs on hardware the user owns.
  - Real-time on-device transcription (server does the AI; device just records + syncs).
  - Speaker diarisation (deferred; noted as a later enhancement).

## Audience

Makers and privacy-minded users who want a Plaud-like capture-and-summarise workflow
they fully own: build the device from the BOM, print the case, run the server on a NAS
or mini-PC, install the app, keep every recording and transcript on their own kit.

## Description

The device records voice to microSD as WAV (compressed codecs optional later). On
battery it advertises over BLE for control and hands bulk transfers to WiFi. When placed
on charge or hard-powered it becomes autonomous: it joins configured WiFi, serves its
REST API on the LAN, and uploads new recordings to generic cloud storage (S3-compatible,
e.g. self-hosted MinIO, or WebDAV/NAS). A self-hosted server ingests recordings,
transcribes them with faster-whisper, summarises with a local LLM, and exposes an open
API with exports (audio, TXT, SRT/VTT, Markdown, JSON). The Flutter app provisions the
device, browses the library, plays audio and shows transcripts and summaries.

## Success criteria

- A person can build the device from `hardware/BOM.md`, flash `firmware/`, print
  `case/`, run `server/`, install `app/`, and capture -> transcribe -> summarise -> export
  a recording without any proprietary service.
- Every recording is retrievable and exportable through the open API.
- The device syncs three ways as specified (BLE, WiFi-to-app, independent WiFi upload).
- The whole stack is self-hostable and licensed for open reuse.

## Brand and commercial (2026-07)

- **Product brand: Nightjar** (the repo is still named `openscribe`; rename deferred - see
  `docs/naming.md`).
- **Marketing site:** live at https://nightjar.12hobbies.studio (WordPress on ApisCP;
  content + tooling saved in `site/`).
- **Commercial model:** open project + a managed "hosted" backend with plan tiers
  (`docs/hosted-service.md`); backend infra plan in `docs/infrastructure.md` (self-host on
  the MS-02 cluster, provision later).

## Key facts

- Trunk branch: `main`
- Forge / remote: https://git.discworld.casa/laurence/openscribe
- Runtime / stack:
  - Firmware: C++ (Arduino-ESP32) via PlatformIO, target ESP32-S3.
  - Server: Python (FastAPI) + faster-whisper + Ollama + object storage (MinIO/local).
  - App: Flutter (Dart), Android + iOS.
  - Case: OpenSCAD. CI: Forgejo Actions (self-hosted runner).
- How to run it: see `state/NOTES.md` (per-component build/run commands).