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 2026-09-08 13:23:45 -05:00
commit 5fab96e824
46 changed files with 3616 additions and 0 deletions

53
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,53 @@
# Contributing to S.H.O.N.A.R.
Thanks for your interest in improving S.H.O.N.A.R.!
## Ground rules
1. **Original code only.** Do not submit code, assets, names, logos, or API
details derived from proprietary voice-note products (Plaud or otherwise).
This project is Apache-2.0 and must stay clean-room.
2. **Privacy is a feature.** Changes must not add telemetry, analytics, or
undisclosed network calls. Any new external service integration requires
explicit configuration and in-app disclosure.
3. **Never commit secrets.** Configuration goes through environment variables
(`SHONAR_*`) — never hard-coded credentials.
4. **Keep `main` buildable.** Every PR must pass lint and tests.
## Development setup
```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 && .venv/bin/ruff check .
# Android
cd android
./gradlew test assembleDebug
```
## Pull request checklist
- [ ] `ruff check .` and `pytest` pass (backend)
- [ ] `./gradlew test` passes (Android, if touched)
- [ ] API changes regenerate `shared/openapi.json` (`scripts/gen_openapi.sh`)
- [ ] New endpoints have tests, including authorization checks
- [ ] Docs updated when behaviour or configuration changes
- [ ] Commit per logical unit; imperative-mess-free messages ("Add X", not "added x")
## Style
- Python 3.11+, type hints everywhere, 100-col, `ruff format`.
- Kotlin with Compose; follow existing MVVM structure (ui → viewmodel →
repository → data source).
- Error messages shown to users must be safe: no stack traces, no internal
paths, no information leakage about other users' data.
## Reporting issues
Use the issue templates. For security issues, see SECURITY.md — do not open
a public issue.