Files
obsidian-vault/sportnote-roadmap.md
T

97 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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