Montis.icu Unified Prefetch Architecture — v5.1 Design

The Montis.icu Coach App operates on an 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 • 🔵 Tool & LLM

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 — Cloudflare Services handle identity resolution, OAuth facades, sessions, grants, routing, and policy. Railway performs deterministic data ingestion, validation, aggregation, and semantic serialization (URF v5.1). Canonical outputs remain immutable.
• 🟠 Coaching Intelligence Pipeline — Uses validated URF outputs for Tier-3 structural performance modelling, progression analysis, phase governance, and deterministic Adaptive Decision Engine prescription logic. It never mutates Tier-1 or Tier-2 metrics.
• 🔵 Tool & LLM Architecture — ChatGPT, MCP, Gemini App, browser app, and CLI resolve through Cloudflare Services. Client wrappers resolve to the shared Montis Intervals connection record where required. LLMs render and converse through tools 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.

🔐 Identity & Token Resolution

Montis resolves athlete identity at runtime through client access wrappers: browser session, ChatGPT JWT, MCP JWT, or a limited legacy fallback. The primary data connection is the shared server-side KV token record.

Browser session, ChatGPT JWT, and MCP JWT resolve to the shared KV token record.
Intervals access tokens remain server-side in Cloudflare KV.

🔑 Separation of Concerns

• Execution access → MCP /run_*
• Data access → OAuth token (KV or direct)

MCP grants control tool execution only.
OAuth tokens control access to athlete data.

⚙️ Unified Execution Model

Montis.icu operates a multi-entry, shared-token execution architecture. Tool execution and athlete identity are resolved independently at runtime.

Client
  → Cloudflare Services
    → Unified Auth Resolver
      → Dispatcher / Internal Tools
        → Intervals API + Railway Engine
          → Semantic JSON (URF v5.1)
            → LLM Rendering Layer

⚙️ Runtime Token Resolution

if (valid_gpt_jwt_with_kv_key) {
  load shared Intervals token from KV
} else if (valid_mcp_jwt_with_kv_key) {
  load shared Intervals token from KV
} else if (valid_browser_session) {
  resolve athlete_id and load shared Intervals token from KV
} else if (legacy_bearer_or_ICU_OAUTH) {
  use fallback token path
} else {
  return 401
}

This logic applies uniformly across:

• /run_* report endpoints
• /calendar/* calendar endpoints
• /athlete/* athlete data endpoints
• /connection/status diagnostics
• /mcp tool calls

🧩 Separation of Concerns

Tool access does not equal athlete data access.
Protected data execution requires resolution to the shared Intervals KV token record.

🧠 Execution Patterns

Browser / Gemini App:
  Client → montis_session → KV → Intervals

ChatGPT:
  ChatGPT → Montis GPT JWT → kv_key → KV → Intervals

MCP:
  Claude / Codex → MCP JWT → kv_key → KV → Intervals

CLI / Legacy:
  Client → Worker endpoint → Bearer or KV fallback → Intervals

All paths converge into the same dispatcher and produce identical outputs.

📘 Public API & MCP Documentation

Montis exposes two public integration surfaces: a REST/OpenAPI interface for direct HTTP integrations and a Model Context Protocol (MCP) interface for AI assistants and tool clients.

Railway remains a private compute backend. Public access is provided exclusively through Cloudflare Worker routes.

🔌 MCP Endpoint

Server URL
https://montis.icu/mcp

Client ID
intervals-mcp

Local MCP Inspector
npx @modelcontextprotocol/inspector

Inspector URL
http://localhost:6274/#tools

🔐 Security Model

• MCP endpoint URLs and OAuth discovery metadata are public by design.
• The OAuth client identifier (intervals-mcp) is public and not a secret.
• Access to athlete data requires successful OAuth authentication.
• Bearer tokens are validated before tool execution.
• Intervals.icu access tokens remain server-side and are never exposed through MCP.
• MCP controls tool access; OAuth controls athlete data access.

⚙️ Current Operational Pipeline (Production)

Status: Live • Used in production • Backward compatible

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

🧩 Current Architecture Guarantees

🧠 Unified Tool & LLM Architecture

⚙️ Execution Flow

Client / LLM
    ↓
Cloudflare Services
    • Token Resolver (GPT JWT / MCP JWT / browser session → KV)
    • Routing
    ↓
Dispatcher (Internal Tools)
    ↓
Railway Engine (Tier 0–3)
    ↓
Intervals API (Data)
    ↓
Semantic JSON (URF v5.1)
    ↓
LLM Rendering Layer (Read-only, tool-driven)

🔑 Key Properties

• Single execution path — all clients use the same dispatcher
• Shared identity resolution — browser session, GPT JWT, and MCP JWT all resolve to KV
• No recomputation in LLMs
• Deterministic outputs across all interfaces

⚠️ Important Clarification

• MCP controls tool access
• OAuth controls data access
• ChatGPT uses a Montis OAuth facade and receives a Montis GPT JWT

🔑 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.
• Intervals tokens remain server-side in Cloudflare KV
  Client wrappers resolve to the shared token record without exposing Intervals tokens to LLM 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 a tool call (direct or MCP)
   • Strongly typed inputs
   • Explicit report scope (weekly / season / activity)
3. Cloudflare Services handle 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.

Every decision is rule-based, auditable, and reproducible — never guessed or generated.

🔁 Architectural Continuity

The system evolves toward a unified tool-based architecture (direct + MCP), without changing execution guarantees. 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.

🧠 Montis Intelligence Stack

From raw training load to adaptive coaching decisions — a closed-loop performance system.

🧠 Coaching Intelligence Pipeline (Performance Layer)

Status: Active (v5 / ADE v2) • Rule-based • Closed-loop • Production

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 executes deterministic training decisions.

Tier-3 now operates as a closed-loop system with hierarchical control: performance intelligence drives prescription, but phase governance can override execution.

CANONICAL SEMANTIC DATA (URF v5.1)
                │
                ▼
Tier-3A: Stress Intelligence (PI)
(WDRM / ISDM / NDLI)
                │
                ▼
Tier-3B: Progression Intelligence
ESPE v1 — Power Curve Adaptation (ACTIVE)
                │
                ▼
Tier-3C: System Modeling
(PI + ESPE synthesis)
                │
                ▼
ADE v2 — Adaptive Decision Engine
(Operational Layer — metrics driven)
                │
                ▼
PHASE GOVERNANCE LAYER (Strategic Override)
(required_phase enforcement)
                │
                ▼
COACHING SEMANTIC LAYER (v5)
                │
                ▼
Final Structured Report

🔍 Stage 1 — Stress Intelligence (PI)

Evaluates how the athlete expresses 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 — Active)

Tracks energy system adaptation using deterministic power curve comparison.

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

Answers: “Is current training producing adaptation?”

🧬 Stage 3 — System Modeling

Combines stress signals (PI) and progression signals (ESPE) into a unified physiological state model.

• Energy system balance
• Durability gradient
• Adaptation bias
• Plateau detection

This stage defines system capability and constraints.

🧭 Stage 4 — ADE v2 (Operational Decision Layer)

Executes rule-based training adjustments based on current physiological state.

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

This layer answers: “What can the athlete handle right now?”

🧭 Stage 5 — Phase Governance (Strategic Override Layer)

Enforces mesocycle intent over short-term optimisation.

Critical rule:

IF:
  required_phase != operational_state
THEN:
  override ADE decision

This layer answers: “What should the athlete be doing now?”

• Prevents fatigue accumulation drift
• Forces recovery / taper when required
• Ends blocks when adaptation saturates

Hierarchy:
Phase (strategy) > ADE (execution)

🧠 Training State Model (ADE v2)

Operational States:
  load_progression
  stable_load
  absorption_required
  recovery_priority

These states define execution capacity, but do not override phase intent.

📦 Coaching Semantic Output (v5)

adaptive_layer:
  operational_state
  required_phase
  phase_alignment
  resolution
  adaptation_focus
  prescription_adjustment

The system supports:

• Athlete Mode — Clear directive
• Coach Mode — Full traceability

Complexity is abstracted in Athlete Mode, but fully accessible in Coach Mode. The system hides complexity — it never hides transparency.