Router

Router

TrackHub Router is the multi-protocol integration layer of the platform. It connects to external GPS Tracking Providers — each with their own API technology (REST, GraphQL, SOAP, WebSockets, tRPC, etc.) — and standardizes the position data into a unified format that the rest of the TrackHub ecosystem can consume consistently and reliably.

---

Multi-Protocol Integration

graph LR
    subgraph Providers["GPS Tracking Providers"]
        rest["REST API<br/><i>e.g. Traccar</i>"]
        gql["GraphQL API<br/><i>e.g. Custom</i>"]
        soap["SOAP / XML<br/><i>e.g. enterprise providers</i>"]
        ws["WebSocket<br/><i>e.g. Real-time</i>"]
        trpc["tRPC / gRPC<br/><i>e.g. Modern</i>"]
    end

    subgraph Router["TrackHub Router"]
        adapter["Protocol Adapters"]
        norm["Data Normalizer"]
        cache["Token Cache"]
    end

    rest -->|HTTP/JSON| adapter
    gql -->|HTTP/GraphQL| adapter
    soap -->|HTTP/XML| adapter
    ws -->|WS/Binary| adapter
    trpc -->|HTTP/Protobuf| adapter

    adapter --> norm
    norm --> unified["Unified Position Model<br/><i>TransporterId, Lat, Lng,<br/>Speed, Altitude, EventDate</i>"]

Loading

The Router abstracts away the protocol differences so that downstream services (Reporting, Geofencing) and the frontend always work with the same data shape.

---

Data Synchronization Flow

Position data flows through a background synchronization process powered by the SyncWorker service:

sequenceDiagram
    participant SW as SyncWorker
    participant Auth as AuthorityServer
    participant Router as Router API
    participant Mgr as Manager API
    participant GPS as GPS Provider
    participant Geo as Geofencing API

    SW->>Auth: Client Credentials Grant
    Auth-->>SW: Access Token

    SW->>Router: getAccountsToSync()
    Router->>Mgr: getAccountsToSync()
    Mgr-->>Router: Accounts list
    Router-->>SW: Accounts list

    loop For each Account
        SW->>Router: getOperators(accountId)
        Router->>Mgr: getOperators(accountId)
        Mgr-->>Router: Operators + Credentials
        Router-->>SW: Operators + Credentials

        loop For each Operator
            SW->>GPS: Authenticate (token/credentials)
            GPS-->>SW: Session / New Token

            alt Token Refreshed
                SW->>Router: updateToken(credentialId, newToken)
                Router->>Mgr: updateToken(...)
            end

            SW->>GPS: Fetch Device Positions
            GPS-->>SW: Raw Position Data

            loop For each Device Position
                SW->>Router: addOrUpdatePosition(position)
                Router->>Mgr: Persist to DB
                Router->>Geo: Check Geofence Events
            end
        end
    end

Loading

---

Supported Protocol Types

The Router uses a protocol type identifier to determine which adapter to use for each operator:

Protocol	Description	Authentication
CommandTrack	CommandTrack REST API	Token-based
GeoTab	GeoTab fleet management	Session-based
GpsGate	GPS Gate tracking platform	Token-based
Traccar	Open-source tracking server	Basic auth / Token

New providers can be integrated by implementing the corresponding protocol adapter and registering it in the Router configuration:

AppSettings__Protocols__0=CommandTrack
AppSettings__Protocols__1=GeoTab
AppSettings__Protocols__2=GpsGate
AppSettings__Protocols__3=Traccar

---

Key GraphQL Operations

Queries

Operation	Description
getOperators	List operators for an account
getOperatorByTransporter	Find the operator managing a transporter
getDevicesByOperator	List devices assigned to an operator
getDeviceTransporter	Get the transporter linked to a device
getTransporterPosition	Current position of a transporter
getPositionsRecord	Historical position records (date range)
getAccountsToSync	Accounts requiring synchronization

Mutations

Operation	Description
updateToken	Refresh stored credentials after token renewal
addOrUpdatePosition	Persist a new device position

---

Service Dependencies

graph LR
    Router["Router API"]
    Manager["Manager API<br/><i>Operators, Devices,<br/>Credentials, Positions</i>"]
    Geofencing["Geofencing API<br/><i>Geofence Event Detection</i>"]

    Router -->|"GraphQL<br/>(read/write)"| Manager
    Router -->|"GraphQL<br/>(write events)"| Geofencing

Loading

The Router does not have its own database. It delegates all persistence to the Manager service and geofence event detection to the Geofencing service.