Home

TrackHub

TrackHub is an enterprise GPS asset-tracking integration platform. It connects to the web services of multiple GPS tracking providers, retrieves real-time and historical positioning data, and consolidates it into a single, user-friendly interface — so a fleet spread across several tracking vendors is monitored in one place.

This wiki is the complete technical documentation for the platform. Repository README files carry only an overview, setup instructions and repo-specific gotchas; everything architectural lives here. End-user documentation is not here either — it ships inside the portal (see User Guide).

---

📖 Wiki Index

Platform

Page	Description
Architecture	Clean Architecture layers, CQRS mediator pipeline, composition root, tenant scoping, exception handling
Technology	Tech stack and versions, PKCE authentication flow, OAuth clients and endpoints
Inter-Service Communication	GraphQL service-to-service calls, caller vs service identity, resilience, batched reads
Database	PostgreSQL databases, schema ownership, ER diagrams, migration ownership, conventions
Security and Identity	AuthorityServer + Security API, principal types, token claims, service-client provisioning
User Permissions Overview	RBAC + policy model, resources, actions, permission matrix by screen

Services

Page	Description
Manager	Master data, accounts and features, documents, workforce, alerts and notifications, background jobs
Telemetry	Latest-position projection, position history, operator sync runs and health checks, retention
Router	Multi-protocol GPS provider integration, sync pipeline, provider capabilities
Adding a Provider	Step-by-step guide for integrating a new GPS provider
Geofencing	Geofence CRUD (polygons and circles), visit detection, dwell evaluation, alert emission
Trip Management	Trips, stops, deliveries, route plans and corridors, tolls, proof of delivery, public tracking
Reporting	Governed report catalog, dataset model, Excel and PDF rendering, limits
Common Library	What TrackHubCommon ships, and how the shared packages are versioned
Frontend	React portal architecture, data-access layering, codegen, i18n, contextual help, status page

Engineering

Page	Description
Deployment and Operations	Topology, ports and routes, configuration keys, migrations, health and status, background job catalog
Testing Strategy	Unit, contract and smoke test layers and what each one guarantees
Coding Standards	Dependency rules, required and forbidden patterns, new-feature checklist

👤 User Guide (non-technical)

User documentation lives in the app: click the Help button (or press F1) on any TrackHub screen for contextual help, a browsable topic index, and search — in English and Spanish. See User Guide for details.

---

Platform Overview

graph TB
    subgraph Clients["TrackHub Clients"]
        direction LR
        laptop["🖥️ Web Browser"]
        tablet["📱 Tablet"]
        phone["📱 Mobile"]
    end

    subgraph TrackHub["TrackHub Platform"]
        direction LR
        api["Unified API Layer"]
    end

    subgraph Providers["GPS Tracking Providers"]
        p1["Platform 1<br/><i>e.g. GeoTab</i>"]
        p2["Platform 2<br/><i>e.g. GPS Gate</i>"]
        p3["Platform 3<br/><i>e.g. Traccar</i>"]
        pn["Platform N<br/><i>Any Provider</i>"]
    end

    laptop --> api
    tablet --> api
    phone --> api

    api -->|REST / GraphQL / SOAP| p1
    api -->|REST / GraphQL / SOAP| p2
    api -->|REST / GraphQL / SOAP| p3
    api -->|REST / GraphQL / SOAP| pn

Loading

TrackHub abstracts the complexity of each provider's unique API into a standardized data model, so clients always receive consistent position data regardless of the underlying GPS platform.

---

Architecture

TrackHub is a microservices platform built on .NET 10 and React 19, with each service owning a specific domain. Services communicate over GraphQL; the Reporting service exposes a REST Minimal API for file downloads. See Architecture for the internal layering of each service and Inter-Service Communication for how they call each other.

graph TB
    subgraph Frontend["Frontend"]
        web["TrackHub Web<br/><i>React 19 + TypeScript</i>"]
    end

    subgraph Gateway["Nginx Reverse Proxy"]
        nginx["SSL Termination<br/>Path-based Routing"]
    end

    subgraph Backend["Backend Microservices"]
        auth["AuthorityServer<br/><i>OpenIddict / OAuth 2.0</i>"]
        sec["Security API<br/><i>GraphQL</i>"]
        mgr["Manager API<br/><i>GraphQL</i>"]
        rtr["Router API<br/><i>GraphQL</i>"]
        geo["Geofencing API<br/><i>GraphQL</i>"]
        tele["Telemetry API<br/><i>GraphQL</i>"]
        rpt["Reporting API<br/><i>REST</i>"]
        trip["TripManagement API<br/><i>GraphQL</i>"]
    end

    subgraph Workers["Background Services"]
        sync["SyncWorker<br/><i>Position Sync</i>"]
    end

    subgraph Data["Data Layer"]
        db1[("TrackHubSecurity<br/><i>PostgreSQL</i>")]
        db2[("TrackHub<br/><i>PostgreSQL + PostGIS</i>")]
    end

    web --> nginx
    nginx --> auth & sec & mgr & rtr & geo & tele & rpt & trip

    auth --> db1
    sec --> db1
    sec -->|GraphQL| mgr
    mgr --> db2
    mgr -->|GraphQL| sec
    mgr -->|GraphQL| rtr
    rtr -->|GraphQL| mgr
    rtr -->|GraphQL| tele
    rtr -->|GraphQL| geo
    rtr -->|GraphQL| trip
    geo --> db2
    geo -->|GraphQL| mgr
    tele --> db2
    rpt -->|GraphQL| mgr
    rpt -->|GraphQL| rtr
    rpt -->|GraphQL| geo
    rpt -->|GraphQL| tele
    rpt -->|GraphQL| trip
    trip --> db2
    trip -->|GraphQL| mgr
    trip -->|GraphQL| tele
    trip -->|REST| ors["OpenRouteService<br/><i>External</i>"]
    sync -->|GraphQL| rtr

Loading

---

Service Inventory

Service	Technology	Protocol	Database	Purpose
TrackHub (Frontend)	React 19 + TypeScript, Vite, MUI	—	—	Web portal: live map, dashboards, reports, administration, in-app contextual help (EN/ES)
AuthorityServer	.NET 10, OpenIddict	OAuth 2.0 / OIDC	TrackHubSecurity	Identity provider: PKCE authorization, client credentials, token issue/refresh/revoke
Security	.NET 10, HotChocolate	GraphQL	TrackHubSecurity	Users, roles, policies, resource/action permissions, service-client allowlist
Manager	.NET 10, HotChocolate	GraphQL + REST	TrackHub (app, map, telemetry)	Master data, accounts and features, documents, workforce, alerts and notifications, announcements
Router	.NET 10, HotChocolate	GraphQL + REST	—	Multi-protocol GPS provider integration and synchronization dispatch
Telemetry	.NET 10, HotChocolate	GraphQL	TrackHub (telemetry)	Position storage and history, operator sync runs and health checks, retention purge
Geofencing	.NET 10, HotChocolate	GraphQL	TrackHub (geofencing)	Geofence CRUD, spatial detection, visit events, dwell evaluation, alert emission
Reporting	.NET 10, Minimal APIs	REST	—	Governed report catalog: preview, Excel and PDF generation
TripManagement	.NET 10, HotChocolate	GraphQL + REST	TrackHub (trip)	Trip planning and execution, route corridors, tolls, proof of delivery, public tracking links
SyncWorker	.NET 10 Generic Host	—	—	Background position and device synchronization (built from the Router repository)
TrackHubMobile	.NET MAUI	—	—	Driver/operator mobile application (work in progress)

The Router and Reporting services hold no database of their own — they compose data from the services that own it.

---

Shared Library

All backend services depend on TrackHubCommon, distributed as local NuGet packages. It provides the custom CQRS mediator and its behavior pipeline, OpenIddict JWT configuration, the GraphQL client factory, authorization and tenant-scope enforcement, domain-event infrastructure, and the cross-service constant catalogs (resources, actions, feature keys, schema and table names). See Common Library.

---

Key Features

• Multi-provider integration — connect any number of GPS providers simultaneously; nine are implemented
• Real-time tracking — live map with device positions, speed, address and status
• Geofencing — polygon and circle zones with entry, exit and dwell detection
• Trip management — multi-stop routes with corridors and toll estimates, real-time deviation detection, proof of delivery, and shareable read-only tracking links
• Reporting — a governed catalog of 30 reports across Operations, GPS, Documents, Workforce, Trips and Administration, with preview, Excel and PDF export
• Alerts and notifications — alert events with in-app, email, webhook and WhatsApp delivery rules, throttling and digests
• Document management — versioned uploads with virus scanning, signatures, sharing and expiration alerts
• Workforce — driver registry, qualifications with expiration scanning, and transporter assignment history
• In-app contextual help — Help button / F1 on every screen, searchable bilingual (EN/ES) topic index shipped with each release
• Public status page — /status renders without signing in, reporting per-service health and platform announcements
• Multi-tenant — account isolation enforced centrally in the request pipeline, with hierarchical roles and policies
• PKCE authentication — OAuth 2.0 authorization code flow with PKCE for web, mobile and driver clients