Montis.icu Unified Prefetch Architecture — v5.1 Design

The Montis.icu Coach App operates on a authority-driven architecture separating measurement, interpretation, prescription, and interface.

Data integrity originates from Intervals.icu, computation executes in Railway (python), and conversational rendering never alters canonical truth.

🧠 Strategy • 🟢 Technical • 🟠 Coaching • 🔵 Future

The system is intentionally divided into independent architectural layers, each with a single responsibility and defined authority.

• 🧠 Strategy & Philosophy — Governing architectural doctrine. Defines authority boundaries and non-negotiable contracts for interpretation.
• 🟢 Technical Pipeline - Operational Architecture — Deterministic data ingestion, validation, aggregation, and semantic serialization (URF v5.1). Immutable canonical outputs.
• 🟠 Coaching Intelligence Pipeline — Structural performance modelling (Tier-3), progression analysis, and deterministic adaptive prescription logic.
• 🔵 Future Technical Pipeline Architecture — Model-agnostic conversational layer using MCP tools. Renders insights without computing or mutating metrics.

This separation enforces:

• Measurement Integrity
• Transparent Decision Intelligence
• Interface Abstraction Without Authority

Conversational AI is a rendering layer — never a computational authority.

🧠 System Strategy & Architectural Philosophy

The Montis.icu Coach App is engineered around strict authority separation. No layer may override or recompute another layer’s outputs.

🔒 Core Architectural Contract

Coaching logic never mutates canonical metrics.
Tier-1 and Tier-2 outputs are immutable and remain the single source of performance truth.

• Measurement is deterministic and audited.
• Interpretation is rule-based and traceable.
• Prescription executes via a deterministic state engine.
• LLMs render outcomes but never compute, infer, or adjust metrics.

This prevents metric drift, silent recomputation, probabilistic coaching artifacts, and black-box behavior.

🧱 Responsibility Separation Model

Measurement    → Technical Pipeline (Tier-0 / Tier-1 / Tier-2)
Interpretation → Coaching Pipeline (Tier-3 Intelligence)
Prescription   → Adaptive Decision Engine (Deterministic Rules)
Interface      → LLM Rendering Layer (Read-Only)

No single layer owns more than one responsibility. This structure enables auditability, stateless execution, and predictable system evolution.

🎯 Strategic Positioning

Unlike heuristic AI dashboards or machine-learning coaching engines, this system does not invent, infer, or probabilistically manipulate performance metrics.

• No hidden state
• No probabilistic coaching inference
• No language-model metric computation
• No silent threshold adjustment

The result is a deterministic performance intelligence platform — not a black-box AI coach.

⚙️ Current Operational Pipeline (Production)

Status: Live • Used in production • Backward compatible

┌──────────────────────────────┐
│        ChatGPT / CLI App     │
│  (Tool invocation layer)     │
└─────────────┬────────────────┘
              │  HTTPS tool call
              ▼
┌──────────────────────────────────────────────┐
│          Cloudflare Worker (Edge)            │
│  • Auth + routing proxy                      │
│  • Handles start/end normalization           │
│  • Prefetches Intervals data → JSON context  │
└─────────────┬────────────────────────────────┘
              ▼
┌──────────────────────────────────────────────┐
│         Railway Backend (FastAPI)            │
│  • Tier-0: Prefetch normalization            │
│     - DataFrame coercion + baseline columns  │
│     - Empty-source detection + AuditHalt     │
│  • Tier-1: Activity & wellness validation    │
│     - moving_time filtering, zero-checks     │
│  • Tier-2: Aggregation + enforcement         │
│     - Totals reconciliation, variance checks │
│  • Tier-3: Forecast, PI and ESPE             │
│     - Advanced Coaching                      │
│  • Outputs URF v5.1 Semantic JSON            │
└─────────────┬────────────────────────────────┘
              ▼
┌──────────────────────────────┐
│     Intervals.icu API        │
│   (authoritative source)     │
└──────────────────────────────┘

🔄 Cloudflare handles authentication, routing, and optional synthetic testing.
🚉 Railway performs full computation, validation, and serialization.

🧩 Current Architecture Guarantees

🧠 Future Technical Pipeline

⚙️ Future Operational Pipeline

Status: Planned • Incremental rollout • No breaking changes

🧭 System Diagram

┌────────────────────┐
│  Human / LLM Agent │
│  (Chat, Voice, AI) │
└─────────┬──────────┘
          │  Natural Language
          ▼
┌──────────────────────────────┐
│ MCP Tool Interface (Standard)│
│ • Typed tool contracts       │
│ • No UI state                │
│ • Multi-LLM compatible       │
└─────────┬────────────────────┘
          │ MCP call
          ▼
┌──────────────────────────────┐
│ Cloudflare Edge (OAuth + MCP)│
│ • OAuth token handling       │
│ • Scope enforcement          │
│ • Rate limiting              │
│ • Request normalization      │
└─────────┬────────────────────┘
          │ Authenticated request
          ▼
┌──────────────────────────────┐
│ Railway Execution Layer      │
│ (FastAPI + Pandas)           │
│ • Tier-0 validation          │
│ • Tier-1 audit               │
│ • Tier-2 enforcement         │
│ • Tier-3 Methodology         │
│ • Deterministic computation  │
└─────────┬────────────────────┘
          │ Canonical queries
          ▼
┌──────────────────────────────┐
│ Intervals.icu APIs           │
│ • Activities (7d / 90d)      │
│ • Intervals & FIT-derived    │
└─────────┬────────────────────┘
          │ Structured data
          ▼
┌──────────────────────────────┐
│ Semantic JSON (URF v5.1)     │
│ • Explicit context windows   │
│ • Locked totals              │
│ • No recomputation allowed   │
└─────────┬────────────────────┘
          │ Read-only
          ▼
┌──────────────────────────────┐
│ LLM Rendering / Reasoning    │
│ • Descriptive only           │
│ • Coach-like narrative       │
│ • No metric invention        │
└──────────────────────────────┘

🔄 Cloudflare handles authentication, routing, and optional synthetic testing.
🚉 Railway performs full computation, validation, and serialization.
💡Independence from LLMs via MCP

🔑 Key Insights

• There is no UI state
  Every interaction is stateless, reproducible, and tool-driven.
• LLMs never compute metrics
  They only interpret pre-computed, audited semantic JSON.
• OAuth tokens never reach the model
  Cloudflare fully isolates authentication from reasoning.
• Intervals.icu remains the single source of truth
  All metrics originate from published APIs or FIT-derived data.
• Context is explicit, never inferred
  Each metric declares whether it is activity, 7d, 90d, or rolling.
• The system is headless by design
  It works equally well for chat, voice, automation, or background agents.

⚙️ How It Works (End-to-End)

1. User or AI issues a natural-language request
   Example: “Explain my weekly intensity balance and recovery status.”
2. Request is converted into an MCP tool call
   • Strongly typed inputs
   • Explicit report scope (weekly / season / activity)
3. Cloudflare Edge handles trust and policy
   • OAuth token exchange with Intervals.icu
   • Scope validation
   • Rate limiting
   • Parameter normalization
4. Railway executes the computation
   • Tier-0: schema + column validation
   • Tier-1: numeric consistency and filtering
   • Tier-2: locked totals and scope enforcement
   • No cross-window leakage (e.g. weekly ≠ seasonal)
5. Canonical semantic JSON is produced
   • URF v5.1 contract
   • Explicit context windows
   • Deterministic numeric precision
   • No derived ambiguity
6. LLM renders the report
   • Descriptive, coach-like language
   • Anchored strictly to provided semantics
   • No recomputation, guessing, or extrapolation

🧠 Why This Matters

This architecture enables natural language coaching at scale without:

• Dashboards
• Sliders
• Charts
• Hidden state
• Silent recomputation

The result is a system that is:

• Auditable
• Secure
• Model-agnostic
• Future-proof
• Genuinely conversational

Natural language becomes the interface — not the source of truth.

🔁 Architectural Continuity

The future MCP-native architecture does not replace the current system. It formalizes the same guarantees behind a standard tool interface.

• Same Railway execution engine
• Same Tier-0/1/2 enforcement
• Same URF v5.1 semantic contract
• Same Intervals.icu data authority

🎯 Decision Governance

• The Adaptive Decision Engine is the sole prescriptive authority.
• Tier-2 metrics provide diagnostic context.
• Tier-3 synthesizes capability state.
• LLMs never modify, override, or invent recommendations.

🧠 Coaching Intelligence Pipeline (Performance Layer)

Status: Evolutionary (v6+) • Deterministic • Rule-based • No metric recomputation

The Coaching Pipeline operates strictly on validated canonical data produced by the Technical Pipeline. It does not compute raw metrics. It transforms trusted semantic inputs into structured performance intelligence and deterministic training decisions.

CANONICAL SEMANTIC DATA (URF v5.1)
                │
                ▼
Tier-3A: Stress Intelligence
(WDRM / ISDM / NDLI)
                │
                ▼
Tier-3B: Progression Intelligence
ESPE v1 — Power Curve Progression
• Duration anchors (5s / 1m / 5m / 20m / 60m)
• Curve rotation detection
• Endurance vs anaerobic shift
                │
                ▼
Tier-3C: System Modeling (Future)
ESPE v2 — Physiological System Engine
• Glycolytic vs aerobic bias
• Durability gradient
• VO₂ reserve capacity
• Energy system balance score
                │
                ▼
Adaptive Decision Engine (ADE)
                │
                ▼
COACHING SEMANTIC LAYER (v6)
                │
                ▼
Final Structured Report

🔍 Stage 1 — Stress Intelligence

Evaluates how the athlete is expressing training load under fatigue.

• WDRM — Anaerobic repeatability and W′ depletion behavior
• ISDM — Durability and fatigue resistance
• NDLI — Neural load density and intensity clustering

Answers: “Can the athlete tolerate additional stress?”

📈 Stage 2 — Progression Intelligence (ESPE v1)

Tracks energy system progression using power curves and structural signals.

• Endurance (60min trend)
• Threshold (20min trend)
• VO₂ Capacity (5min trend)
• Anaerobic Repeatability (1min + W′ behavior)

Answers: “Is current training producing adaptation?”

🧬 Stage 2B — System Modeling (ESPE v2)

The next evolution of the Energy System Progression Engine extends beyond simple power-duration changes and models the athlete’s physiological system balance.

• Glycolytic vs aerobic bias
• Durability gradient
• VO₂ reserve capacity
• System balance score

This stage transforms curve progression into deeper physiological diagnostics describing how the athlete’s energy systems are adapting to training stimulus.

🧭 Stage 3 — Adaptive Decision Engine (ADE)

Applies deterministic, rule-based logic to produce structured prescription guidance.

IF:
  Neural density high
  AND Repeatability decreasing
  AND FatigueTrend elevated
THEN:
  Reduce VO2 duration 15%
  Convert tempo → endurance
  Insert OFF day

No GPT improvisation. No hidden logic. Rules are executed inside Railway and serialized into the semantic graph.

🧠 Training State Machine

All prescription logic is governed by a deterministic training state model. The system cannot prescribe progression outside the current state.

Training State Machine:
  Stable → Progress
  Dense → Absorb
  Strain → Consolidate
  Overreached → Recover

The state machine governs intensity permission and load progression. It ensures Tier-2 diagnostics cannot override Tier-3 state.

📦 Coaching Semantic Output (v6)

The Coaching Semantic Layer converts structural intelligence into clear, athlete-readable language — without removing analytical depth.

adaptive_layer:
  readiness_state
  progression_state
  neural_state
  durability_state
  prescription_adjustment

The system supports:

• Athlete Mode — Clear readiness, next-step guidance, and actionable adjustments.
• Coach Mode — Full structural diagnostics including WDRM, ESPE, NDLI, thresholds, state transitions, and rule traces.

Complexity is abstracted in Athlete Mode, but fully accessible in Coach Mode.

Any recommendation can be queried for complete technical breakdown — including source metrics, thresholds, trend deltas, and deterministic rule logic.

The system hides complexity — it never hides transparency.