An application for planning a complete training calendar leading up to a chosen target race.
The user selects a goal (e.g., marathon or 32 km trail run / D+2100), and the application generates
a plan "top-down" — working backward from race date — selecting phases, volume, paces, and
key workouts based on creator questionnaire answers and (optionally) analysis of previous training.
The plan is evidence-based: every methodological rule comes from a verified knowledge base
in docs/knowledge-running/. A second discipline,
pool freediving (dynamic apnea), is also wired into the engine from its own knowledge base
in docs/knowledge-dive/. A standalone, documentation-only
knowledge base for docs/knowledge-cycling/ (road cycling)
also exists but is not yet wired into the engine.
Status: in development. The knowledge base, the deterministic rule engine (running + trail + freediving), the ASP.NET Core Web API, relational persistence (SQLite / EF Core), and the React Native / Expo frontend are all implemented and tested. LLM integration and Strava/Garmin import are still ahead. This document describes the product vision and the current technical direction.
- Select goal — distance and race date. Supported: 5 km, 10 km, half-marathon, marathon, trail / mountain running, and pool freediving (dynamic apnea, DYN/DYNB).
- Creator questionnaire + training analysis — the application asks questions (level, frequency, PRs, injuries) and/or analyzes previous training to determine training zones (VDOT / threshold) and starting point.
- Calendar generation — a complete plan is generated week by week: phases (Base → Build → Peak → Taper), volume progression, intensity distribution, long runs, key workouts, strength, and tune-up races.
- Auto-regulation — the plan adapts to readiness and data (RPE, sleep, later HRV/heart rate): it reduces intensity or shifts key workouts, never automatically cancels a session.
The result resembles "golden output" from docs/knowledge-running/example-plans.md
(5k/10k/half-marathon/marathon plans and 32 km trail D+2100).
- Distances: full running range (5k, 10k, HM, marathon) and mountain/trail from the start.
- Training data: manual entry (race results, RPE, sleep). Strava/Garmin integrations (auto-import, HRV/readiness) are a later phase, not MVP.
- Application model: web-based, multi-user (accounts), cloud-hosted.
Goal + questionnaire answers/history ─► Rule engine (deterministic) ─► Training plan
▲ │
│ validation of hard constraints │
knowledge base (docs/knowledge-running) ▼
▲ LLM: questionnaire,
└───────── explanations ◄─── decision translation,
edge-case handling
- Rule engine generates and validates a plan deterministically according to rules from the knowledge base — it is repeatable and testable 1:1 against reference plans.
- LLM (e.g., Anthropic Claude) runs the questionnaire, explains decisions ("why this taper / these paces") and handles nuance — but cannot violate hard engine constraints (progression limits, taper, conflict rules). This principle is explicitly stated in the core specification.
The application should be extensible to triathlon (and other endurance sports), so we are
designing the domain model as sport-agnostic from the start. Freediving already proves this:
it was added as a third IDisciplineModule (metric = breath-hold swim meters) without touching
the generator loop.
- Discipline as a first-class abstraction (road running, trail, pool freediving today; swimming/cycling in the future) — with its own training zones, metrics, and session types.
- Swappable metrics: the core knows km+pace (road), time+D+ (mountains), meters+breath-hold (freediving), and in the future distance/power (cycling), pace/100 m (swimming) — without rewriting the engine.
- PeriodizationStrategy and constraints as strategies/plugins, not hard-coded logic.
- Distance extensions (HM/marathon, mountains) today only parametrize the core — the same pattern will support multisport.
| Layer | Technology |
|---|---|
| Frontend | React Native / Expo — goal creator, calendar view, plan editing and preview |
| Backend | C# / ASP.NET Core Minimal API — planning engine, auto-regulation, plan library, profile, readiness |
| Engine | Deterministic rule module (domain layer), tested against golden output and invariants |
| LLM | Integration with language model for questionnaire and explanations (planned; optional, constrained by engine) |
| Data | Relational database via EF Core — SQLite today (swappable to PostgreSQL by changing one registration) |
| Auth | User accounts (proposed: ASP.NET Core Identity + JWT) — not yet implemented |
| Integrations (later phase) | Strava/Garmin via OAuth2 — training import, HRV/RHR |
Layers marked "proposed" / "planned" are sensible defaults not yet built and can still change.
Sport-planner/
├─ README.md ← this document (vision + technical direction)
├─ main_knowledge.md ← orientation map: how code, knowledge, and decisions connect
├─ docs/
│ ├─ knowledge-running/ ← KNOWLEDGE BASE + engine spec (source of truth, wired in)
│ │ ├─ README.md ← index: how to navigate knowledge
│ │ ├─ running-knowledge.md ← foundation + road 5k→marathon (evidence levels A/B/C)
│ │ ├─ mountain-running-knowledge.md ← mountain/trail differences
│ │ ├─ quality-training.md · mountain-training.md ← workout catalogs
│ │ ├─ spec-engine-core.md · spec-hm-marathon.md · spec-mountain.md · spec-workout-catalog.md
│ │ └─ example-plans.md ← reference plans (golden output)
│ ├─ knowledge-dive/ ← freediving knowledge base (wired into the engine)
│ ├─ knowledge-cycling/ ← road-cycling knowledge base (documentation-only, not wired in)
│ ├─ engine-architecture.md ← backend architecture (pipeline, ports, versions 1→3)
│ ├─ contract-planrequest.md ← engine input contract (creator's goal)
│ └─ architecture-review.md ← architecture review (gaps, decisions)
├─ SportPlanner.slnx ← .NET 10 solution
├─ src/
│ ├─ SportPlanner.Domain/ ← domain core: model, PlanRequest, engine (road/trail/apnea),
│ │ invariants, DecisionLog
│ ├─ SportPlanner.Application/ ← use-cases (feature slices): generate + replan, conflict policy
│ ├─ SportPlanner.Api/ ← ASP.NET Core Minimal API: endpoints, DTO contracts, mapping
│ ├─ SportPlanner.Infrastructure/ ← EF Core persistence (SQLite): plans, profile, readiness
│ └─ web/ ← React Native / Expo frontend (creator, calendar, plan view)
└─ tests/
├─ SportPlanner.Domain.Tests/ ← golden (characterization) + property-based (FsCheck)
└─ SportPlanner.Api.Tests/ ← API endpoints + persistence (plan library, profile, readiness)
docs/knowledge-running/anddocs/knowledge-dive/are the source of truth for methodology: what we know, where from (research + forums), with evidence levels. The engine must align with them.docs/(outside theknowledge-*folders) documents the application itself (architecture, API, ADR/decisions). Seemain_knowledge.mdfor the code↔knowledge map.
- Evidence-based: methodological decisions come from
docs/knowledge-running/; new knowledge is added there with evidence level and source. - Layer separation: knowledge (what we know) ≠ specification (how the engine works) ≠ examples (golden output) ≠ application documentation.
- Conservative and safe: engine does not violate hard progression limits; auto-regulation reduces/shifts, never cancels; time prediction gives ranges, not false certainty.
- Knowledge foundation — ✅ done (
docs/knowledge-running/,docs/knowledge-dive/). - Domain model + rule engine (sport-agnostic) — ✅ done: road + trail + freediving, validated against golden output and invariants.
- API + frontend + persistence — ✅ done: goal creator, calendar, plan library, manual training entry, readiness/auto-regulation on RPE/sleep (SQLite / EF Core).
- LLM — questionnaire and decision explanations (next).
- Integrations — Strava/Garmin (auto-import, HRV/readiness).
- Multisport — triathlon extension based on the sport-agnostic core.