Files
obsidian-vault/sportnote-roadmap.md

4.5 KiB
Raw Permalink Blame History

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.