4.5 KiB
4.5 KiB
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
- 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.
- OCR's hard part is layout→schema mapping, not OCR itself. Layered: easyocr (read text) → normalization/parse (field aliases) → vision model only as fallback.
- Goals are input to the coach — "training toward Nov 29 half, 10km PR, ankle recovering" changes every recommendation.
- 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/sportnoteon Fedora, pushed to GitHub
7. Current State
- ✅ Phase 0 skeleton: FastAPI + SQLModel + SQLite,
run/sleep/weighttables, 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