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

Status: Active • PI v1.61 • ESPE v1.2 • ADE v2.21 • Deterministic • Production

The Coaching Intelligence Pipeline operates on validated Tier-1 and Tier-2 outputs. It does not recompute canonical metrics. Tier-3 models capability under stress, ESPE evaluates adaptation direction, and ADE produces the operational decision before phase and event governance determine the final coaching instruction.

VALIDATED TIER-1 / TIER-2 OUTPUTS
                │
                ▼
Performance Intelligence — PI v1.61
WDRM / ISDM / NDLI
                │
                ▼
Training State
load_accepting / recovery_priority
                │
                ▼
Energy System Progression — ESPE v1.2
Power-curve adaptation state
                │
                ▼
ADE v2.21 BASE DECISION — CAN
Operational capacity and risk
                │
                ▼
PHASE + EVENT GOVERNANCE — SHOULD
Recovery, build, taper and event-form control
                │
                ▼
SEMANTIC OUTPUT
Actions / Guidance / Alignment / Event Context
                │
                ▼
LLM RENDERING
Read-only interpretation

⚙️ Stage 1 — Performance Intelligence

Performance Intelligence evaluates how fitness is expressed under current stress.

• WDRM — W′ depletion depth, repeated deep-depletion exposure, and joules above FTP.
• ISDM — activity-level durability using decoupling, drift-session count, and long-session exposure.
• NDLI — high-intensity exposure and density proxies using joules above FTP, intensity factor, efficiency, and variability.

Weekly reports use the 7-day FULL dataset. Season and Summary reports use the 90-day LIGHT dataset with a 7-day FULL acute overlay.

PI does not directly measure CNS fatigue, W′ recovery between efforts, or stream-level late-session power decay.

🧠 Stage 2 — Training State

Montis combines load, wellness, forecast, and Performance Intelligence into a consolidated Training State.

• CTL / ATL / TSB
• HRV ratio and recovery context
• Future fatigue classification
• WDRM exposure
• Durability state
• NDLI intensity exposure

ADE consumes two operational states:

load_accepting
recovery_priority

📈 Stage 3 — ESPE v1.2

ESPE evaluates power-curve progression using two normalized comparison windows, normally equal rolling windows of approximately 84 days.

ESPE also exposes CP, W′, pMax, FTP, regression slope, regression R², curve quality, curve profile, plateau state, adaptation bias, and adaptation state.

When no previous comparison window exists, ESPE returns a baseline state rather than inventing progression.

🎯 Stage 4 — ADE v2.21 Base Decision

ADE determines what the athlete can tolerate now.

It consumes the governed operational state, forecast fatigue, load trend, HRV ratio, ESPE adaptation state, nutrition context, and target-event context.

ADE produces a pre-governance score and directive. It does not directly rewrite workouts or automatically insert calendar events.

🧭 Stage 5 — Phase and Event Governance

Phase and event governance determine what the athlete should do.

• Current and projected phase
• Recovery or deload requirement
• Planned load direction
• Taper state
• Event TSB against target range
• Controlled sharpening when projected form is too fresh

Recovery and Deload share a recovery bucket. Taper remains separate because event form can justify selective intensity preservation or sharpening.

Can: ADE operational directive
Should: governed phase and event action

📦 Final Semantic Output

performance_intelligence
energy_system_progression
actions
training_guidance
decision_context
phase_alignment
event_targets
future_forecast

Final ADE resolution is classified as:

• honoured
• honoured_with_sharpening
• overridden_by_phase
• historical_only

The LLM renders this governed output. It does not compute metrics, replace classifications, or invent a competing coaching directive.