This directory contains project documentation for the WebSDR monorepo.
Documentation is organized by topic. Currently, the primary documentation set is the WebUSB / SDR interaction subsystem under docs/webusb/.
- api.md - HTTP, WebSocket, WebUSB, and npm API reference
Start here: webusb/README.md
Key entry points:
- webusb/overview.md — high-level overview
- webusb/architecture.md — architecture and runtime boundaries
- webusb/control-model.md — control model and abstractions
- webusb/commands.md — command protocol and dispatch
- webusb/driver-development.md — adding / extending drivers
Diagrams live in webusb/diagrams/ (Mermaid sources .mmd and rendered .svg).
Manual (hardware-in-the-loop) testing docs:
Diagrams are written in Mermaid (.mmd) and rendered to SVG for stable display in GitHub.
The SVG files are the rendered artifacts; Mermaid files are the editable sources.
Regenerate all diagrams under docs/:
npm run docs:diagrams
Ubuntu (Chromium sandbox / AppArmor):
npm run docs:diagrams:ubuntu
Notes:
- Diagram rendering is implemented in scripts/render-mermaid.js and uses
mmdcfrom@mermaid-js/mermaid-cli. - The Ubuntu workaround relies on running
mmdcunder an AppArmor profile viaaa-exec.
In scope:
- WebUSB device access and interaction patterns
- Driver architecture (JavaScript and/or WASM drivers)
- Control model, commands, and data flow relevant to the WebUSB subsystem
Out of scope (for this docs folder):
- CI/CD and release process details
- Developer environment setup beyond what is needed to understand the subsystem
This documentation is intended for:
- Developers working on WebSDR frontend/backends
- Contributors implementing or integrating SDR drivers
- Reviewers evaluating architecture and protocol decisions