# manu08manu/traintrackerv2-server architecture

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

- Interactive diagram: https://gitdiagram.com/manu08manu/traintrackerv2-server
- Repository: https://github.com/manu08manu/traintrackerv2-server

## Overview

TrainTracker is a Kotlin server for live and scheduled UK rail service information. HTTP users query boards, service histories/details, train units and related data; the server combines timetable/reference feeds with Kafka movement and signalling events, persists state, then serves enriched views. Separate branches provide operator administration, login, Knowledgebase data, and location/reference updates. The graph follows only relationships shown by the excerpts, source index, or application wiring; several route and feed internals were not sampled, so those links are omitted rather than inferred.

Main entry points: [`src/main/kotlin/com/traintracker/server/Application.kt`](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/Application.kt) (HTTP application), [`src/main/kotlin/com/traintracker/server/database/AppDatabase.kt`](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/database/AppDatabase.kt) (Application database), [`src/main/kotlin/com/traintracker/server/cif/CorpusLookup.kt`](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/CorpusLookup.kt) (Station corpus lookup), [`src/main/kotlin/com/traintracker/server/cif/LocationData.kt`](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/LocationData.kt) (Location reference data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_server["HTTP application<br/>[Application.kt]"]
  node_config["Runtime configuration<br/>[Config.kt]"]
  node_db[("Application database<br/>[AppDatabase.kt]")]
end

subgraph group_reference["Timetable and reference"]
  node_cifparser["CIF importer<br/>[CifParser.kt]"]
  node_corpus["Station corpus lookup<br/>[CorpusLookup.kt]"]
  node_locations["Location reference data<br/>[LocationData.kt]"]
  node_cancellations["Schedule cancellations"]
  node_smart["Smart berth lookup<br/>[SmartLookup.kt]"]
  node_rdm["RDM feed watcher<br/>[RdmWatcher.kt]"]
  node_pif["PIF parser<br/>[PifParser.kt]"]
  node_nlc["NLC parser<br/>[NlcParser.kt]"]
end

subgraph group_live["Live rail feeds"]
  node_linx["LINX consumer<br/>[LinxConsumer.kt]"]
  node_writer["Movement writer"]
  node_td["TD consumer<br/>[TdConsumer.kt]"]
  node_correlator["TD correlator<br/>[TdCorrelator.kt]"]
  node_tdstore["TD state store<br/>[TdStore.kt]"]
  node_allocation["Allocation consumer"]
end

subgraph group_serving["Rail queries"]
  node_routes["Rail query routes<br/>[BoardQuery.kt]"]
  node_service["Service detail routes"]
  node_unit["Unit query<br/>[UnitQuery.kt]"]
end

subgraph group_admin["Administration and integrations"]
  node_authroutes["Authentication routes<br/>[AuthRoutes.kt]"]
  node_authdb[("User sessions<br/>[AuthDatabase.kt]")]
  node_adminroutes["Admin routes<br/>[AdminRoutes.kt]"]
  node_admindata["Admin data<br/>[AdminData.kt]"]
  node_kbroute["Knowledgebase routes<br/>[KbRoutes.kt]"]
  node_kb["Knowledgebase client<br/>[KbClient.kt]"]
end

node_user(("Web user"))
node_kafka["Rail event brokers"]
node_kbservice["Rail Knowledgebase"]

node_user -->|"requests"| node_server
node_server -->|"configures"| node_config
node_server -->|"initializes"| node_db
node_server -->|"initializes"| node_corpus
node_server -->|"registers"| node_locations
node_server -->|"starts"| node_smart
node_server -->|"starts"| node_linx
node_server -->|"starts"| node_td
node_server -->|"starts"| node_allocation
node_cifparser -->|"imports schedules"| node_db
node_cifparser -->|"uses lookup"| node_corpus
node_cifparser -->|"uses cancellations"| node_cancellations
node_locations -->|"registers feeds"| node_rdm
node_locations -->|"parses feed"| node_pif
node_locations -->|"parses feed"| node_nlc
node_locations -->|"saves mappings"| node_db
node_smart -->|"registers feed"| node_rdm
node_linx -->|"consumes events"| node_kafka
node_td -->|"consumes events"| node_kafka
node_linx -->|"writes movements"| node_writer
node_writer -->|"checks references"| node_corpus
node_writer -->|"reports movement"| node_correlator
node_writer -->|"stores movements"| node_db
node_td -->|"correlates events"| node_correlator
node_correlator -->|"updates state"| node_tdstore
node_allocation -->|"stores allocations"| node_db
node_server -.->|"mounts routes"| node_routes
node_server -.->|"mounts routes"| node_service
node_routes -->|"queries services"| node_db
node_routes -->|"resolves stations"| node_corpus
node_routes -->|"checks schedules"| node_cancellations
node_routes -->|"reads movements"| node_writer
node_service -->|"queries service"| node_db
node_service -->|"resolves locations"| node_corpus
node_service -->|"checks cancellation"| node_cancellations
node_unit -->|"queries units"| node_db
node_unit -->|"resolves locations"| node_corpus
node_authroutes -->|"authenticates users"| node_authdb
node_adminroutes -->|"manages operators"| node_admindata
node_adminroutes -->|"updates references"| node_corpus
node_kbroute -->|"requests data"| node_kb
node_kb -->|"fetches rail data"| node_kbservice

click node_server "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/Application.kt"
click node_config "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/Config.kt"
click node_db "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/database/AppDatabase.kt"
click node_cifparser "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/CifParser.kt"
click node_corpus "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/CorpusLookup.kt"
click node_locations "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/LocationData.kt"
click node_cancellations "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/ScheduleCancellations.kt"
click node_smart "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/SmartLookup.kt"
click node_rdm "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/rdm/RdmWatcher.kt"
click node_pif "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/rdm/PifParser.kt"
click node_nlc "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/rdm/NlcParser.kt"
click node_linx "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/LinxConsumer.kt"
click node_writer "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/LinxMovementWriter.kt"
click node_td "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/TdConsumer.kt"
click node_correlator "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/TdCorrelator.kt"
click node_tdstore "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/TdStore.kt"
click node_allocation "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/AllocationConsumer.kt"
click node_routes "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/BoardQuery.kt"
click node_service "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/ServiceDetailRoutes.kt"
click node_unit "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/UnitQuery.kt"
click node_authroutes "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/auth/AuthRoutes.kt"
click node_authdb "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/auth/AuthDatabase.kt"
click node_adminroutes "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/AdminRoutes.kt"
click node_admindata "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/database/AdminData.kt"
click node_kbroute "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/KbRoutes.kt"
click node_kb "https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kb/KbClient.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_server,node_config,node_db,node_user toneBlue
class node_cifparser,node_corpus,node_locations,node_cancellations,node_smart,node_rdm,node_pif,node_nlc toneAmber
class node_linx,node_writer,node_td,node_correlator,node_tdstore,node_allocation toneMint
class node_routes,node_service,node_unit toneRose
class node_authroutes,node_authdb,node_adminroutes,node_admindata,node_kbroute,node_kb,node_kafka,node_kbservice toneIndigo
```

## Components

### Server runtime

- [HTTP application](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/Application.kt): `src/main/kotlin/com/traintracker/server/Application.kt`
- [Runtime configuration](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/Config.kt): `src/main/kotlin/com/traintracker/server/Config.kt`
- [Application database](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/database/AppDatabase.kt): `src/main/kotlin/com/traintracker/server/database/AppDatabase.kt`

### Timetable and reference

- [CIF importer](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/CifParser.kt): `src/main/kotlin/com/traintracker/server/cif/CifParser.kt`
- [Station corpus lookup](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/CorpusLookup.kt): `src/main/kotlin/com/traintracker/server/cif/CorpusLookup.kt`
- [Location reference data](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/LocationData.kt): `src/main/kotlin/com/traintracker/server/cif/LocationData.kt`
- [Schedule cancellations](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/ScheduleCancellations.kt): `src/main/kotlin/com/traintracker/server/cif/ScheduleCancellations.kt`
- [Smart berth lookup](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/cif/SmartLookup.kt): `src/main/kotlin/com/traintracker/server/cif/SmartLookup.kt`
- [RDM feed watcher](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/rdm/RdmWatcher.kt): `src/main/kotlin/com/traintracker/server/rdm/RdmWatcher.kt`
- [PIF parser](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/rdm/PifParser.kt): `src/main/kotlin/com/traintracker/server/rdm/PifParser.kt`
- [NLC parser](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/rdm/NlcParser.kt): `src/main/kotlin/com/traintracker/server/rdm/NlcParser.kt`

### Live rail feeds

- [LINX consumer](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/LinxConsumer.kt): `src/main/kotlin/com/traintracker/server/kafka/LinxConsumer.kt`
- [Movement writer](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/LinxMovementWriter.kt): `src/main/kotlin/com/traintracker/server/kafka/LinxMovementWriter.kt`
- [TD consumer](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/TdConsumer.kt): `src/main/kotlin/com/traintracker/server/kafka/TdConsumer.kt`
- [TD correlator](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/TdCorrelator.kt): `src/main/kotlin/com/traintracker/server/kafka/TdCorrelator.kt`
- [TD state store](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/TdStore.kt): `src/main/kotlin/com/traintracker/server/kafka/TdStore.kt`
- [Allocation consumer](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kafka/AllocationConsumer.kt): `src/main/kotlin/com/traintracker/server/kafka/AllocationConsumer.kt`

### Rail queries

- [Rail query routes](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/BoardQuery.kt): `src/main/kotlin/com/traintracker/server/routes/BoardQuery.kt`
- [Service detail routes](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/ServiceDetailRoutes.kt): `src/main/kotlin/com/traintracker/server/routes/ServiceDetailRoutes.kt`
- [Unit query](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/UnitQuery.kt): `src/main/kotlin/com/traintracker/server/routes/UnitQuery.kt`

### Administration and integrations

- [Authentication routes](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/auth/AuthRoutes.kt): `src/main/kotlin/com/traintracker/server/auth/AuthRoutes.kt`
- [User sessions](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/auth/AuthDatabase.kt): `src/main/kotlin/com/traintracker/server/auth/AuthDatabase.kt`
- [Admin routes](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/AdminRoutes.kt): `src/main/kotlin/com/traintracker/server/routes/AdminRoutes.kt`
- [Admin data](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/database/AdminData.kt): `src/main/kotlin/com/traintracker/server/database/AdminData.kt`
- [Knowledgebase routes](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/routes/KbRoutes.kt): `src/main/kotlin/com/traintracker/server/routes/KbRoutes.kt`
- [Knowledgebase client](https://github.com/manu08manu/traintrackerv2-server/blob/main/src/main/kotlin/com/traintracker/server/kb/KbClient.kt): `src/main/kotlin/com/traintracker/server/kb/KbClient.kt`

### Other components

- **Web user**
- **Rail event brokers**
- **Rail Knowledgebase**

## Connections

- Web user → HTTP application: requests (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → Runtime configuration: configures (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → Application database: initializes (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → Station corpus lookup: initializes (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → Location reference data: registers (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → Smart berth lookup: starts (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → LINX consumer: starts (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → TD consumer: starts (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- HTTP application → Allocation consumer: starts (evidence: `src/main/kotlin/com/traintracker/server/Application.kt`)
- CIF importer → Application database: imports schedules (evidence: `src/main/kotlin/com/traintracker/server/cif/CifParser.kt`)
- CIF importer → Station corpus lookup: uses lookup (evidence: `src/main/kotlin/com/traintracker/server/cif/CifParser.kt`)
- CIF importer → Schedule cancellations: uses cancellations (evidence: `src/main/kotlin/com/traintracker/server/cif/CifParser.kt`)
- Location reference data → RDM feed watcher: registers feeds (evidence: `src/main/kotlin/com/traintracker/server/cif/LocationData.kt`)
- Location reference data → PIF parser: parses feed (evidence: `src/main/kotlin/com/traintracker/server/cif/LocationData.kt`)
- Location reference data → NLC parser: parses feed (evidence: `src/main/kotlin/com/traintracker/server/cif/LocationData.kt`)
- Location reference data → Application database: saves mappings (evidence: `src/main/kotlin/com/traintracker/server/cif/LocationData.kt`)
- Smart berth lookup → RDM feed watcher: registers feed (evidence: `src/main/kotlin/com/traintracker/server/cif/SmartLookup.kt`)
- LINX consumer → Rail event brokers: consumes events (evidence: `src/main/kotlin/com/traintracker/server/kafka/LinxConsumer.kt`)
- TD consumer → Rail event brokers: consumes events (evidence: `src/main/kotlin/com/traintracker/server/kafka/TdConsumer.kt`)
- LINX consumer → Movement writer: writes movements (evidence: `src/main/kotlin/com/traintracker/server/kafka/LinxConsumer.kt`)
- Movement writer → Station corpus lookup: checks references (evidence: `src/main/kotlin/com/traintracker/server/kafka/LinxMovementWriter.kt`)
- Movement writer → TD correlator: reports movement (evidence: `src/main/kotlin/com/traintracker/server/kafka/LinxMovementWriter.kt`)
- Movement writer → Application database: stores movements (evidence: `src/main/kotlin/com/traintracker/server/kafka/LinxMovementWriter.kt`)
- TD consumer → TD correlator: correlates events (evidence: `src/main/kotlin/com/traintracker/server/kafka/TdConsumer.kt`)
- TD correlator → TD state store: updates state (evidence: `src/main/kotlin/com/traintracker/server/kafka/TdCorrelator.kt`)
- Allocation consumer → Application database: stores allocations (evidence: `src/main/kotlin/com/traintracker/server/kafka/AllocationConsumer.kt`)
- HTTP application → Rail query routes: mounts routes
- HTTP application → Service detail routes: mounts routes
- Rail query routes → Application database: queries services (evidence: `src/main/kotlin/com/traintracker/server/routes/BoardQuery.kt`)
- Rail query routes → Station corpus lookup: resolves stations (evidence: `src/main/kotlin/com/traintracker/server/routes/BoardQuery.kt`)
- Rail query routes → Schedule cancellations: checks schedules (evidence: `src/main/kotlin/com/traintracker/server/routes/BoardQuery.kt`)
- Rail query routes → Movement writer: reads movements (evidence: `src/main/kotlin/com/traintracker/server/routes/BoardQuery.kt`)
- Service detail routes → Application database: queries service (evidence: `src/main/kotlin/com/traintracker/server/routes/ServiceDetailRoutes.kt`)
- Service detail routes → Station corpus lookup: resolves locations (evidence: `src/main/kotlin/com/traintracker/server/routes/ServiceDetailRoutes.kt`)
- Service detail routes → Schedule cancellations: checks cancellation (evidence: `src/main/kotlin/com/traintracker/server/routes/ServiceDetailRoutes.kt`)
- Unit query → Application database: queries units (evidence: `src/main/kotlin/com/traintracker/server/routes/UnitQuery.kt`)
- Unit query → Station corpus lookup: resolves locations (evidence: `src/main/kotlin/com/traintracker/server/routes/UnitQuery.kt`)
- Authentication routes → User sessions: authenticates users (evidence: `src/main/kotlin/com/traintracker/server/auth/AuthRoutes.kt`)
- Admin routes → Admin data: manages operators (evidence: `src/main/kotlin/com/traintracker/server/routes/AdminRoutes.kt`)
- Admin routes → Station corpus lookup: updates references (evidence: `src/main/kotlin/com/traintracker/server/routes/AdminRoutes.kt`)
- Knowledgebase routes → Knowledgebase client: requests data (evidence: `src/main/kotlin/com/traintracker/server/routes/KbRoutes.kt`)
- Knowledgebase client → Rail Knowledgebase: fetches rail data (evidence: `src/main/kotlin/com/traintracker/server/kb/KbClient.kt`)
