# 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