# uvaestudantes/noponto-backend architecture

> Architecture diagram of the GitHub repository uvaestudantes/noponto-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uvaestudantes/noponto-backend
- Repository: https://github.com/uvaestudantes/noponto-backend

## Overview

NoPonto is a layered ASP.NET Core mobility backend. The main runtime path collects and validates bus/BRT GPS, matches observations to versioned routes, updates operational state and ephemeral snapshots, then publishes vehicle updates to clients. Rail is a distinct schedule-first path that infers positions from provider evidence. The README documents additional structural imports, stop events, history, telemetry, and experimental ETA capabilities. Edges use README statements or shown source references; unsampled implementation details are represented conservatively.

Main entry points: [`NoPonto/Program.cs`](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/Program.cs) (ASP.NET API), [`NoPonto/2-Application/Services/GPS/GpsPollingService.cs`](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsPollingService.cs) (GPS polling and validation), [`NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs`](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs) (Trip repository), [`NoPonto/2-Application/Services/GPS/GpsEnriquecimentoService.cs`](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsEnriquecimentoService.cs) (GPS matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and clients"]
  node_api_runtime["ASP.NET API<br/>[Program.cs]"]
  node_gps_hub["GPS SignalR hub<br/>[GpsHub.cs]"]
  node_struct_api["Structure endpoints"]
  node_rail_api["Rail vehicle API"]
end

subgraph group_road["Road operations"]
  node_gps_collect["GPS sources"]
  node_gps_poll["GPS polling and validation"]
  node_gps_enrich["GPS matching"]
  node_gps_projection["Operational projection"]
  node_trip_service["Observed trips"]
  node_gps_eta["ETA client<br/>[GpsEtaClient.cs]"]
end

subgraph group_rail["Rail realtime"]
  node_rail_schedule["Rail schedules"]
  node_rail_scheduler["Sentinel scheduler"]
  node_rail_tracker["Rail tracking"]
  node_rail_engine["Position estimation"]
end

subgraph group_domain["Structure and insights"]
  node_structure_import["Structural imports"]
  node_stop_events["Stop events"]
  node_telemetry["Telemetry and ETA V2"]
end

subgraph group_storage["Persistence"]
  node_postgres[("PostgreSQL / PostGIS")]
  node_redis[("Redis snapshots")]
  node_trip_repo["Trip repository"]
  node_trip_observed_repo["Observed-trip repository"]
  node_outbox["Trip outbox worker"]
end

node_app(("Mobile app"))
node_providers(("Transit providers"))

node_app -->|"HTTP / SignalR"| node_api_runtime
node_api_runtime -->|"SQL / PostGIS"| node_postgres
node_api_runtime -->|"RESP"| node_redis
node_api_runtime -->|"HTTP"| node_providers
node_api_runtime -->|"hosts workers"| node_gps_poll
node_gps_poll -->|"collects positions"| node_gps_collect
node_gps_poll -->|"enriches batch"| node_gps_enrich
node_gps_poll -->|"requests predictions"| node_gps_eta
node_gps_poll -->|"updates snapshots"| node_redis
node_gps_poll -->|"publishes updates"| node_gps_hub
node_gps_enrich -->|"matches via PostGIS"| node_postgres
node_gps_poll -->|"updates trip state"| node_trip_service
node_trip_service -->|"persists operations"| node_trip_repo
node_trip_repo -->|"stores durable state"| node_postgres
node_trip_repo -->|"projects state"| node_redis
node_trip_observed_repo -->|"updates trip state"| node_redis
node_trip_repo -->|"writes outbox"| node_outbox
node_api_runtime -->|"registers import command"| node_structure_import
node_structure_import -->|"publishes versions"| node_postgres
node_api_runtime -->|"hosts rail services"| node_rail_scheduler
node_rail_schedule -->|"loads schedules"| node_postgres
node_rail_scheduler -.->|"schedules evidence tracking"| node_rail_tracker
node_rail_tracker -.->|"supplies observations"| node_rail_engine
node_rail_engine -->|"serves inferred positions"| node_rail_api
node_api_runtime -.->|"hosts event services"| node_stop_events
node_stop_events -->|"stores history"| node_postgres
node_api_runtime -->|"hosts workers"| node_telemetry
node_telemetry -->|"persists telemetry"| node_postgres
node_api_runtime -->|"serves structure"| node_struct_api

click node_api_runtime "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/Program.cs"
click node_gps_hub "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/1-API/Hubs/GpsHub.cs"
click node_struct_api "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/1-API/Controllers/EstruturaLinhasController.cs"
click node_rail_api "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/1-API/Controllers/RailVehiclesController.cs"
click node_gps_collect "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GtfsRealtimeGpsSource.cs"
click node_gps_poll "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsPollingService.cs"
click node_gps_enrich "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsEnriquecimentoService.cs"
click node_gps_projection "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/ProjecaoOperacional.cs"
click node_trip_service "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/ViagemObservadaService.cs"
click node_gps_eta "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsEtaClient.cs"
click node_rail_schedule "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremSchedule/RailScheduleRuntime.cs"
click node_rail_scheduler "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremRealtime/Scheduling/TremSentinelSchedulerEngine.cs"
click node_rail_tracker "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremRealtime/Tracking/TremRealtimeTracker.cs"
click node_rail_engine "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremRealtime/RailRuntime/RailRealtimeEngine.cs"
click node_structure_import "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GTFS/StructuralImportCommand.cs"
click node_stop_events "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/EventosParada/EventosParadaService.cs"
click node_telemetry "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/BackgroundServices/TelemetriaMlWorker.cs"
click node_trip_repo "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs"
click node_trip_observed_repo "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/4-Data/Repositories/ViagemObservadaRepository.cs"
click node_outbox "https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/BackgroundServices/ViagemOutboxWorker.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_runtime,node_gps_hub,node_struct_api,node_rail_api toneBlue
class node_gps_collect,node_gps_poll,node_gps_enrich,node_gps_projection,node_trip_service,node_gps_eta toneAmber
class node_rail_schedule,node_rail_scheduler,node_rail_tracker,node_rail_engine toneMint
class node_structure_import,node_stop_events,node_telemetry toneRose
class node_postgres,node_redis,node_trip_repo,node_trip_observed_repo,node_outbox,node_app,node_providers toneIndigo
```

## Components

### API and clients

- [ASP.NET API](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/Program.cs): `NoPonto/Program.cs`
- [GPS SignalR hub](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/1-API/Hubs/GpsHub.cs): `NoPonto/1-API/Hubs/GpsHub.cs`
- [Structure endpoints](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/1-API/Controllers/EstruturaLinhasController.cs): `NoPonto/1-API/Controllers/EstruturaLinhasController.cs`
- [Rail vehicle API](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/1-API/Controllers/RailVehiclesController.cs): `NoPonto/1-API/Controllers/RailVehiclesController.cs`

### Road operations

- [GPS sources](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GtfsRealtimeGpsSource.cs): `NoPonto/2-Application/Services/GPS/GtfsRealtimeGpsSource.cs`
- [GPS polling and validation](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsPollingService.cs): `NoPonto/2-Application/Services/GPS/GpsPollingService.cs`
- [GPS matching](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsEnriquecimentoService.cs): `NoPonto/2-Application/Services/GPS/GpsEnriquecimentoService.cs`
- [Operational projection](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/ProjecaoOperacional.cs): `NoPonto/2-Application/Services/GPS/ProjecaoOperacional.cs`
- [Observed trips](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/ViagemObservadaService.cs): `NoPonto/2-Application/Services/GPS/ViagemObservadaService.cs`
- [ETA client](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GPS/GpsEtaClient.cs): `NoPonto/2-Application/Services/GPS/GpsEtaClient.cs`

### Rail realtime

- [Rail schedules](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremSchedule/RailScheduleRuntime.cs): `NoPonto/2-Application/Services/TremSchedule/RailScheduleRuntime.cs`
- [Sentinel scheduler](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremRealtime/Scheduling/TremSentinelSchedulerEngine.cs): `NoPonto/2-Application/Services/TremRealtime/Scheduling/TremSentinelSchedulerEngine.cs`
- [Rail tracking](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremRealtime/Tracking/TremRealtimeTracker.cs): `NoPonto/2-Application/Services/TremRealtime/Tracking/TremRealtimeTracker.cs`
- [Position estimation](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/TremRealtime/RailRuntime/RailRealtimeEngine.cs): `NoPonto/2-Application/Services/TremRealtime/RailRuntime/RailRealtimeEngine.cs`

### Structure and insights

- [Structural imports](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/GTFS/StructuralImportCommand.cs): `NoPonto/2-Application/Services/GTFS/StructuralImportCommand.cs`
- [Stop events](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/EventosParada/EventosParadaService.cs): `NoPonto/2-Application/Services/EventosParada/EventosParadaService.cs`
- [Telemetry and ETA V2](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/BackgroundServices/TelemetriaMlWorker.cs): `NoPonto/2-Application/Services/BackgroundServices/TelemetriaMlWorker.cs`

### Persistence

- **PostgreSQL / PostGIS**
- **Redis snapshots**
- [Trip repository](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs): `NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs`
- [Observed-trip repository](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/4-Data/Repositories/ViagemObservadaRepository.cs): `NoPonto/4-Data/Repositories/ViagemObservadaRepository.cs`
- [Trip outbox worker](https://github.com/uvaestudantes/noponto-backend/blob/main/NoPonto/2-Application/Services/BackgroundServices/ViagemOutboxWorker.cs): `NoPonto/2-Application/Services/BackgroundServices/ViagemOutboxWorker.cs`

### Other components

- **Mobile app**
- **Transit providers**

## Connections

- Mobile app → ASP.NET API: HTTP / SignalR
- ASP.NET API → PostgreSQL / PostGIS: SQL / PostGIS
- ASP.NET API → Redis snapshots: RESP
- ASP.NET API → Transit providers: HTTP
- ASP.NET API → GPS polling and validation: hosts workers (evidence: `NoPonto/Program.cs`)
- GPS polling and validation → GPS sources: collects positions (evidence: `NoPonto/2-Application/Services/GPS/GpsPollingService.cs`)
- GPS polling and validation → GPS matching: enriches batch (evidence: `NoPonto/2-Application/Services/GPS/GpsPollingService.cs`)
- GPS polling and validation → ETA client: requests predictions (evidence: `NoPonto/2-Application/Services/GPS/GpsPollingService.cs`)
- GPS polling and validation → Redis snapshots: updates snapshots
- GPS polling and validation → GPS SignalR hub: publishes updates (evidence: `NoPonto/2-Application/Services/GPS/GpsPollingService.cs`)
- GPS matching → PostgreSQL / PostGIS: matches via PostGIS
- GPS polling and validation → Observed trips: updates trip state (evidence: `NoPonto/2-Application/Services/GPS/GpsPollingService.cs`)
- Observed trips → Trip repository: persists operations (evidence: `NoPonto/5-Testes/GpsPipelineDisposableIntegrationTests.EvidenceContinuity.cs`)
- Trip repository → PostgreSQL / PostGIS: stores durable state (evidence: `NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs`)
- Trip repository → Redis snapshots: projects state (evidence: `NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs`)
- Observed-trip repository → Redis snapshots: updates trip state (evidence: `NoPonto/4-Data/Repositories/ViagemObservadaRepository.cs`)
- Trip repository → Trip outbox worker: writes outbox (evidence: `NoPonto/4-Data/Repositories/ViagemOperacionalRepository.cs`)
- ASP.NET API → Structural imports: registers import command (evidence: `NoPonto/Program.cs`)
- Structural imports → PostgreSQL / PostGIS: publishes versions
- ASP.NET API → Sentinel scheduler: hosts rail services (evidence: `NoPonto/Program.cs`)
- Rail schedules → PostgreSQL / PostGIS: loads schedules
- Sentinel scheduler → Rail tracking: schedules evidence tracking
- Rail tracking → Position estimation: supplies observations
- Position estimation → Rail vehicle API: serves inferred positions
- ASP.NET API → Stop events: hosts event services
- Stop events → PostgreSQL / PostGIS: stores history
- ASP.NET API → Telemetry and ETA V2: hosts workers (evidence: `NoPonto/Program.cs`)
- Telemetry and ETA V2 → PostgreSQL / PostGIS: persists telemetry
- ASP.NET API → Structure endpoints: serves structure