M0: repo scaffold, backend skeleton, schema + migrations, dev compose, docs
- Apache-2.0, README, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue templates - FastAPI app with /api/v1 healthz/readyz/system-status (honest AI disclosure) - Full SQLAlchemy schema (users, devices, refresh tokens, recordings, assets, upload sessions, transcripts, summaries, tags, jobs, exports) + Alembic migrations incl. Postgres FTS tsvector columns - Settings via SHONAR_* env only; local + S3 storage abstraction with path-traversal-safe keys - Docker dev compose (postgres+redis, 127.0.0.1-only); CI workflow; scripts - shared/openapi.json contract generated from app
This commit is contained in:
avi
commit
5fab96e824
46 changed files with 3616 additions and 0 deletions
121
README.md
Normal file
121
README.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
# S.H.O.N.A.R.
|
||||
|
||||
**S.H.O.N.A.R. — Self-hosted Oral Notes and Audio Recorder**
|
||||
|
||||
An open-source, self-hosted alternative to cloud voice-note AI devices and
|
||||
services. Record conversations on your Android phone, sync them to a server
|
||||
**you** control, transcribe and summarize them with AI providers **you**
|
||||
choose, and keep full ownership of your audio, transcripts, and accounts.
|
||||
|
||||
- No telemetry. No third-party analytics. No hidden external AI calls.
|
||||
- Runs fully locally by default (local transcription + local LLM supported).
|
||||
- Works with **no AI configured at all**: recording, sync, playback, download,
|
||||
and manual transcripts still work.
|
||||
- Apache-2.0 licensed. All code in this repository is original.
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
android/ Android app (Kotlin, Jetpack Compose, Material 3)
|
||||
backend/ FastAPI + PostgreSQL API server
|
||||
worker/ Background worker entrypoint (same image as backend)
|
||||
shared/ OpenAPI spec shared with the Android client
|
||||
deploy/ Docker Compose, reverse proxy, backup/restore
|
||||
docs/ Architecture, API, security, self-hosting guides
|
||||
scripts/ Dev / CI helper scripts
|
||||
```
|
||||
|
||||
## Quick start (Docker)
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# EDIT .env — at minimum set SHONAR_SECRET_KEY (any 32+ random chars):
|
||||
# python3 -c "import secrets; print(secrets.token_urlsafe(48))"
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Then open `http://localhost:8000/api/docs` for the interactive API docs and
|
||||
point the Android app at your server URL.
|
||||
|
||||
The default compose stack is: API + worker + PostgreSQL + Redis, with audio
|
||||
stored on the local filesystem. No paid cloud service is required.
|
||||
|
||||
## Quick start (Android)
|
||||
|
||||
Requirements: JDK 17, Android SDK (platform 35). See
|
||||
[android/README.md](android/README.md).
|
||||
|
||||
```bash
|
||||
cd android
|
||||
./gradlew assembleDebug
|
||||
adb install app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
## Feature status
|
||||
|
||||
S.H.O.N.A.R. is developed in milestones; each merged milestone is tested and
|
||||
buildable. See [docs/ROADMAP.md](docs/ROADMAP.md) for the maintained matrix.
|
||||
|
||||
**Current state:** M0–M1 complete — backend health, full auth (register,
|
||||
login, rotating refresh tokens with reuse detection, logout, delete-account),
|
||||
rate limiting, Alembic schema, Docker dev stack. Everything else is
|
||||
in-progress or TODO as per the roadmap.
|
||||
|
||||
## AI providers
|
||||
|
||||
All AI is optional and provider-independent, configured only through
|
||||
environment variables (never hard-coded keys):
|
||||
|
||||
| Variable | Values | Default |
|
||||
|---|---|---|
|
||||
| `SHONAR_TRANSCRIPTION_PROVIDER` | `none`, `whisper_http`, `faster_whisper` | `none` |
|
||||
| `SHONAR_TRANSCRIPTION_MODEL` | model name (e.g. `base`, `small`) | `base` |
|
||||
| `SHONAR_TRANSCRIPTION_BASE_URL` | whisper-compatible HTTP server URL | — |
|
||||
| `SHONAR_LLM_PROVIDER` | `none`, `openai_compat`, `ollama` | `none` |
|
||||
| `SHONAR_LLM_MODEL` / `SHONAR_LLM_BASE_URL` / `SHONAR_LLM_API_KEY` | model/endpoint/credentials | — |
|
||||
| `SHONAR_STORAGE_BACKEND` | `local`, `s3` | `local` |
|
||||
| `SHONAR_STORAGE_PATH` | filesystem storage root | `./data/storage` |
|
||||
| `SHONAR_DATABASE_URL` | SQLAlchemy async URL | postgres in compose |
|
||||
|
||||
When any external (non-local) provider is enabled, `/api/v1/system/status`
|
||||
reports `external_ai_in_use: true` and the Android app shows it in Settings —
|
||||
you always know if your audio or text leaves your machine.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [docs/self-hosting.md](docs/self-hosting.md) — deployment, HTTPS, backups
|
||||
- [docs/api.md](docs/api.md) — API overview (OpenAPI at `/api/docs`)
|
||||
- [docs/security.md](docs/security.md) — security model and honest limits
|
||||
- [docs/architecture.md](docs/architecture.md) — system design
|
||||
- [docs/recording-consent.md](docs/recording-consent.md) — legal notice
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# backend
|
||||
cd backend && uv venv .venv && uv pip install -e ".[dev]"
|
||||
docker compose -f deploy/docker-compose.dev.yml up -d
|
||||
.venv/bin/alembic upgrade head
|
||||
.venv/bin/uvicorn shonar.main:app --reload
|
||||
.venv/bin/pytest # tests
|
||||
.venv/bin/ruff check . # lint
|
||||
|
||||
# android
|
||||
cd android && ./gradlew test
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) and
|
||||
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
||||
|
||||
## License
|
||||
|
||||
Apache-2.0 — see [LICENSE](LICENSE).
|
||||
|
||||
## Legal notice
|
||||
|
||||
**You are responsible for complying with recording-consent laws in your
|
||||
jurisdiction.** Many jurisdictions require all-party consent to record a
|
||||
conversation. S.H.O.N.A.R. shows this notice in-app and never records without
|
||||
a visible, persistent recording indicator and an obvious stop control.
|
||||
Loading…
Add table
Add a link
Reference in a new issue