{
  "feature": "device-status-tracking",
  "version": "1.0.0",
  "description": "Continuously monitor whether GPS devices are actively reporting, and automatically transition them between online, offline, and unknown states based on configurable inactivity thresholds, emitting ...",
  "category": "data",
  "tags": [
    "gps",
    "tracking",
    "device-status",
    "connectivity",
    "fleet",
    "monitoring"
  ],
  "actors": [
    {
      "id": "device",
      "name": "GPS Device",
      "type": "external",
      "description": "Physical hardware that transmits positions; its silence drives offline detection"
    },
    {
      "id": "scheduler",
      "name": "Inactivity Checker",
      "type": "system",
      "description": "Periodically scans devices whose last_update has exceeded the inactivity threshold"
    },
    {
      "id": "fleet_user",
      "name": "Fleet User",
      "type": "human",
      "description": "Views real-time device status in the fleet map or device list"
    }
  ],
  "fields": [
    {
      "name": "status",
      "type": "select",
      "required": true,
      "label": "Current connectivity status: online, offline, or unknown"
    },
    {
      "name": "last_update",
      "type": "datetime",
      "required": false,
      "label": "Timestamp of the most recently received position from this device"
    },
    {
      "name": "inactivity_start",
      "type": "number",
      "required": false,
      "label": "Milliseconds of silence after which the device is flagged as inactive; inherited from group if no..."
    },
    {
      "name": "inactivity_period",
      "type": "number",
      "required": false,
      "label": "Repeat interval (milliseconds) for generating repeated inactivity events after the initial one"
    }
  ],
  "states": {
    "field": "status",
    "values": [
      {
        "id": "unknown",
        "label": "Unknown",
        "initial": true,
        "description": "Device has registered but never transmitted a position"
      },
      {
        "id": "online",
        "label": "Online",
        "description": "Device transmitted a position within the inactivity_start window"
      },
      {
        "id": "offline",
        "label": "Offline",
        "description": "Device has not transmitted within the inactivity_start window"
      }
    ],
    "transitions": [
      {
        "from": "unknown",
        "to": "online",
        "actor": "device",
        "description": "Device transmits its first position"
      },
      {
        "from": "offline",
        "to": "online",
        "actor": "device",
        "description": "Device resumes transmitting after a period of silence"
      },
      {
        "from": "online",
        "to": "offline",
        "actor": "scheduler",
        "description": "Inactivity threshold exceeded since last_update"
      },
      {
        "from": "unknown",
        "to": "offline",
        "actor": "scheduler",
        "description": "Device registered but never reported within threshold period"
      }
    ]
  },
  "rules": {
    "processing": {
      "online_on_position_received": "Status transitions to online as soon as a new position is received, regardless of current status",
      "offline_on_inactivity_threshold": "Status transitions to offline when (current_time - last_update) > inactivity_start",
      "threshold_inheritance": "If inactivity_start is not set on the device, it inherits the value from the parent group or server default",
      "check_schedule": "The inactivity check runs on a configurable schedule (typically every few minutes); status is not updated in real time between check runs",
      "repeated_inactivity_events": "If inactivity_period is set, repeated inactivity events are generated each time the silence duration increases by another inactivity_period interval"
    },
    "event_emission": {
      "transitions_trigger_notifications": "Status transitions are recorded as events and can trigger notifications to fleet users"
    }
  },
  "outcomes": {
    "device_comes_online": {
      "priority": 8,
      "given": [
        "device transmits a new position",
        {
          "field": "status",
          "source": "db",
          "operator": "neq",
          "value": "online"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "status",
          "value": "online"
        },
        {
          "action": "set_field",
          "target": "last_update",
          "value": "now"
        },
        {
          "action": "emit_event",
          "event": "device.online",
          "payload": [
            "device_id",
            "last_update"
          ]
        }
      ],
      "result": "Device status is updated to online and subscribers are notified"
    },
    "device_goes_offline": {
      "priority": 5,
      "given": [
        "scheduler determines that (now - last_update) > inactivity_start",
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "online"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "status",
          "value": "offline"
        },
        {
          "action": "emit_event",
          "event": "device.offline",
          "payload": [
            "device_id",
            "last_update",
            "silence_duration_ms"
          ]
        }
      ],
      "result": "Device is marked offline; alert handlers can dispatch notifications to users"
    },
    "device_remains_inactive": {
      "priority": 4,
      "given": [
        "device continues to be silent beyond additional inactivity_period intervals",
        {
          "field": "inactivity_period",
          "source": "db",
          "operator": "gt",
          "value": 0
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "device.inactive",
          "payload": [
            "device_id",
            "silence_duration_ms"
          ]
        }
      ],
      "result": "Repeated inactivity event emitted at each period boundary while device remains silent"
    }
  },
  "errors": [
    {
      "code": "DEVICE_STATUS_NOT_FOUND",
      "message": "The specified device does not exist",
      "status": 404
    }
  ],
  "events": [
    {
      "name": "device.online",
      "description": "Device has resumed transmitting positions after being offline or unknown",
      "payload": [
        "device_id",
        "last_update"
      ]
    },
    {
      "name": "device.offline",
      "description": "Device has exceeded the inactivity threshold without transmitting",
      "payload": [
        "device_id",
        "last_update",
        "silence_duration_ms"
      ]
    },
    {
      "name": "device.inactive",
      "description": "Device remains silent beyond a repeated inactivity period boundary",
      "payload": [
        "device_id",
        "silence_duration_ms"
      ]
    }
  ],
  "related": [
    {
      "feature": "gps-device-registration",
      "type": "required",
      "reason": "Devices must be registered before their status can be tracked"
    },
    {
      "feature": "gps-position-ingestion",
      "type": "required",
      "reason": "Receiving a position is the trigger for transitioning to online"
    },
    {
      "feature": "device-alarm-notifications",
      "type": "recommended",
      "reason": "Offline events can be routed as notifications to fleet users"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_device_status_tracking",
        "description": "Continuously monitor whether GPS devices are actively reporting, and automatically transition them between online, offline, and unknown states based on configurable inactivity thresholds, emitting ...",
        "success_metrics": [
          {
            "metric": "data_accuracy",
            "target": "100%",
            "measurement": "Records matching source of truth"
          },
          {
            "metric": "duplicate_rate",
            "target": "0%",
            "measurement": "Duplicate records detected post-creation"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Data consistency must be maintained across concurrent operations",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before transitioning to a terminal state"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "device_comes_online",
          "permission": "autonomous"
        },
        {
          "action": "device_goes_offline",
          "permission": "autonomous"
        },
        {
          "action": "device_remains_inactive",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "data_integrity",
        "over": "performance",
        "reason": "data consistency must be maintained across all operations"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "gps_device_registration",
          "from": "gps-device-registration",
          "fallback": "degrade"
        },
        {
          "capability": "gps_position_ingestion",
          "from": "gps-position-ingestion",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "source": {
      "repo": "https://github.com/traccar/traccar",
      "project": "Traccar GPS Tracking Server",
      "tech_stack": "Java 17, Hibernate",
      "files_traced": 6,
      "entry_points": [
        "src/main/java/org/traccar/model/Device.java",
        "src/main/java/org/traccar/schedule/TaskDeviceInactivityCheck.java"
      ]
    }
  }
}