27 lines
1.7 KiB
Markdown
27 lines
1.7 KiB
Markdown
# DuckDB Backend
|
|
|
|
HTTP-based analytical and transactional backend for personal logging data stored in the Knowledge Wiki.
|
|
Powered by Python 3.12, FastAPI, and in-memory DuckDB querying JSONL files directly.
|
|
|
|
## Architecture
|
|
|
|
- **Single Source of Truth**: Knowledge Wiki (`/wiki` git repository with data in `/wiki/data/**/*.jsonl`).
|
|
- **Engine**: In-memory DuckDB reading `sleep`, `nutrition`, `mila`, `entities`, and `garmin` partitions.
|
|
- **Git Synchronization**:
|
|
- Background periodic `git pull --rebase origin main` (every 60s).
|
|
- Mutating operations (`POST /duckdb-api/v1/events`) append to typed JSONL partition files, sort them, commit, rebase, and push to origin main.
|
|
- Conflicts trigger automatic rebase abort and flag `git_conflict: true` on `/status` and `/healthz`.
|
|
|
|
## Endpoints
|
|
|
|
- `GET /duckdb-api/v1/mila/dashboard`: Curated aggregated dashboard for Mila (sleep, wake timer, feedings, diapers, WHO percentiles).
|
|
- `GET /duckdb-api/v1/moritz/dashboard`: Curated aggregated dashboard for Moritz (today's intake, yesterday's 24h deficit/surplus, Garmin recovery & sleep, 7d/30d trends).
|
|
- `POST /duckdb-api/v1/query`: Generic read-only SQL queries against DuckDB tables and views.
|
|
- `POST /duckdb-api/v1/events`: Record new events (sleep, nutrition, diaper, feeding, growth).
|
|
- `POST /duckdb-api/v1/events/stop`: Close active open sleep session or interval.
|
|
- `DELETE /duckdb-api/v1/events/{id}`: Soft-delete event.
|
|
- `POST /duckdb-api/v1/entities`: Upsert entities (`foods`, `recipes`, `places`, `people`).
|
|
- `GET /duckdb-api/v1/healthz`: Liveness and readiness probe.
|
|
- `GET /duckdb-api/v1/status`: Git synchronization status and table row counts.
|
|
- `POST /duckdb-api/v1/git/sync`: Manual pull or webhook sync trigger.
|