Identity & policy
Cloudflare resolves sessions, OAuth grants, client JWTs, routing and access policy. Public clients never need direct access to Intervals credentials.
Technical design
One architecture. Multiple interfaces.
Montis separates identity, trust, routing, deterministic computation, semantic contracts and interface rendering into explicit layers. Each layer has one responsibility and a defined authority boundary.
Intervals.icu is the data authority. Cloudflare is the public trust boundary. Railway performs deterministic computation. LLMs consume governed output; they do not redefine it.
URF v5.1
Cloudflare Edge Services
Railway deterministic compute
Shared identity resolution
REST + MCP + App clients
Architecture model
Separate authority before scaling capability.
The platform is designed so that identity, data access, computation and presentation can evolve independently without one layer silently taking control of another.
Intervals.icu authority
Athlete activity, wellness, calendar and training data originate from the connected Intervals.icu account and remain the canonical data source.
Railway execution
Python executes validation, aggregation, enforcement and semantic serialization through the Unified Reporting Framework.
Tool-driven clients
Browser, Gemini App, ChatGPT, Claude, Codex and direct API clients consume the same execution layer through different access wrappers.
The interface can change without changing the execution truth.
This is the central technical principle behind Montis: the user experience is replaceable; the identity, computation and semantic contracts are not.
Why this architecture is different
Data access is not coaching intelligence.
Giving an AI model direct access to Intervals.icu exposes useful data, but it still leaves the model to decide what that data means. Montis inserts a governed intelligence layer between athlete data and the language model.
Intervals.icu provides the evidence. Montis determines the coaching
context. AI communicates the governed result.
DIRECT DATA ACCESS
MONTIS
Training load, physiology, performance behaviour, adaptation, phase and event context are resolved by Montis before conversational AI is asked to explain or discuss them. The language model therefore does not begin with an unstructured collection of athlete metrics and invent its own training state.
Intervals.icu → AI
The model receives athlete data and must independently infer its significance, relationships and coaching implications.
Intervals.icu → Montis → AI
Montis validates and resolves the evidence into governed athlete context and coaching decisions before the language model enters the dialogue.
Identity & token resolution
Different clients. One athlete connection.
Browser sessions, ChatGPT OAuth and MCP OAuth use different access wrappers, but each resolves to the same server-side Intervals token record.
Browser / Montis App
montis_session → athlete identity → shared KV token
ChatGPT
Montis GPT JWT → KV key → shared Intervals token
Claude / Codex MCP
MCP JWT → KV key → shared Intervals token
CLI / legacy access
Limited bearer / fallback path where supported
flowchart TB
subgraph Clients["Client access"]
direction TB
A1["Browser / Montis App"]
A2["ChatGPT GPT Actions"]
A3["Claude / Codex MCP"]
A4["CLI / REST client"]
end
subgraph Edge["Cloudflare trust boundary"]
direction TB
B1["Browser session"]
B2["GPT OAuth facade"]
B3["MCP OAuth facade"]
B4["Unified auth resolver"]
B5["Dispatcher / internal tools"]
end
subgraph Store["Server-side state"]
direction TB
C1["SESSIONS"]
C2["MCP_GRANTS"]
C3["INTERVALS_TOKENS
intervals:{athleteId}"] end A1 --> B1 A2 --> B2 A3 --> B3 A4 --> B4 B1 --> C1 B2 --> C2 B3 --> C2 C1 --> B4 C2 --> B4 B4 --> C3 C3 --> B5
intervals:{athleteId}"] end A1 --> B1 A2 --> B2 A3 --> B3 A4 --> B4 B1 --> C1 B2 --> C2 B3 --> C2 C1 --> B4 C2 --> B4 B4 --> C3 C3 --> B5
Unified execution model
Every client converges into the same execution path.
Authentication and interface differ at the edge. Once identity and data access are resolved, requests enter the same dispatcher and deterministic backend.
Client
Browser, Gemini App, ChatGPT, MCP or direct API.
Cloudflare
Identity, OAuth, policy, routing and parameter normalization.
Resolver
Maps client access to the athlete's shared connection record.
Dispatcher
Routes execution into the required report, calendar or athlete tool.
Railway
Runs validation, calculation, enforcement and semantic serialization.
Output
Returns governed semantic JSON for UI or LLM rendering.
Client
→ Cloudflare Services
→ Unified Auth Resolver
→ Dispatcher / Internal Tools
→ Intervals.icu API + Railway Engine
→ Semantic JSON (URF v5.1)
→ Client / LLM Rendering
Production pipeline
The current operational architecture.
Public access is concentrated at Cloudflare. Data retrieval and deterministic report computation are separated from client-specific presentation logic.
flowchart TB
subgraph Clients["Clients"]
direction TB
A1["Browser /app"]
A2["Gemini App"]
A3["ChatGPT GPT Actions"]
A4["Claude / Codex MCP"]
A5["CLI / REST"]
end
subgraph Cloudflare["Cloudflare Services"]
direction TB
subgraph Public["Public routes"]
direction TB
B1["/connect"]
B2["/oauth/*"]
B3["/mcp"]
B4["/run_*"]
B5["/calendar/*"]
B6["/athlete/*"]
B7["/connection/status"]
end
subgraph Runtime["Runtime control"]
direction TB
C1["Unified Auth Resolver"]
C2["Dispatcher / Internal Tools"]
end
subgraph KV["KV"]
direction TB
D1["SESSIONS"]
D2["MCP_GRANTS"]
D3["INTERVALS_TOKENS"]
end
end
subgraph Compute["Backend"]
direction TB
E1["Intervals.icu API"]
E2["Railway
URF v5.1
Tier 0–3"] end subgraph Consumers["Rendering"] direction TB F1["Browser UI"] F2["ChatGPT"] F3["Claude / MCP"] F4["Gemini"] end A1 --> B1 A1 --> B4 A2 --> B4 A3 --> B2 A3 --> B4 A4 --> B3 A5 --> B4 B1 --> D1 B1 --> D3 B2 --> D2 B3 --> D2 B4 --> C1 B5 --> C1 B6 --> C1 B7 --> C1 B3 --> C1 C1 --> D1 C1 --> D2 C1 --> D3 D3 --> C2 C2 --> E1 C2 --> E2 E2 --> F1 E2 --> F2 E2 --> F3 E2 --> F4
URF v5.1
Tier 0–3"] end subgraph Consumers["Rendering"] direction TB F1["Browser UI"] F2["ChatGPT"] F3["Claude / MCP"] F4["Gemini"] end A1 --> B1 A1 --> B4 A2 --> B4 A3 --> B2 A3 --> B4 A4 --> B3 A5 --> B4 B1 --> D1 B1 --> D3 B2 --> D2 B3 --> D2 B4 --> C1 B5 --> C1 B6 --> C1 B7 --> C1 B3 --> C1 C1 --> D1 C1 --> D2 C1 --> D3 D3 --> C2 C2 --> E1 C2 --> E2 E2 --> F1 E2 --> F2 E2 --> F3 E2 --> F4
Cloudflare is the public trust and routing layer. Railway remains the private compute backend.
Public integration surfaces
REST for direct integrations. MCP for tool-capable AI clients.
The same governed coaching engine is exposed through different protocols so that applications and AI clients can use Montis without duplicating backend logic.
Direct HTTP integration
Public REST endpoints provide structured access through Cloudflare while Railway remains private and unreachable as a direct public backend.
Native tool access for AI clients
MCP provides discovery, typed tool execution and public coaching resources for Claude, Codex and other MCP-capable clients without giving the model direct custody of Intervals.icu tokens.
Server URL https://montis.icu/mcp Client ID intervals-mcp Public MCP resources https://github.com/revo2wheels/montis-mcp-resources Local Inspector npx @modelcontextprotocol/inspector Inspector URL http://localhost:6274/#tools
Security model
Tool access and athlete data access are deliberately separate.
MCP or GPT access alone is not sufficient to obtain athlete data. Protected execution must resolve to an authenticated Montis identity and the athlete's server-side Intervals connection.
Athlete data requires a successful authenticated connection to Intervals.icu.
MCP grants determine whether a client may discover and execute Montis tools.
Intervals access and refresh tokens are held in Cloudflare KV, not exposed to LLM prompts.
MCP endpoint URLs, OAuth discovery metadata and the public client identifier are intentionally public.
Client JWTs are validated before protected tool execution can resolve athlete context.
The compute backend is not exposed as the public integration surface.
URF v5.1 execution guarantees
Deterministic computation before conversational rendering.
The technical pipeline validates, filters, derives and serializes the report state before an interface or LLM sees the result.
| Layer | Implementation role | Guarantee |
|---|---|---|
| Prefetch / Edge | Identity resolution, parameter normalization, routing and optional test payloads | Consistent public request handling |
| Tier-0 | Baseline schema and required-column validation | Rejects structurally invalid input before deeper processing |
| Tier-1 | Activity filtering, normalization and numeric consistency | Clean canonical input state |
| Tier-2 | Derived metrics, locked totals and scope enforcement | No silent variance bleed between report windows |
| Tier-3 | Performance, forecast and coaching intelligence modules | Operates on governed upstream outputs |
| Serialization | Single semantic JSON contract | Stable downstream structure and precision |
| Observability | Structured logs at execution boundaries | Traceable audit chain |
Tool & LLM architecture
The model is a client of the system, not the owner of it.
ChatGPT, Claude, Gemini and future clients can all use the same Montis execution layer. Tool schemas and semantic contracts constrain what the model receives and what it is allowed to invoke.
Multiple LLMs
ChatGPT, Claude, Gemini and other clients can share the same backend capability without introducing separate coaching logic.
One execution engine
Cloudflare routes all protected execution into the same dispatcher and Railway engine.
Semantic output
Clients receive structured output rather than raw authority to recompute canonical metrics.
Client / LLM
↓
Cloudflare Services
↓
Unified Auth Resolver
↓
Dispatcher / Internal Tools
↓
Railway Engine
↓
Semantic JSON (URF v5.1)
↓
Read-only rendering / interaction
End-to-end behaviour
Natural language sits on top of a conventional execution chain.
The conversational experience may feel flexible, but the underlying path is explicit and reproducible.
1. A user or client makes a request
For example: run a weekly report, retrieve an activity or inspect calendar state.
2. The request becomes a typed tool or API call
Scope and parameters are explicit rather than inferred from hidden application state.
3. Cloudflare resolves trust and athlete identity
Session, GPT JWT or MCP JWT resolves to the connected athlete record.
4. Railway executes the required deterministic pipeline
Validation, filtering, calculation, enforcement and serialization occur server-side.
5. URF semantic JSON is returned
Context windows and report semantics remain explicit.
6. The interface renders the result
Browser UI or LLM presents the output without becoming the metric authority.
Architectural continuity
Interfaces can evolve without breaking the execution contract.
Direct APIs, MCP, browser features and future clients can change independently while preserving the same backend data authority and URF guarantees.
Core report computation remains centralized rather than duplicated per client.
Tier-0, Tier-1 and Tier-2 contracts remain upstream of all client rendering.
URF v5.1 provides the shared output structure consumed by multiple interfaces.
Intervals.icu remains the canonical athlete data connection.
Execution is headless and can be called from browser, chat, automation or CLI.
ChatGPT, Claude and Gemini do not get different canonical metrics from separate pipelines.
Coaching methodology
Technical Design explains how Montis runs. Science explains how Montis decides.
Performance Intelligence, ESPE, ADE, phase governance and the physiology behind the coaching pipeline are documented separately so this page can stay focused on architecture.