Admin Tracker Updates

This guide explains how administrators can request immediate updates for tracker locations.

Overview

The system includes an admin-only function that allows privileged users to request an immediate update of a tracker's location. This feature is particularly useful when:

• You need the most up-to-date location information for a specific tracker
• A tracker hasn't reported its location recently
• You want to verify if a tracker is still active
• You need to troubleshoot tracking issues

When an admin requests an update, the system:

1. Submits a task to the Redis queue for immediate processing
2. The fetcher service processes the request and retrieves the latest data
3. The database is updated with any new location information
4. Real-time notifications are sent to connected clients via Socket.IO

Prerequisites

To use this feature, you must:

• Have an account with admin privileges
• Be authenticated with a valid JWT token that includes the admin role
• Have the tracker ID of the device you want to update

Checking Admin Status

You can check if your user account has admin privileges by using the currentUser GraphQL query:

query GetCurrentUser {
  currentUser {
    id
    name
    email
    roles
  }
}

This query returns information about the currently authenticated user, including their roles. If the roles array includes "admin", the user has admin privileges and can use the tracker update feature:

{
  "data": {
    "currentUser": {
      "id": "3",
      "name": "Admin User",
      "email": "admin@example.com",
      "roles": ["admin"]
    }
  }
}

The frontend application automatically checks for admin privileges and only displays the "Update Location" button for users with the admin role.

Using the Admin Update Feature

Through the Web Interface

1. Log in to the system with an admin account (e.g., admin@example.com)
2. Navigate to the main tracking dashboard
3. Find the tracker you want to update in the table
4. Click the "Update Location" button in the Actions column
5. Confirm the action in the dialog that appears

The system will submit the update request and notify you when the process is complete. If new location data is found, the map and table will automatically update to reflect the changes.

Through the GraphQL API

You can also trigger an update programmatically using the GraphQL API:

mutation UpdateTrackerLocation($trackerId: ID!) {
  updateTrackerLocation(trackerId: $trackerId) {
    success
    message
    trackerId
  }
}

Variables:

{
  "trackerId": "123"
}

The response will include:

{
  "data": {
    "updateTrackerLocation": {
      "success": true,
      "message": "Tracker location update request sent to fetcher service",
      "trackerId": "123"
    }
  }
}

Real-time Updates

When the fetcher service completes the update process, it sends a notification through Redis. The Socket.IO server forwards this notification to connected clients, which will receive an event like this:

{
  "type": "tracker_location_updated",
  "trackerId": "123",
  "success": true,
  "message": "Successfully updated tracker ABC123, found 5 reports, stored 2 new reports",
  "location": {
    "id": "456789",
    "timestamp": "2025-05-06T12:53:25",
    "nearestCity": "London",
    "location": {
      "latitude": 51.5074,
      "longitude": -0.1278
    },
    "confidence": 3,
    "horizontalAccuracy": 10.5
  }
}

The client application will automatically update the map and table with this new information.

Implementation Details

Backend Components

The admin update feature is implemented using several components:

1. GraphQL Mutation: The updateTrackerLocation mutation in mutations/tracker.py handles the request and performs admin role verification
2. Redis Queue: The update request is published to a Redis channel for processing
3. Fetcher Service: Listens for requests and fetches the latest tracker data
4. Socket.IO Integration: Provides real-time updates to clients when new data is available

Socket.IO Architecture

The Socket.IO implementation uses a two-stage notification system:

1. A Redis subscriber thread listens for notifications from the fetcher service
2. Notifications are stored in Redis with a unique key
3. A dedicated notification processor task runs in the main event loop to process these notifications
4. The processor emits Socket.IO events to connected clients

This architecture solves the "no current event loop in thread" error that can occur when trying to emit Socket.IO events from a background thread.

Troubleshooting

Common Issues

• Update button not visible: Verify that your account has admin privileges
• Update request fails: Check that the fetcher service is running and connected to Redis
• No real-time updates: Ensure Socket.IO is properly connected and authenticated
• No new data received: The tracker may be inactive or unable to report its location

Logs to Check

If you encounter issues, check the following logs:

• Backend server logs for authentication or permission issues
• Redis logs for queue processing problems
• Fetcher service logs for data retrieval issues
• Socket.IO logs for connection and event emission problems

Security Considerations

The admin update feature includes several security measures:

• Admin role verification through JWT token claims
• Rate limiting to prevent abuse
• Validation of tracker IDs to prevent unauthorized access
• Secure Socket.IO connections with proper authentication

Conclusion

The admin tracker update feature provides a powerful tool for administrators to ensure they have the most up-to-date location information. By leveraging Redis queues and Socket.IO for real-time updates, the system delivers a responsive and efficient experience for tracking critical assets.