Soigneur FHIR Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Data model

Data model

This page walks the FHIR R4 data model resource-by-resource. It graduates from docs/plan-maf-azure/04-data-model.md (how resources reference each other) and 05-terminology.md (the code systems). The Artifacts index has the generated StructureDefinitions; this page explains how they fit together.

Everything is FHIR R4 on Fire Arrow (ADR 0001). The athlete owns their record; the coach never writes Patient (04 §15.1). All athlete-facing metric labels are trademark-safe (Load / Weighted Power / Intensity / Fitness / Fatigue / Form); the cc-* codes are internal machine keys.

The athlete

• Soigneur Athlete (Patient) — gender and birthDate carry the sex and age demographic axes; a timezone extension drives athlete-local scheduling. At least one provider identifier (the cc-provider system) ties the record to imported provider data.

Training data

• Activity Group Observation — a ride or strength session as an Observation Activity Group (HL7 Physical Activity IG, code 73985-4), not a Procedure (ADR 0002). Per-metric values hang off it via hasMember, the raw file via derivedFrom → Binary, and adherence via basedOn → the CarePlan / RequestGroup it was prescribed under.
• Activity Measure Observation — one per-metric member (Load, Weighted Power, Intensity, average/max HR, decoupling, …). Summaries are computed from the rendered stream with the same production math (core.metrics), so a summary can never disagree with its stream.
• Wellness Observation — a per-day wellness or derived value (weight, RHR, HRV, sleep, or a derived Fitness / Fatigue / Form / eFTP value).
• FTP-family Observation — an FTP / eFTP / CP value. method is required (cc-inv-ftp-method) so an accepted/set value is distinguishable from an estimate.

The coaching frame and profile

• Coaching Frame (Composition) — the coaching frame as a Composition split into an immutable Core and an editable Live layer (ADR 0003).
• Profile Questionnaires / Responses — the athlete profile has three write-authority layers — invariant / live / derived (ADR 0004). The invariant layer is the sole trigger for a Frame Core re-derive.

Plans and outcomes

• Training Plan (CarePlan) — a phase-scoped plan (intent = plan) with strategy / scheduling-mode / coach-managed extensions. A phase must not exceed 18 weeks (cc-inv-plan-max-18wk; warn > 12).
• Per-day Workout (RequestGroup) — the instantiated daily prescription. Targets are stored relative (preferably %FTP) and resolved to watts at push time.
• Outcome Report (DiagnosticReport) — each plan/experiment ends in a DiagnosticReport (ADR 0009).

Preferences

• Athlete Preferences (Basic) — the athlete's engine/scheduling tunables (PMC time constants, deviation thresholds, gap-fill window, scheduling mode, availability ceiling, briefing time), modeled as a profiled Basic (ADR 0021). These are eval-realism tunables, not numeric coaching thresholds (which live in the corpus / frame, 13 §2.5).

Sex-aware health axes

The simulator (below) exercises two sex-asymmetric mechanisms the coach must reason about:

• Ferritin Observation (LOINC 24373-3) — the marker for the hidden iron-deficiency sub-phenotype: a plateau/fatigue that mimics overreach but needs iron screening, not rest.
• Amenorrhoea Condition (SNOMED) — the RED-S / low-energy-availability sentinel under the female-athlete axis.

Provenance — imported vs ours

Imported provider data carries a provider Provenance (download/translate, 04 13/13/Device. Skills that reason about data provenance and sufficiency (cold-start vs veteran) can therefore be tested honestly.

Worked examples (simulator fixtures)

The IG's example Instances are lifted from SoigneurSynth, the physiological athlete simulator (ADR 0021), so every profile is exercised against real generated data. Two phenotype exemplars are machine-checked here:

• hidden iron deficiency (female) — synth-iron-01: FTP stalls while ferritin falls and overreach debt stays low.
• overreach decline (male) — synth-overreach-01: observable Fitness keeps rising while true FTP has already peaked and turned down — the trap the coach must catch.

These exemplars double as eval fixtures (08 §H); the full generated cohort is published as a separate versioned artifact.