Run + Sleep: 2026-09-23 — 2.01km 7'03" + max-HR sprint test (165 under-read), sleep 87pt HRV 126 deep 30%
This commit is contained in:
@@ -0,0 +1,96 @@
|
||||
# SportNote — Tech Stack & Roadmap
|
||||
|
||||
> Decisions from 2026-09-20 (stack pivot + product planning session with Hermes).
|
||||
> Companion to [[sportnote-blueprint]] (the target experience).
|
||||
|
||||
---
|
||||
|
||||
## 1. Tech Stack Decision — Pivot to Python
|
||||
|
||||
| Layer | Was | Now |
|
||||
|---|---|---|
|
||||
| Backend | Spring Boot | **FastAPI** |
|
||||
| ORM | JPA/Hibernate | **SQLModel** (SQLAlchemy + Pydantic) |
|
||||
| DB | SQLite/Turso | **SQLite → Postgres later** |
|
||||
| Migrations | — | **Alembic** |
|
||||
| Stats | — | **pandas + scikit-learn** (polars later) |
|
||||
| Agent | Spring AI (idea) | **direct LLM SDK** (LangChain only if needed) |
|
||||
| Frontend | Angular (idea) | **PWA from the start** (framework TBD, Svelte/React) |
|
||||
| Dev/CI | Jenkins (work) | **GitHub Actions** + Docker |
|
||||
|
||||
**Why the pivot:** statistics + agentic AI are the *core* of the product, not a "later" feature. Python owns that ecosystem (pandas, scikit-learn, LangChain, MCP). One language across app + analysis + agent beats a Spring app + separate Python service.
|
||||
|
||||
---
|
||||
|
||||
## 2. Product Identity
|
||||
|
||||
- **"Not a tracker — an AI agent for health & sports."**
|
||||
- "The equivalent of talking to Hermes about my running, but simpler with a UI."
|
||||
- **No wearable required** — but **brand-agnostic screenshot OCR** is the moat (any watch → universal DB).
|
||||
- **Self-report ("how did it feel?") is load-bearing** — the one universal, device-free input, and what makes raw numbers meaningful.
|
||||
- **Goals are data**, not just a page — the coach consumes them as input.
|
||||
- **PWA from the start** — no native Android app.
|
||||
|
||||
---
|
||||
|
||||
## 3. The 6 Checkpoints
|
||||
|
||||
| # | Checkpoint | Note |
|
||||
|---|---|---|
|
||||
| 1 | **Backend + universal DB + endpoints** | schema includes `run`, `sleep`, **and `goal`** |
|
||||
| 2 | **OCR ingestion (Huawei first)** | bar = reliable on *my* screenshots, not "perfected" |
|
||||
| 3 | **Manual-entry UI (PWA)** | self-report required, installable, works with no wearable |
|
||||
| 4 | **Statistics** | the "visible number" |
|
||||
| 5 | **Goals experience** | set + track — coach needs them as input |
|
||||
| 6 | **AI coach** | reads stats + goals + self-report |
|
||||
|
||||
Through-line: #1 contract → #2 proves the moat → #3 makes it usable → #4–6 are the product.
|
||||
|
||||
---
|
||||
|
||||
## 4. Universal Schema Tiers
|
||||
|
||||
| Tier | Data | Flag |
|
||||
|---|---|---|
|
||||
| **0 — Core** | date, duration, distance → **pace (derived)** | required |
|
||||
| **1 — Most important** | avg HR, max HR, **HR recovery (2-min)**, sleep (HRV/RHR/REM%/deep%/total), **self-report** | required for self-report, optional wearable |
|
||||
| **2 — Extra** | cadence, HR zones, pace-by-km (splits) | optional |
|
||||
| **3 — Skip** | stride, ground contact, vertical oscillation, balance L/R, training load, recovery-time estimate, elevation | store nothing |
|
||||
|
||||
**Rule:** *"Would this change my advice?"* — if no, skip it.
|
||||
|
||||
**Correction vs earlier assumption:** sleep is NOT "extra" — it's the single most important modifier of performance. Every run log cross-references the night before.
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Architectural Insights
|
||||
|
||||
1. **Coach = stats-computed + prompt-injected** — never free-range tool-calling, especially with a 9B local model. Backend crunches numbers with pandas → hands the model a pre-digested summary → model reasons over it.
|
||||
2. **OCR's hard part is layout→schema mapping**, not OCR itself. Layered: easyocr (read text) → normalization/parse (field aliases) → vision model only as fallback.
|
||||
3. **Goals are input to the coach** — "training toward Nov 29 half, 10km PR, ankle recovering" changes every recommendation.
|
||||
4. **Manual entry and OCR write to the same endpoint** — the universal schema is the contract both paths hit.
|
||||
|
||||
---
|
||||
|
||||
## 6. Local Dev Setup (as of 2026-09-20)
|
||||
|
||||
- **Hardware:** Fedora, RX 9060 XT 16GB
|
||||
- **Local model:** Qwen 3.5 9B via LM Studio (fast on the AMD card)
|
||||
- **Harness:** OpenCode, pointed at LM Studio's OpenAI-compatible API (`http://127.0.0.1:1234/v1`)
|
||||
- **Division of labor:** local Qwen = *pair programmer* (helps, doesn't write for me) · Hermes = *PM/thinker* (specs, review, architecture) · Gutca = *owner* (understands everything)
|
||||
- **Project home:** `~/Projects/sportnote` on Fedora, pushed to GitHub
|
||||
|
||||
---
|
||||
|
||||
## 7. Current State
|
||||
|
||||
- ✅ Phase 0 skeleton: FastAPI + SQLModel + SQLite, `run`/`sleep`/`weight` tables, Alembic wired, pushed to GitHub.
|
||||
- ⏳ Checkpoint 1: define the universal schema (the contract), then build endpoints.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [[sportnote-blueprint]] — the target experience (conversation architecture, OCR pipeline, onboarding interview)
|
||||
- [[Half-marathon-plan]] — current training context
|
||||
- [[Health/sleep-system]] — sleep data context
|
||||
Reference in New Issue
Block a user