@stuartshay/otel-graphql-types 1.0.0 → 1.0.95

package/schema.graphql

@@ -6,234 +6,1321 @@ scalar DateTime
 # -------------------------------------------------------
 # Common Types
 # -------------------------------------------------------
+"""
+Pagination metadata for paginated list responses.
+"""
 type PaginationInfo {
+  """
+  Total number of items matching the query
+  """
   total: Int!
+  """
+  Maximum number of items per page
+  """
   limit: Int!
+  """
+  Number of items skipped from the start
+  """
   offset: Int!
 }
 
 # -------------------------------------------------------
 # Health
 # -------------------------------------------------------
+"""
+Service health status.
+"""
 type HealthStatus {
+  """
+  Service health status (healthy or unhealthy)
+  """
   status: String!
+  """
+  Application version from VERSION file
+  """
   version: String!
 }
 
+"""
+Service readiness status including database connectivity.
+"""
 type ReadyStatus {
+  """
+  Service readiness status
+  """
   status: String!
+  """
+  Database connection status
+  """
   database: String
+  """
+  Application version from VERSION file
+  """
   version: String
 }
 
 # -------------------------------------------------------
 # Locations (OwnTracks)
 # -------------------------------------------------------
+"""
+GPS location recorded by the OwnTracks mobile app.
+"""
 type Location {
+  """
+  Unique location record identifier
+  """
   id: Int!
+  """
+  OwnTracks device identifier (e.g. iphone_stuart)
+  """
   device_id: String!
+  """
+  Two-character tracker ID set in the OwnTracks app
+  """
   tid: String
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
   latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
   longitude: Float!
+  """
+  Horizontal accuracy of the GPS fix in meters
+  """
   accuracy: Float
+  """
+  Altitude above sea level in meters
+  """
   altitude: Float
+  """
+  Device velocity in km/h at time of report
+  """
   velocity: Float
+  """
+  Device battery level as a percentage (0-100)
+  """
   battery: Int
+  """
+  Battery charging state (0=unknown, 1=unplugged, 2=charging, 3=full)
+  """
   battery_status: Int
+  """
+  Network connection type (w=WiFi, m=mobile)
+  """
   connection_type: String
+  """
+  What triggered this location report (p=ping, c=circular, t=timer)
+  """
   trigger: String
+  """
+  UTC timestamp when the device recorded the location
+  """
   timestamp: DateTime!
+  """
+  UTC timestamp when the record was inserted into the database
+  """
   created_at: String
+  """
+  Short formatted address from reverse geocoding
+  """
+  display_address: String
 }
 
+"""
+Full location detail including the original OwnTracks JSON payload.
+"""
 type LocationDetail {
+  """
+  Unique location record identifier
+  """
   id: Int!
+  """
+  OwnTracks device identifier (e.g. iphone_stuart)
+  """
   device_id: String!
+  """
+  Two-character tracker ID set in the OwnTracks app
+  """
   tid: String
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
   latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
   longitude: Float!
+  """
+  Horizontal accuracy of the GPS fix in meters
+  """
   accuracy: Float
+  """
+  Altitude above sea level in meters
+  """
   altitude: Float
+  """
+  Device velocity in km/h at time of report
+  """
   velocity: Float
+  """
+  Device battery level as a percentage (0-100)
+  """
   battery: Int
+  """
+  Battery charging state (0=unknown, 1=unplugged, 2=charging, 3=full)
+  """
   battery_status: Int
+  """
+  Network connection type (w=WiFi, m=mobile)
+  """
   connection_type: String
+  """
+  What triggered this location report (p=ping, c=circular, t=timer)
+  """
   trigger: String
+  """
+  UTC timestamp when the device recorded the location
+  """
   timestamp: DateTime!
+  """
+  UTC timestamp when the record was inserted into the database
+  """
   created_at: String
+  """
+  Original OwnTracks JSON payload as received from the MQTT broker
+  """
   raw_payload: JSON
+  """
+  Full reverse-geocoded address components from Pelias
+  """
+  address: GeocodedAddress
 }
 
 scalar JSON
 
+# -------------------------------------------------------
+# Geocoding
+# -------------------------------------------------------
+"""
+Reverse-geocoded address components from Pelias.
+"""
+type GeocodedAddress {
+  """
+  Full formatted address label from Pelias
+  """
+  display_address: String
+  """
+  Street name
+  """
+  street: String
+  """
+  House or building number
+  """
+  housenumber: String
+  """
+  Neighbourhood name
+  """
+  neighbourhood: String
+  """
+  City or town
+  """
+  locality: String
+  """
+  State or province
+  """
+  region: String
+  """
+  Country name
+  """
+  country: String
+  """
+  Postal or ZIP code
+  """
+  postalcode: String
+  """
+  Pelias confidence score (0-1)
+  """
+  confidence: Float
+  """
+  Geocoding status: success, no_coverage, error, pending
+  """
+  status: String!
+  """
+  UTC timestamp when geocoding was performed
+  """
+  geocoded_at: String
+}
+
+"""
+Coverage statistics for geocoded location records.
+"""
+type GeocodingStatus {
+  """
+  Total number of OwnTracks location records
+  """
+  total_locations: Int!
+  """
+  Number of locations with a geocoded address (any status)
+  """
+  geocoded: Int!
+  """
+  Number of successfully geocoded locations
+  """
+  success: Int!
+  """
+  Number of locations awaiting geocoding
+  """
+  pending: Int!
+  """
+  Number of locations outside Pelias coverage area
+  """
+  no_coverage: Int!
+  """
+  Number of locations that failed geocoding
+  """
+  errors: Int!
+  """
+  Percentage of locations with a geocoded address
+  """
+  coverage_percent: Float!
+  """
+  Per-source breakdown of geocoding coverage (owntracks, garmin)
+  """
+  by_source: GeocodingStatusBySource!
+}
+
+"""
+Coverage statistics for a single geocoding source (owntracks or garmin).
+"""
+type GeocodingSourceStatus {
+  """
+  Number of successfully geocoded records for this source
+  """
+  success: Int!
+  """
+  Number of records awaiting geocoding for this source
+  """
+  pending: Int!
+  """
+  Number of records outside Pelias coverage area
+  """
+  no_coverage: Int!
+  """
+  Number of records that failed geocoding
+  """
+  errors: Int!
+  """
+  Total number of geocoded_addresses rows for this source
+  """
+  total: Int!
+}
+
+"""
+Per-source breakdown of geocoding coverage.
+"""
+type GeocodingStatusBySource {
+  """
+  Coverage stats for OwnTracks rows
+  """
+  owntracks: GeocodingSourceStatus!
+  """
+  Coverage stats for Garmin rows
+  """
+  garmin: GeocodingSourceStatus!
+  """
+  Total number of Garmin activities (denominator for activity-level coverage)
+  """
+  garmin_activities_total: Int!
+  """
+  Number of Garmin activities that have at least one address row
+  """
+  garmin_activities_geocoded: Int!
+  """
+  Percentage of Garmin activities with at least one geocoded address
+  """
+  garmin_coverage_percent: Float!
+}
+
+"""
+Result of triggering a batch geocoding operation.
+"""
+type GeocodingTriggerResult {
+  """
+  Number of records processed in this batch
+  """
+  processed: Int!
+  """
+  Number of records still awaiting geocoding
+  """
+  remaining: Int!
+  """
+  Number of records skipped via proximity deduplication
+  """
+  skipped_dedup: Int!
+}
+
+"""
+Paginated list of OwnTracks location records.
+"""
 type LocationConnection {
+  """
+  List of location items in the current page
+  """
   items: [Location!]!
+  """
+  Total number of items matching the query
+  """
   total: Int!
+  """
+  Maximum number of items per page
+  """
   limit: Int!
+  """
+  Number of items skipped from the start
+  """
   offset: Int!
 }
 
+"""
+Distinct OwnTracks device identifier.
+"""
 type DeviceInfo {
+  """
+  OwnTracks device identifier
+  """
   device_id: String!
 }
 
+"""
+Aggregate location count with optional filter context.
+"""
 type LocationCount {
+  """
+  Total number of location records matching the filter
+  """
   count: Int!
+  """
+  Date filter applied (YYYY-MM-DD), if any
+  """
   date: String
+  """
+  Device ID filter applied, if any
+  """
   device_id: String
 }
 
+"""
+Earliest and latest timestamps in the locations table.
+"""
+type LocationDateRange {
+  """
+  Earliest location timestamp (ISO 8601)
+  """
+  min_date: DateTime!
+  """
+  Latest location timestamp (ISO 8601)
+  """
+  max_date: DateTime!
+}
+
 # -------------------------------------------------------
 # Garmin
 # -------------------------------------------------------
+"""
+Recording device metadata captured from a Garmin activity's FIT file.
+"""
+type GarminDevice {
+  """
+  Recording device serial number
+  """
+  device_id: Float
+  """
+  Device manufacturer (e.g. garmin)
+  """
+  manufacturer: String
+  """
+  Raw Garmin product enum id from the FIT file (e.g. 4061)
+  """
+  garmin_product: Int
+  """
+  Friendly device model name (e.g. Edge 540 Solar)
+  """
+  model: String
+  """
+  Device firmware/software version (e.g. 31.30)
+  """
+  software_version: String
+}
+
+"""
+Summary of a Garmin Connect activity parsed from a FIT file.
+"""
 type GarminActivity {
+  """
+  Garmin Connect activity identifier
+  """
   activity_id: String!
+  """
+  Primary sport type (e.g. cycling, running)
+  """
   sport: String!
+  """
+  Sub-sport classification (e.g. road, trail)
+  """
   sub_sport: String
+  """
+  Activity start time in UTC
+  """
   start_time: String
+  """
+  Activity end time in UTC
+  """
   end_time: String
+  """
+  Total distance in kilometres
+  """
   distance_km: Float
+  """
+  Active duration in seconds (excludes pauses)
+  """
   duration_seconds: Float
+  """
+  Average heart rate in beats per minute
+  """
   avg_heart_rate: Int
+  """
+  Maximum heart rate in beats per minute
+  """
   max_heart_rate: Int
+  """
+  Whether this activity has usable heart-rate data in summary or track points
+  """
+  hr_available: Boolean!
+  """
+  Minimum heart rate in beats per minute
+  """
+  min_heart_rate: Int
+  """
+  Aerobic training effect score
+  """
+  aerobic_training_effect: Float
+  """
+  Anaerobic training effect score
+  """
+  anaerobic_training_effect: Float
+  """
+  Exercise load score
+  """
+  exercise_load: Int
+  """
+  Average respiration rate in breaths per minute
+  """
+  avg_respiration_rate: Int
+  """
+  Minimum respiration rate in breaths per minute
+  """
+  min_respiration_rate: Int
+  """
+  Maximum respiration rate in breaths per minute
+  """
+  max_respiration_rate: Int
+  """
+  Estimated sweat loss in millilitres
+  """
+  sweat_loss_ml: Int
+  """
+  Moderate intensity minutes
+  """
+  moderate_intensity_minutes: Int
+  """
+  Vigorous intensity minutes
+  """
+  vigorous_intensity_minutes: Int
+  """
+  Total intensity minutes
+  """
+  total_intensity_minutes: Int
+  """
+  Distance over paved surfaces in kilometres
+  """
+  paved_distance_km: Float
+  """
+  Distance over unpaved surfaces in kilometres
+  """
+  unpaved_distance_km: Float
+  """
+  Average cadence in RPM
+  """
   avg_cadence: Int
+  """
+  Maximum cadence in RPM
+  """
   max_cadence: Int
+  """
+  Total activity strokes
+  """
+  total_strokes: Int
+  """
+  Total calories burned
+  """
   calories: Int
+  """
+  Average speed in km/h
+  """
   avg_speed_kmh: Float
+  """
+  Maximum speed in km/h
+  """
   max_speed_kmh: Float
+  """
+  Total elevation gain in meters
+  """
   total_ascent_m: Float
+  """
+  Total elevation loss in meters
+  """
   total_descent_m: Float
+  """
+  Raw total distance in meters from FIT file
+  """
   total_distance: Float
+  """
+  Average pace in minutes per kilometre
+  """
   avg_pace: Float
+  """
+  Device manufacturer (e.g. garmin)
+  """
   device_manufacturer: String
+  """
+  Recording device metadata (manufacturer, model, firmware)
+  """
+  device: GarminDevice
+  """
+  Average ambient temperature in degrees C
+  """
   avg_temperature_c: Int
+  """
+  Minimum ambient temperature in degrees C
+  """
   min_temperature_c: Int
+  """
+  Maximum ambient temperature in degrees C
+  """
   max_temperature_c: Int
+  """
+  Total elapsed time in seconds (includes pauses)
+  """
   total_elapsed_time: Float
+  """
+  Total timer time in seconds (active recording)
+  """
   total_timer_time: Float
+  """
+  UTC timestamp when the record was inserted
+  """
   created_at: String
+  """
+  UTC timestamp when the FIT file was uploaded
+  """
   uploaded_at: String
+  """
+  Number of GPS track points in this activity
+  """
   track_point_count: Int
 }
 
+"""
+Paginated list of Garmin activities.
+"""
 type GarminActivityConnection {
+  """
+  List of Garmin activity items in the current page
+  """
   items: [GarminActivity!]!
+  """
+  Total number of items matching the query
+  """
   total: Int!
+  """
+  Maximum number of items per page
+  """
   limit: Int!
+  """
+  Number of items skipped from the start
+  """
   offset: Int!
 }
 
+"""
+Earliest and latest timestamps in the Garmin activities table.
+"""
+type GarminDateRange {
+  """
+  Earliest Garmin activity timestamp (ISO 8601)
+  """
+  min_date: DateTime!
+  """
+  Latest Garmin activity timestamp (ISO 8601)
+  """
+  max_date: DateTime!
+}
+
+"""
+Individual GPS track point within a Garmin activity.
+"""
 type GarminTrackPoint {
+  """
+  Unique track point record identifier
+  """
   id: Int!
+  """
+  Parent Garmin activity identifier
+  """
   activity_id: String!
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
   latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
   longitude: Float!
+  """
+  UTC timestamp of the track point recording
+  """
   timestamp: DateTime!
+  """
+  Elevation above sea level in meters
+  """
   altitude: Float
+  """
+  Cumulative distance from activity start in km
+  """
   distance_from_start_km: Float
+  """
+  Instantaneous speed in km/h
+  """
   speed_kmh: Float
+  """
+  Heart rate in beats per minute
+  """
   heart_rate: Int
+  """
+  Heart-rate zone index (1-5)
+  """
+  hr_zone: Int
+  """
+  Respiration rate in breaths per minute
+  """
+  respiration_rate: Int
+  """
+  Pedal/step cadence in RPM
+  """
   cadence: Int
+  """
+  Ambient temperature in degrees C
+  """
   temperature_c: Float
+  """
+  Road or terrain type
+  """
+  surface_type: String
+  """
+  Effort classification label
+  """
+  effort_level: String
+  """
+  UTC timestamp when the record was inserted
+  """
   created_at: String
+  """
+  Compact reverse-geocoded address summary, when geocoded
+  """
+  address: GeocodedAddressSummary
 }
 
+"""
+Compact reverse-geocoded address summary embedded in track-point payloads.
+"""
+type GeocodedAddressSummary {
+  """
+  Full formatted address label from Pelias
+  """
+  display_address: String
+  """
+  Street name
+  """
+  street: String
+  """
+  House or building number
+  """
+  housenumber: String
+  """
+  Neighbourhood name
+  """
+  neighbourhood: String
+  """
+  City or town
+  """
+  locality: String
+  """
+  State or province
+  """
+  region: String
+  """
+  Country name
+  """
+  country: String
+  """
+  Postal or ZIP code
+  """
+  postalcode: String
+  """
+  Pelias confidence score (0-1)
+  """
+  confidence: Float
+  """
+  Role of this waypoint within a Garmin activity (start, end, waypoint). Null for OwnTracks records.
+  """
+  waypoint_kind: String
+  """
+  Geocoding status: success, no_coverage, error, pending
+  """
+  status: String!
+  """
+  UTC timestamp when geocoding was performed
+  """
+  geocoded_at: String
+}
+
+"""
+Full reverse-geocoded address attached to a Garmin activity waypoint.
+"""
+type GarminActivityAddress {
+  """
+  garmin_track_points.id this address was geocoded from
+  """
+  track_point_id: Int!
+  """
+  Parent Garmin activity identifier
+  """
+  activity_id: String!
+  """
+  Role of this waypoint within the activity: start, end, or waypoint
+  """
+  waypoint_kind: String!
+  """
+  UTC timestamp of the track point this address was derived from
+  """
+  timestamp: DateTime!
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
+  latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
+  longitude: Float!
+  """
+  Full formatted address label from Pelias
+  """
+  display_address: String
+  """
+  Street name
+  """
+  street: String
+  """
+  House or building number
+  """
+  housenumber: String
+  """
+  Neighbourhood name
+  """
+  neighbourhood: String
+  """
+  City or town
+  """
+  locality: String
+  """
+  State or province
+  """
+  region: String
+  """
+  Country name
+  """
+  country: String
+  """
+  Postal or ZIP code
+  """
+  postalcode: String
+  """
+  Pelias confidence score (0-1)
+  """
+  confidence: Float
+  """
+  Geocoding status: success, no_coverage, error, pending
+  """
+  status: String!
+  """
+  UTC timestamp when geocoding was performed
+  """
+  geocoded_at: String
+}
+
+"""
+Paginated list of Garmin track points.
+"""
 type GarminTrackPointConnection {
+  """
+  List of track point items in the current page
+  """
   items: [GarminTrackPoint!]!
+  """
+  Total number of items matching the query
+  """
   total: Int!
+  """
+  Maximum number of items per page
+  """
   limit: Int!
+  """
+  Number of items skipped from the start
+  """
   offset: Int!
 }
 
+"""
+Sport type with its activity count.
+"""
 type SportInfo {
+  """
+  Sport type name (e.g. cycling, running)
+  """
   sport: String!
+  """
+  Number of activities for this sport
+  """
+  activity_count: Int!
+}
+
+"""
+Lightweight track point optimised for time-series chart rendering.
+"""
+type GarminChartPoint {
+  """
+  UTC timestamp of the data point
+  """
+  timestamp: DateTime!
+  """
+  Elevation above sea level in meters
+  """
+  altitude: Float
+  """
+  Cumulative distance from activity start in km
+  """
+  distance_from_start_km: Float
+  """
+  Instantaneous speed in km/h
+  """
+  speed_kmh: Float
+  """
+  Heart rate in beats per minute
+  """
+  heart_rate: Int
+  """
+  Heart-rate zone index (1-5)
+  """
+  hr_zone: Int
+  """
+  Respiration rate in breaths per minute
+  """
+  respiration_rate: Int
+  """
+  Pedal/step cadence in RPM
+  """
+  cadence: Int
+  """
+  Ambient temperature in degrees C
+  """
+  temperature_c: Float
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
+  latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
+  longitude: Float!
+}
+
+"""
+Aggregated Garmin activity totals for a single time bucket (week, month, or year).
+"""
+type GarminActivityTotal {
+  """
+  Start date of the period bucket (DATE_TRUNC of week/month/year)
+  """
+  period_start: String!
+  """
+  Number of activities in the period
+  """
   activity_count: Int!
+  """
+  Sum of distance in kilometres
+  """
+  total_distance_km: Float
+  """
+  Sum of active duration in seconds (excludes pauses)
+  """
+  total_duration_seconds: Int
+  """
+  Sum of elevation gain in meters
+  """
+  total_ascent_m: Int
+  """
+  Sum of calories burned
+  """
+  total_calories: Int
 }
 
 # -------------------------------------------------------
 # Unified GPS
 # -------------------------------------------------------
+"""
+Single GPS data point from the unified view combining OwnTracks and Garmin sources.
+"""
 type UnifiedGpsPoint {
+  """
+  Data source: 'owntracks' or 'garmin'
+  """
   source: String!
+  """
+  Device or activity identifier from the source
+  """
   identifier: String!
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
   latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
   longitude: Float!
+  """
+  UTC timestamp of the GPS recording
+  """
   timestamp: DateTime!
+  """
+  Horizontal GPS accuracy in meters (OwnTracks only)
+  """
   accuracy: Float
+  """
+  Device battery percentage (OwnTracks only)
+  """
   battery: Int
+  """
+  Instantaneous speed in km/h (Garmin only)
+  """
   speed_kmh: Float
+  """
+  Heart rate in BPM (Garmin only)
+  """
   heart_rate: Int
+  """
+  UTC timestamp when the record was inserted
+  """
   created_at: String
 }
 
+"""
+Paginated list of unified GPS data points.
+"""
 type UnifiedGpsConnection {
+  """
+  List of unified GPS items in the current page
+  """
   items: [UnifiedGpsPoint!]!
+  """
+  Total number of items matching the query
+  """
   total: Int!
+  """
+  Maximum number of items per page
+  """
   limit: Int!
+  """
+  Number of items skipped from the start
+  """
   offset: Int!
 }
 
+"""
+Per-day aggregate combining OwnTracks location stats and Garmin activity metrics.
+"""
 type DailyActivitySummary {
+  """
+  Calendar date in YYYY-MM-DD format
+  """
   activity_date: String
+  """
+  OwnTracks device that reported data for this day
+  """
   owntracks_device: String
+  """
+  Number of OwnTracks GPS points recorded
+  """
   owntracks_points: Int
+  """
+  Lowest device battery percentage observed
+  """
   min_battery: Int
+  """
+  Highest device battery percentage observed
+  """
   max_battery: Int
+  """
+  Mean horizontal GPS accuracy in meters
+  """
   avg_accuracy: Float
+  """
+  Garmin sport type for activities on this day
+  """
   garmin_sport: String
+  """
+  Number of Garmin activities recorded
+  """
   garmin_activities: Int
+  """
+  Combined Garmin activity distance in km
+  """
   total_distance_km: Float
+  """
+  Combined Garmin activity duration in seconds
+  """
   total_duration_seconds: Float
+  """
+  Mean heart rate across Garmin activities in BPM
+  """
   avg_heart_rate: Int
+  """
+  Total calories burned across Garmin activities
+  """
   total_calories: Int
 }
 
+"""
+Paginated list of daily activity summaries.
+"""
+type DailySummaryConnection {
+  """
+  List of daily activity summary items in the current page
+  """
+  items: [DailyActivitySummary!]!
+  """
+  Total number of items matching the query
+  """
+  total: Int!
+  """
+  Maximum number of items per page
+  """
+  limit: Int!
+  """
+  Number of items skipped from the start
+  """
+  offset: Int!
+}
+
+"""
+Earliest and latest activity dates available in the daily activity summary view.
+"""
+type DailySummaryDateRange {
+  """
+  Earliest activity date with daily summary data (YYYY-MM-DD)
+  """
+  min_date: String!
+  """
+  Latest activity date with daily summary data (YYYY-MM-DD)
+  """
+  max_date: String!
+}
+
 # -------------------------------------------------------
 # Reference Locations
 # -------------------------------------------------------
+"""
+Named geographic reference point used for spatial queries (e.g. home, office).
+"""
 type ReferenceLocation {
+  """
+  Unique reference location identifier
+  """
   id: Int!
+  """
+  Short, unique name for the location (e.g. home, office)
+  """
   name: String!
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
   latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
   longitude: Float!
+  """
+  Geofence radius in meters for proximity queries
+  """
   radius_meters: Float!
+  """
+  Optional human-readable description of the location
+  """
   description: String
+  """
+  UTC timestamp when the record was created
+  """
   created_at: String
+  """
+  UTC timestamp when the record was last updated
+  """
   updated_at: String
 }
 
 # -------------------------------------------------------
 # Spatial
 # -------------------------------------------------------
+"""
+GPS point found within a spatial proximity search.
+"""
 type NearbyPoint {
+  """
+  Data source: 'owntracks' or 'garmin'
+  """
   source: String!
+  """
+  Record identifier in the source table
+  """
   id: Int!
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
   latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
   longitude: Float!
+  """
+  Distance from the search center point in meters
+  """
   distance_meters: Float!
+  """
+  UTC timestamp of the GPS recording
+  """
   timestamp: DateTime!
 }
 
+"""
+Geodesic distance calculation result between two geographic points.
+"""
 type DistanceResult {
+  """
+  Geodesic distance between the two points in meters
+  """
   distance_meters: Float!
+  """
+  Origin latitude in decimal degrees
+  """
   from_lat: Float!
+  """
+  Origin longitude in decimal degrees
+  """
   from_lon: Float!
+  """
+  Destination latitude in decimal degrees
+  """
   to_lat: Float!
+  """
+  Destination longitude in decimal degrees
+  """
   to_lon: Float!
 }
 
+"""
+GPS points found within a named reference location's geofence radius.
+"""
 type WithinReferenceResult {
+  """
+  Name of the reference location searched
+  """
   reference_name: String!
+  """
+  Geofence radius used for the search in meters
+  """
   radius_meters: Float!
+  """
+  Number of GPS points found within the radius
+  """
   total_points: Int!
+  """
+  GPS points within the radius, sorted by distance
+  """
   points: [NearbyPoint!]!
 }
 
+"""
+Result payload returned when triggering an on-demand Garmin sync.
+"""
+type GarminSyncTriggerResult {
+  """
+  Sync trigger status (e.g. accepted, conflict, bad_request, error)
+  """
+  status: String!
+  """
+  Human-readable status message from upstream sync service
+  """
+  message: String!
+  """
+  True when a new sync run was accepted and triggered
+  """
+  accepted: Boolean!
+  """
+  UTC timestamp when sync was triggered
+  """
+  triggered_at: String
+  """
+  UTC timestamp when an already-running sync started
+  """
+  started_at: String
+  """
+  Effective sync window in hours
+  """
+  window_hours: Int
+  """
+  Window start timestamp computed by upstream service, when available
+  """
+  window_start: String
+  """
+  Effective lookback value, when provided
+  """
+  lookback: Int
+}
+
 # -------------------------------------------------------
 # Enums
 # -------------------------------------------------------
+"""
+Sort direction for query results.
+"""
 enum SortOrder {
+  """
+  Ascending order (oldest first, A-Z)
+  """
   asc
+  """
+  Descending order (newest first, Z-A)
+  """
   desc
 }
 
@@ -242,89 +1329,395 @@ enum SortOrder {
 # -------------------------------------------------------
 type Query {
   # Health
+  """
+  Get service health status.
+  """
   health: HealthStatus!
+  """
+  Get service readiness status including database connectivity.
+  """
   ready: ReadyStatus!
 
   # Locations
+  """
+  Retrieve a paginated list of OwnTracks location records.
+  """
   locations(
+    """
+    Filter by OwnTracks device identifier
+    """
     device_id: String
+    """
+    Start date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_from: String
+    """
+    End date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_to: String
+    """
+    Maximum number of items to return per page
+    """
     limit: Int
+    """
+    Number of items to skip for pagination
+    """
     offset: Int
+    """
+    Field name to sort by
+    """
     sort: String
+    """
+    Sort direction
+    """
     order: SortOrder
   ): LocationConnection!
 
-  location(id: Int!): LocationDetail
+  """
+  Retrieve a single location by its ID, including raw payload.
+  """
+  location(
+    """
+    Unique location record identifier
+    """
+    id: Int!
+  ): LocationDetail
 
+  """
+  List all distinct OwnTracks device identifiers.
+  """
   devices: [DeviceInfo!]!
 
-  locationCount(date: String, device_id: String): LocationCount!
+  """
+  Get aggregate count of location records with optional filters.
+  """
+  locationCount(
+    """
+    Filter by date (YYYY-MM-DD)
+    """
+    date: String
+    """
+    Filter by device identifier
+    """
+    device_id: String
+  ): LocationCount!
+
+  """
+  Get the earliest and latest location timestamps.
+  """
+  locationDateRange: LocationDateRange!
 
   # Garmin
+  """
+  Get the earliest and latest Garmin activity timestamps.
+  """
+  garminDateRange: GarminDateRange!
+
+  """
+  Retrieve a paginated list of Garmin activities.
+  """
   garminActivities(
+    """
+    Filter by sport type (e.g. cycling, running)
+    """
     sport: String
+    """
+    Start date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_from: String
+    """
+    End date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_to: String
+    """
+    Maximum number of items to return per page
+    """
     limit: Int
+    """
+    Number of items to skip for pagination
+    """
     offset: Int
+    """
+    Field name to sort by
+    """
     sort: String
+    """
+    Sort direction
+    """
     order: SortOrder
   ): GarminActivityConnection!
 
-  garminActivity(activity_id: String!): GarminActivity
+  """
+  Retrieve a single Garmin activity by its ID.
+  """
+  garminActivity(
+    """
+    Garmin Connect activity identifier
+    """
+    activity_id: String!
+  ): GarminActivity
 
+  """
+  Retrieve paginated GPS track points for a Garmin activity.
+  """
   garminTrackPoints(
+    """
+    Garmin Connect activity identifier
+    """
     activity_id: String!
+    """
+    Maximum number of items to return per page
+    """
     limit: Int
+    """
+    Number of items to skip for pagination
+    """
     offset: Int
+    """
+    Field name to sort by
+    """
     sort: String
+    """
+    Sort direction
+    """
     order: SortOrder
+    """
+    Simplification tolerance for track point reduction
+    """
     simplify: Float
   ): GarminTrackPointConnection!
 
+  """
+  List all distinct sport types with activity counts.
+  """
   garminSports: [SportInfo!]!
 
+  """
+  Retrieve chart-optimised track points for a Garmin activity.
+  """
+  garminChartData(
+    """
+    Garmin Connect activity identifier
+    """
+    activity_id: String!
+  ): [GarminChartPoint!]!
+
+  """
+  Retrieve all reverse-geocoded addresses for a Garmin activity (start, mid-route waypoints, and end).
+  """
+  garminActivityAddresses(
+    """
+    Garmin Connect activity identifier
+    """
+    activity_id: String!
+  ): [GarminActivityAddress!]!
+
+  """
+  Aggregate Garmin activity totals grouped by week, month, or year.
+  """
+  garminActivityTotals(
+    """
+    Aggregation period: 'week', 'month', or 'year'
+    """
+    period: String!
+    """
+    Filter by sport (e.g. cycling, running)
+    """
+    sport: String
+    """
+    Inclusive lower bound on activity start time (YYYY-MM-DD)
+    """
+    date_from: String
+    """
+    Inclusive upper bound on activity start time (YYYY-MM-DD)
+    """
+    date_to: String
+  ): [GarminActivityTotal!]!
+
   # Unified GPS
+  """
+  Retrieve a paginated list of unified GPS points from all sources.
+  """
   unifiedGps(
+    """
+    Filter by data source: 'owntracks' or 'garmin'
+    """
     source: String
+    """
+    Start date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_from: String
+    """
+    End date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_to: String
+    """
+    Maximum number of items to return per page
+    """
     limit: Int
+    """
+    Number of items to skip for pagination
+    """
     offset: Int
+    """
+    Sort direction
+    """
     order: SortOrder
+    """
+    Exclude stationary points where speed is zero
+    """
+    exclude_stationary: Boolean
+    """
+    Remove points with duplicate coordinates (rounded to ~11m precision)
+    """
+    deduplicate: Boolean
   ): UnifiedGpsConnection!
 
+  """
+  Retrieve daily activity summaries combining OwnTracks and Garmin data.
+  """
   dailySummary(
+    """
+    Start date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_from: String
+    """
+    End date filter (YYYY-MM-DD or ISO 8601)
+    """
     date_to: String
+    """
+    Maximum number of days to return per page
+    """
     limit: Int
-  ): [DailyActivitySummary!]!
+    """
+    Number of items to skip for pagination
+    """
+    offset: Int
+  ): DailySummaryConnection!
+
+  """
+  Get the earliest and latest activity dates available in the daily activity summary view.
+  """
+  dailySummaryDateRange: DailySummaryDateRange!
 
   # Reference Locations
+  """
+  List all named reference locations.
+  """
   referenceLocations: [ReferenceLocation!]!
-  referenceLocation(id: Int!): ReferenceLocation
+  """
+  Retrieve a single reference location by its ID.
+  """
+  referenceLocation(
+    """
+    Unique reference location identifier
+    """
+    id: Int!
+  ): ReferenceLocation
 
   # Spatial
+  """
+  Find GPS points within a radius of a geographic coordinate.
+  """
   nearbyPoints(
+    """
+    Center point latitude in decimal degrees
+    """
     lat: Float!
+    """
+    Center point longitude in decimal degrees
+    """
     lon: Float!
+    """
+    Search radius in meters
+    """
     radius_meters: Float
+    """
+    Filter by data source: 'owntracks' or 'garmin'
+    """
     source: String
+    """
+    Maximum number of points to return
+    """
     limit: Int
   ): [NearbyPoint!]!
 
+  """
+  Calculate the geodesic distance between two geographic points.
+  """
   calculateDistance(
+    """
+    Origin latitude in decimal degrees
+    """
     from_lat: Float!
+    """
+    Origin longitude in decimal degrees
+    """
     from_lon: Float!
+    """
+    Destination latitude in decimal degrees
+    """
     to_lat: Float!
+    """
+    Destination longitude in decimal degrees
+    """
     to_lon: Float!
   ): DistanceResult!
 
+  """
+  Find GPS points within a named reference location's geofence.
+  """
   withinReference(
+    """
+    Name of the reference location to search within
+    """
     name: String!
+    """
+    Filter by data source: 'owntracks' or 'garmin'
+    """
     source: String
+    """
+    Maximum number of points to return
+    """
     limit: Int
   ): WithinReferenceResult!
+
+  # Geocoding
+  """
+  Get geocoding coverage statistics.
+  """
+  geocodingStatus: GeocodingStatus!
+}
+
+# -------------------------------------------------------
+# Mutations
+# -------------------------------------------------------
+type Mutation {
+  """
+  Trigger an on-demand Garmin sync in the upstream API.
+  """
+  triggerGarminSync(
+    """
+    Optional sync window in hours. Preferred over lookback.
+    """
+    window_hours: Int
+    """
+    Optional legacy lookback value.
+    """
+    lookback: Int
+  ): GarminSyncTriggerResult!
+
+  """
+  Trigger batch reverse-geocoding of un-geocoded location records.
+  """
+  triggerGeocoding(
+    """
+    Number of locations to geocode in this batch (default 100)
+    """
+    batch_size: Int
+    """
+    Re-process previously failed location records (for example, those with status `no_coverage`)
+    """
+    retry_failed: Boolean
+  ): GeocodingTriggerResult!
 }