# wardzik4/ztm-backend architecture

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

- Interactive diagram: https://gitdiagram.com/wardzik4/ztm-backend
- Repository: https://github.com/wardzik4/ztm-backend

## Overview

ztm-tracker is a Ktor backend that enriches vehicle data with depot and route information. Its API accepts vehicle details, looks up stored route data, calculates enrichment fields, and returns a unified response. Separately, background jobs poll Warsaw’s ZTM API, cache live locations, and periodically refresh the database. The excerpts show these flows, but not how the application starts or registers them; those links are therefore omitted. The README documents JSON content negotiation, though its registration path is not shown.

Main entry points: [`src/main/kotlin/ZtmSyncJob.kt`](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/ZtmSyncJob.kt) (Background Pollers), [`src/main/kotlin/Routing.kt`](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/Routing.kt) (Enrichment Endpoint), [`src/main/kotlin/DepotCalculator.kt`](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/DepotCalculator.kt) (Depot Calculator), [`src/main/kotlin/VehicleRoutes.kt`](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/VehicleRoutes.kt) (Vehicle Route Table)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_routing["Enrichment Endpoint<br/>[Routing.kt]"]
  node_server["Ktor Entrypoint<br/>[main.kt]"]
  node_serialization["JSON Negotiation<br/>[Serialization.kt]"]
end

subgraph group_ingest["Live Data Ingestion"]
  node_sync["Background Pollers<br/>[ZtmSyncJob.kt]"]
  node_cache["Live GPS Cache<br/>[ZtmSyncJob.kt]"]
end

subgraph group_enrichment["Vehicle Enrichment"]
  node_calculator["Depot Calculator<br/>[DepotCalculator.kt]"]
end

subgraph group_persistence["Persistence"]
  node_table["Vehicle Route Table<br/>[VehicleRoutes.kt]"]
end

subgraph group_contracts["Data Contracts"]
  node_models["Vehicle DTOs"]
  node_mockdata["Route Data Model<br/>[RouteMockData.kt]"]
end

node_client(("API Client"))
node_ztm{{"Warsaw ZTM API"}}
node_database[("Supabase PostgreSQL")]

node_client -->|"requests"| node_routing
node_routing -->|"queries"| node_table
node_routing -->|"calculates depot"| node_calculator
node_routing -->|"reads"| node_database
node_routing -->|"returns response"| node_client
node_sync -->|"polls locations"| node_ztm
node_sync -->|"updates"| node_cache
node_sync -->|"refreshes rows"| node_table
node_sync -->|"writes"| node_database
node_sync -->|"calculates depots"| node_calculator
node_sync -->|"decodes locations"| node_models
node_routing -->|"builds response"| node_models

click node_routing "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/Routing.kt"
click node_server "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/main.kt"
click node_sync "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/ZtmSyncJob.kt"
click node_cache "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/ZtmSyncJob.kt"
click node_calculator "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/DepotCalculator.kt"
click node_table "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/VehicleRoutes.kt"
click node_models "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/ZtmBackendModels.kt"
click node_mockdata "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/RouteMockData.kt"
click node_serialization "https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/Serialization.kt"

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_routing,node_server,node_serialization,node_client toneBlue
class node_sync,node_cache,node_database toneAmber
class node_calculator,node_ztm toneMint
class node_table toneRose
class node_models,node_mockdata toneIndigo
```

## Components

### HTTP API

- [Enrichment Endpoint](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/Routing.kt): `src/main/kotlin/Routing.kt`
- [Ktor Entrypoint](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/main.kt): `src/main/kotlin/main.kt`
- [JSON Negotiation](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/Serialization.kt): `src/main/kotlin/Serialization.kt`

### Live Data Ingestion

- [Background Pollers](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/ZtmSyncJob.kt): `src/main/kotlin/ZtmSyncJob.kt`
- [Live GPS Cache](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/ZtmSyncJob.kt): `src/main/kotlin/ZtmSyncJob.kt`

### Vehicle Enrichment

- [Depot Calculator](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/DepotCalculator.kt): `src/main/kotlin/DepotCalculator.kt`

### Persistence

- [Vehicle Route Table](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/VehicleRoutes.kt): `src/main/kotlin/VehicleRoutes.kt`

### Data Contracts

- [Vehicle DTOs](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/ZtmBackendModels.kt): `src/main/kotlin/ZtmBackendModels.kt`
- [Route Data Model](https://github.com/wardzik4/ztm-backend/blob/main/src/main/kotlin/RouteMockData.kt): `src/main/kotlin/RouteMockData.kt`

### Other components

- **API Client**
- **Warsaw ZTM API**
- **Supabase PostgreSQL**

## Connections

- API Client → Enrichment Endpoint: requests (evidence: `src/main/kotlin/Routing.kt`)
- Enrichment Endpoint → Vehicle Route Table: queries (evidence: `src/main/kotlin/Routing.kt`)
- Enrichment Endpoint → Depot Calculator: calculates depot (evidence: `src/main/kotlin/Routing.kt`)
- Enrichment Endpoint → Supabase PostgreSQL: reads (evidence: `src/main/kotlin/Routing.kt`)
- Enrichment Endpoint → API Client: returns response (evidence: `src/main/kotlin/Routing.kt`)
- Background Pollers → Warsaw ZTM API: polls locations (evidence: `src/main/kotlin/ZtmSyncJob.kt`)
- Background Pollers → Live GPS Cache: updates (evidence: `src/main/kotlin/ZtmSyncJob.kt`)
- Background Pollers → Vehicle Route Table: refreshes rows (evidence: `src/main/kotlin/ZtmSyncJob.kt`)
- Background Pollers → Supabase PostgreSQL: writes (evidence: `src/main/kotlin/ZtmSyncJob.kt`)
- Background Pollers → Depot Calculator: calculates depots (evidence: `src/main/kotlin/ZtmSyncJob.kt`)
- Background Pollers → Vehicle DTOs: decodes locations (evidence: `src/main/kotlin/ZtmSyncJob.kt`)
- Enrichment Endpoint → Vehicle DTOs: builds response (evidence: `src/main/kotlin/Routing.kt`)
