Most organizations do not buy their GPS hardware from one vendor. They inherit it — a batch of trackers from one supplier, a second platform that came with a leased fleet, a third that a subsidiary already paid for. Each one ships its own portal, its own login and its own idea of what a "trip" is.
TrackHub is the layer above all of them. It connects to each GPS provider through a pluggable provider model, normalizes what they report, and gives the organization one live map, one set of geofences, one trip board, one report catalog and one permission model over the whole fleet — regardless of who supplied the hardware.
It is open source, self-hosted, multi-tenant and bilingual (English / Spanish), built as a .NET 10 GraphQL microservice platform with a React 19 portal.
| Live tracking | Real-time map of every transporter and device across all connected providers, with replay and trip segmentation |
| Multi-provider GPS integration | Twenty GPS providers behind one Router service, with device management, manual sync, connectivity ping and derived operator health |
| Geofencing | Polygon and circle zones on both map providers, PostGIS containment detection, entry / exit / dwell alerts and visit history |
| Trip management | Zero-touch trip lifecycle — trips arm, start and complete from origin and stop zones — plus route plans, tolls, proof of delivery, ETAs and public tracking links |
| Documents & workforce | Versioned documents with signatures, sharing, expiration and retention; the staff registry with qualifications and assignment history |
| Alerts & notifications | Rule-driven alerts delivered in-app, by email, WhatsApp or webhook, with throttling, digests and escalation |
| Reporting | A governed catalog of 30 reports with in-app preview and Excel / PDF export |
| Multi-tenancy | Account lifecycle, per-account feature flags, branding, and a role + policy permission model enforced service-side |
| Operability | A public /status page that works without signing in, health checks per service, platform announcements and versioned Docker rollback |
Eight backend services, a background worker and a React portal, all speaking GraphQL (Reporting is REST) and authenticated by the AuthorityServer.
flowchart TB
portal["Web portal<br/>React 19"]
mobile["Mobile app<br/>MAUI"]
subgraph identity ["Identity and access"]
authority["AuthorityServer<br/>OAuth 2.0 / OIDC"]
security["Security<br/>users · roles · policies"]
end
subgraph services ["Domain services"]
manager["Manager<br/>master data · alerts · documents"]
router["Router<br/>GPS provider integration"]
telemetry["Telemetry<br/>positions · history · health"]
geofencing["Geofencing<br/>zones · visits"]
trip["Trip Management<br/>trips · routes · tolls"]
reporting["Reporting<br/>report catalog · exports"]
end
worker["SyncWorker<br/>polls every provider"]
providers[("GPS providers")]
db[("PostgreSQL + PostGIS")]
portal --> identity
mobile --> identity
portal --> services
mobile --> services
services -. authorize .-> security
worker --> router
router --> providers
router --> telemetry & geofencing & trip
manager --> telemetry
reporting --> manager & telemetry & router & geofencing & trip
services --> db
identity --> db
How it fits together is in the wiki: Architecture, Inter-Service Communication, Database.
Every service, the portal, the shared framework, the contract tests and the deployment tooling live in this repository and build from one solution.
| Module | Purpose | Route prefix |
|---|---|---|
| TrackHubCommon | Shared framework (domain, request pipeline, GraphQL, infrastructure, PDF), consumed as a ProjectReference | — |
| TrackHub.AuthorityServer | Authorization service — OAuth 2.0 / OpenID Connect, login, tokens | /Identity/ |
| TrackHubSecurity | Security API — users, roles, policies, permissions, service clients | /Security/ |
| TrackHub.Manager | Management API — accounts, assets, operators, documents, workforce, alerts | /Manager/ |
| TrackHubRouter | Router API and SyncWorker — GPS provider integration | /Router/ |
| TrackHub.Telemetry | Telemetry API — positions, history, operator health | /Telemetry/ |
| TrackHub.Geofencing | Geofencing API — zones, containment detection, visits | /Geofence/ |
| TrackHub.TripManagement | Trip Management API — trips, stops, routes, tolls, public tracking | /Trip/ |
| TrackHub.Reporting | Reporting API — governed report catalog, Excel / PDF export | /Reporting/ |
| TrackHub.Portal | Web portal (React 19 + TypeScript) and the in-app help content | / |
| TrackHub.IntegrationTests | Cross-service GraphQL contract tests | — |
| TrackHub.Deployment | Docker deployment for the whole stack | — |
| TrackHubMobile | Mobile application — separate repository | — |
Each module folder has a short README: what it owns, how to build, run and test it on its own, and the gotchas specific to it.
A Linux host with Docker and PostgreSQL 14+ with PostGIS. Follow QUICKSTART.md end to end — the databases, migrations, certificates and OAuth clients have to happen in that order. INSTALL.md covers configuration, upgrades, backups, rollback and troubleshooting.
Requires the .NET 10 SDK and, for the portal, Node.js 22.
git clone https://github.com/shernandezp/TrackHub.git
cd TrackHub
dotnet build TrackHub.slnx # the whole backend graph
dotnet test TrackHub.Manager # one service's tests
dotnet test TrackHub.IntegrationTests # the cross-service contract suite
cd TrackHub.Portal && npm ci && npm run typecheck && npm test && npm run buildEach service also has its own .slnx, for working on it without loading the whole graph.
- Run the backend on local Docker and the portal on the Vite dev server —
LOCAL-DOCKER.md (Windows, Docker Desktop, PostgreSQL on the
host). Every committed
appsettings.jsonand the portal's.envalready point at that stack (https://trackhub.local:8443), so a single service can be pulled out into the debugger while the rest keep running in containers. - The database schema comes from EF Core migrations, never from the seeders. Each owning
service's README has its
dotnet ef database updatecommand; the committed connection strings targetlocalhost:5432aspostgres. - Every service loads the OpenIddict signing certificate from
OpenIddict:Path(C:\Certificates\certificate.pfx, passwordopeniddictin the committed settings). All processes that mint or validate tokens must share the same file.
| Backend | .NET 10, HotChocolate GraphQL, EF Core + Npgsql, NetTopologySuite, FluentValidation, Serilog, OpenIddict |
| Frontend | React 19, TypeScript 7, Vite 8, MUI 9, TanStack Query, Vitest 5, Playwright, Leaflet / Google Maps |
| Data | PostgreSQL 14+ with PostGIS — two databases (TrackHub, TrackHubSecurity), one schema per service |
| Integration | GraphQL everywhere, including service-to-service; OAuth 2.0 client credentials for service identities |
| Delivery | Docker Compose behind nginx, GitHub Actions CI, versioned images with one-command rollback |
| Technical | The TrackHub wiki — Architecture, Technology, Database, Security and Identity, Frontend, Testing Strategy |
| Adding a GPS provider | Adding a Provider |
| Deployment & operations | Deployment and Operations · QUICKSTART · INSTALL |
| Permissions | User Permissions Overview |
| User documentation | In the app — the Help button or F1 on any screen, in English and Spanish |
TrackHub is built to be extended — new GPS providers, new reports, new integrations. Contributions are welcome.
- Read Coding Standards and Architecture first — the layering and CQRS conventions are enforced consistently across all services.
- Branch from
develop, keepdotnet build TrackHub.slnxgreen, and add tests beside the code you change. - Open a pull request; CI builds the whole graph and runs the tests of every affected service, the contract suite, and the portal checks.
Licensed under the Apache License 2.0 — see LICENSE.

