scaffold: OpenScribe open-source self-hosted AI voice recorder

Bootstrap of the project (M0). Sets up the monorepo, design docs, hardware BOM, the open API contract, component skeletons, licensing and CI, following the Default Workflow SOP. What changed: - CLAUDE.md + docs/: copied the Default Workflow so sessions load the SOP. - state/: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES filled in for OpenScribe. ARCHITECTURE captures the four-part design (firmware, server, app, case) and the three sync paths; DECISIONS records the hardware, AI-stack, storage, app and licensing choices; TODO lays out milestones M1-M9. - hardware/BOM.md: two build options (compact XIAO ESP32-S3 Sense; dev ESP32-S3 + I2S mic + SD), wiring/pinout, indicative cost. - api/openapi.yaml: the completely open API (device + server surfaces), including recording list/download/delete and exports (wav/ogg/txt/srt/vtt/md/json). - firmware/: PlatformIO ESP32-S3 project, two board profiles, pin map, boot scaffold with module seams for M1-M4. - server/: FastAPI skeleton mirroring the OpenAPI, config for self-hosted MinIO, faster-whisper and Ollama; stub routes browsable at /docs. - app/, case/: Flutter app plan; parametric OpenSCAD enclosure. - Licensing: GPL-3.0 (code), CERN-OHL-S-2.0 (hardware), CC-BY-SA-4.0 (case/docs), REUSE-style LICENSES/ with SPDX headers; LICENSING.md explains the split. - CI: Forgejo Actions workflow builds firmware (both profiles) and lints/imports server. Why: - Everything self-hosted and openly licensed per the user's requirements: an open API, three sync paths (BLE control, WiFi transfer, independent WiFi upload on charge to generic cloud storage), and a full self-hosted transcription+summary stack. Notes: - No custom PCB in v1; off-the-shelf modules. Physical verification waits on parts. - Component code is stubs at M0; features land milestone by milestone, each as its own branch/PR per the workflow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-03 10:21:37 +01:00 · 2026-07-03 10:21:37 +01:00 · 031074c9a9
commit 031074c9a9
36 changed files with 2922 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,86 @@
+# OpenScribe
+
+An open-source, self-hosted AI voice recorder in the style of the Plaud Note / NotePin.
+A small wearable device records audio to local storage, syncs to a mobile app and to a
+server you run, and produces transcripts and summaries, through a completely open API.
+No proprietary cloud, no lock-in.
+
+> Status: **early scaffold (M0)**. The design, hardware BOM, and open API are defined;
+> component code is being built milestone by milestone. See `state/TODO.md`.
+
+## Why
+
+Commercial AI recorders send your conversations to a vendor's cloud. OpenScribe keeps the
+whole pipeline (capture, storage, transcription, summarisation, export) on hardware you
+own, under open licences, with an API documented so you can build against it.
+
+## What it does
+
+- Records voice to microSD on a small ESP32-S3 device (button start/stop, LED status).
+- Syncs three ways:
+  1. **BLE** for control, status and WiFi provisioning.
+  2. **WiFi** to the mobile app for fast bulk transfer.
+  3. **Independent WiFi upload** to your storage when on charge / hard-powered, with no
+     phone present.
+- Transcribes (faster-whisper) and summarises (local LLM via Ollama) on a server you host.
+- Exposes a **completely open REST API** with exports: audio, TXT, SRT, VTT, Markdown, JSON.
+- Ships a **Flutter** app (Android + iOS) and a **3D-printed** parametric case.
+
+## Architecture at a glance
+
+```
+mic -> ESP32-S3 (record to microSD)
+         |  BLE: control / provision
+         |  WiFi REST API: transfer to app
+         |  WiFi uploader (on charge) -> object storage (MinIO / WebDAV / NAS)
+                                              |
+                                    self-hosted server (FastAPI)
+                                    faster-whisper -> Ollama -> open API + exports
+                                              |
+                              Flutter app (Android + iOS)
+```
+
+Full detail: [`state/ARCHITECTURE.md`](state/ARCHITECTURE.md). The API contract:
+[`api/openapi.yaml`](api/openapi.yaml).
+
+## Repository layout
+
+```
+firmware/   ESP32-S3 recorder firmware (PlatformIO, Arduino-ESP32)
+server/     Self-hosted FastAPI server: ingest, transcribe, summarise, serve API
+app/        Flutter mobile app (Android + iOS)
+hardware/   BOM, wiring/pinout, build notes (off-the-shelf modules, no PCB in v1)
+case/       Parametric 3D-printed enclosure (OpenSCAD)
+api/        openapi.yaml - the single source of truth for the open API
+docs/       Workflow docs (this project follows the Default Workflow SOP)
+state/      Project memory: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES
+LICENSES/   Full licence texts
+```
+
+## Hardware
+
+You build the device from off-the-shelf parts. See [`hardware/BOM.md`](hardware/BOM.md)
+for the shopping list, wiring and pinout. Core: an ESP32-S3 board with PSRAM, an I2S MEMS
+microphone, a microSD card, a LiPo battery and a charge IC.
+
+## Self-hosted stack
+
+Everything runs on hardware you own: Forgejo for the forge, faster-whisper for
+transcription, Ollama for summaries, MinIO (or WebDAV / NAS) for storage. Plain recording
+and transfer work without any server; the server adds transcription and summaries.
+
+## Getting started
+
+Nothing to run end to end yet (M0 scaffold). To follow along:
+
+- Read [`state/PROJECT.md`](state/PROJECT.md) and [`state/TODO.md`](state/TODO.md).
+- Per-component build/run commands are in [`state/NOTES.md`](state/NOTES.md) and each
+  component's `README.md`.
+
+## Licensing
+
+Multi-part, copyleft. Code is GPL-3.0-only, hardware is CERN-OHL-S-2.0, case and docs are
+CC-BY-SA-4.0. See [`LICENSING.md`](LICENSING.md).
+
+OpenScribe is an independent open-source project inspired by the Plaud class of device. It
+is not affiliated with or endorsed by Plaud.