Unified Prefetch Architecture — v5.1 Design

The Coach GPT App now runs on a unified prefetch architecture that separates data retrieval, normalization, and semantic report generation across Cloudflare and Railway. This ensures deterministic output, fixed schema contracts, and verifiable data lineage from Intervals.icu.

⚙️ Current Operational Pipeline

┌──────────────────────────────┐
│        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  │
│  • 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.

🧩 Architecture Guarantees

Area	Implementation	Guarantee
Prefetch Flow	Cloudflare normalizes date params and injects optional test payloads	Safe staging tests without real data
Execution Model	Python execution on Railway (FastAPI + Pandas)	Deterministic, audited output
Tier-0 Validation	Baseline column checks (`moving_time`, `distance`, etc.)	No schema drift or missing fields
Tier-1 Audit	Filters invalid / null activities, computes daily summaries	Enforced numeric consistency
Tier-2 Enforcement	Lock totals, enforce logical consistency	No variance bleed between scopes
Serialization	Single-pass semantic JSON (no float loss)	Stable numeric precision
Observability	Structured logs at all Tier boundaries	Traceable audit chain (light→full→wellness)
Schema Version	URF v5.1 unified contracts	Cross-version compatibility with GPT tool API

📬 Contact

For integration, customization, or coaching inquiries, connect via GitHub link below or DM via Intervals.icu DM and contribute in Intervals.icu Forum.

github.com/revo2wheels

Built with ❤️ for endurance athletes — by Clive King.
Powered by Intervals.icu, Cloudflare and the Railway Engine.