Home

TrackHub

📖 Wiki Index

Page	Description
Home	Platform overview, architecture, and service inventory
Router	Multi-protocol GPS provider integration and data sync flow
Technology	Tech stack, PKCE authentication flow, and Clean Architecture
Database	PostgreSQL schema, ER diagrams, and multi-tenant isolation
User Permissions Overview	RBAC + Policy model, permissions matrix by screen

👤 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.

---

TrackHub is an enterprise GPS asset-tracking integration platformthat 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. This allows users to monitor multiple tracking systems in one place, simplifying fleet management and location tracking.

---

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 follows a microservices architecture built on .NET 10 and React.js, with each service owning a specific domain. All backend services communicate via GraphQL, while the Reporting service exposes a REST Minimal API for file downloads.

graph TB
    subgraph Frontend["Frontend"]
        web["TrackHub Web<br/><i>React.js</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

    auth --> db1
    sec --> db1
    sec -->|GraphQL| mgr
    mgr --> db2
    mgr -->|GraphQL| sec
    rtr -->|GraphQL| mgr
    rtr -->|GraphQL| geo
    geo --> db2
    tele --> db2
    rpt -->|GraphQL| rtr
    rpt -->|GraphQL| geo
    rpt -->|GraphQL| tele
    trip -->|GraphQL| geo
    sync -->|GraphQL| rtr

Loading

---

Service Inventory

Service	Technology	Protocol	Database	Purpose
TrackHub (Frontend)	React 19 + TypeScript, Vite, MUI	—	—	Web UI with maps, dashboards, reports, in-app contextual help (EN/ES)
AuthorityServer	.NET 10, OpenIddict	OAuth 2.0	TrackHubSecurity	Identity provider, PKCE authorization
Security	.NET 10, HotChocolate	GraphQL	TrackHubSecurity	Users, roles, policies, permissions
Manager	.NET 10, HotChocolate	GraphQL	TrackHub	Accounts, transporters, devices, operators
Router	.NET 10, HotChocolate	GraphQL	—	Multi-protocol GPS provider integration
Telemetry	.NET 10, HotChocolate	GraphQL	TrackHub	Position storage & history (live-map hot path), retention purge
Geofencing	.NET 10, HotChocolate	GraphQL	TrackHub	Geofence CRUD (polygons + circles), spatial queries, visit events, alert emission to Manager, dwell evaluator
Reporting	.NET 10 Minimal APIs	REST	—	Excel + PDF report generation (governed catalog)
TripManagement	.NET 10, HotChocolate	GraphQL	—	Trip analysis and management
SyncWorker	.NET 10 Worker	—	—	Background position synchronization

---

Shared Library

All backend services depend on TrackHubCommon, a shared NuGet package that provides:

• Custom CQRS mediator pipeline (commands, queries, behaviors)
• OpenIddict JWT configuration
• GraphQL client helpers with Polly resilience (retry + circuit breaker)
• Authorization behavior with resource/action attribute checking
• Logging, validation, caching, and rate-limiting behaviors
• Domain event infrastructure

---

Key Features

• Multi-provider integration — Connect any number of GPS providers simultaneously
• Real-time tracking — Live map with device positions, speed, and status
• Geofencing — Create and manage geofences with automatic event detection
• Reporting — Governed report catalog (operations, GPS, documents, administration) with preview, Excel, and PDF export
• Alerts & notifications — Alert events with in-app, email, webhook, and WhatsApp notification rules
• In-app contextual help — Help button / F1 on every screen, searchable bilingual (EN/ES) topic index shipped with each release
• Multi-tenant — Full account isolation with hierarchical roles and policies
• PKCE authentication — Secure OAuth 2.0 authorization for web and mobile clients
• Role-based access control — Fine-grained permissions per resource and action