# sander-homelabs/kilometertrackerbackend architecture

> Architecture diagram of the GitHub repository sander-homelabs/kilometertrackerbackend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sander-homelabs/kilometertrackerbackend
- Repository: https://github.com/sander-homelabs/kilometertrackerbackend

## Overview

KilometerTrackerBackend is a Ktor backend. Its evidenced user-facing workflow accepts registration and activation requests, and supports login and refresh-token requests; the corresponding routes dispatch to user-service use cases. JWT handling and persistence are visible internally, as is Knock-backed email delivery. The README provides no capability details, and group/trip modules appear in the tree but their implementation was not sampled, so their behavior and wiring are left unspecified.

Main entry points: [`core/database/src/main/kotlin/di/DatabaseModule.kt`](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/di/DatabaseModule.kt) (Database wiring), [`app/src/main/kotlin/Application.kt`](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/app/src/main/kotlin/Application.kt) (Ktor application), [`features/user/user-api/src/main/kotlin/UserRoutes.kt`](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-api/src/main/kotlin/UserRoutes.kt) (User routes), [`features/user/user-api/src/main/kotlin/AuthRoutes.kt`](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-api/src/main/kotlin/AuthRoutes.kt) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP runtime"]
  node_app["Ktor application<br/>[Application.kt]"]
  node_user_routes["User routes<br/>[UserRoutes.kt]"]
  node_auth_routes["Auth routes<br/>[AuthRoutes.kt]"]
  node_group_feature["Group feature modules"]
  node_trip_feature["Trip feature modules"]
end

subgraph group_user["User lifecycle"]
  node_register["Registration"]
  node_activate["Activation"]
end

subgraph group_auth["Authentication"]
  node_login["Login<br/>[LoginUseCase.kt]"]
  node_refresh["Token refresh"]
  node_token_service["JWT token service<br/>[JwtTokenService.kt]"]
end

subgraph group_infra["Persistence and email"]
  node_token_repo["Refresh token repository"]
  node_user_repo["User repository"]
  node_confirmation_repo["Confirmation codes"]
  node_database_module["Database wiring<br/>[DatabaseModule.kt]"]
  node_email_service["Email delivery<br/>[EmailService.kt]"]
  node_email_workflow["Email workflows<br/>[EmailWorkflow.kt]"]
end

node_client(("API client"))
node_db[("PostgreSQL")]
node_knock["Knock"]

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_user_routes
node_app -->|"registers routes"| node_auth_routes
node_user_routes -->|"dispatches registration"| node_register
node_user_routes -->|"dispatches activation"| node_activate
node_auth_routes -->|"dispatches login"| node_login
node_auth_routes -->|"dispatches refresh"| node_refresh
node_token_service -->|"reads and updates"| node_token_repo
node_database_module -->|"binds repository"| node_user_repo
node_database_module -->|"binds repository"| node_confirmation_repo
node_database_module -->|"binds repository"| node_token_repo
node_user_repo -->|"reads and writes"| node_db
node_confirmation_repo -->|"reads and writes"| node_db
node_token_repo -->|"reads and writes"| node_db
node_email_service -->|"triggers workflows"| node_knock

click node_app "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/app/src/main/kotlin/Application.kt"
click node_user_routes "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-api/src/main/kotlin/UserRoutes.kt"
click node_auth_routes "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-api/src/main/kotlin/AuthRoutes.kt"
click node_register "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/RegisterUserUseCase.kt"
click node_activate "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/ActivateUserUseCase.kt"
click node_login "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/LoginUseCase.kt"
click node_refresh "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/RefreshAccessTokenUseCase.kt"
click node_token_service "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/security/src/main/kotlin/JwtTokenService.kt"
click node_token_repo "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/user/RefreshTokenRepositoryImpl.kt"
click node_user_repo "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/user/UserRepositoryImpl.kt"
click node_confirmation_repo "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/user/UserConfirmationCodeRepositoryImpl.kt"
click node_database_module "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/di/DatabaseModule.kt"
click node_email_service "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/email/src/main/kotlin/EmailService.kt"
click node_email_workflow "https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/email/src/main/kotlin/EmailWorkflow.kt"
click node_group_feature "https://github.com/sander-homelabs/kilometertrackerbackend/tree/main/features/group"
click node_trip_feature "https://github.com/sander-homelabs/kilometertrackerbackend/tree/main/features/trip"

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_app,node_user_routes,node_auth_routes,node_group_feature,node_trip_feature,node_client toneBlue
class node_register,node_activate,node_db toneAmber
class node_login,node_refresh,node_token_service toneMint
class node_token_repo,node_user_repo,node_confirmation_repo,node_database_module,node_email_service,node_email_workflow toneRose
class node_knock toneIndigo
```

## Components

### HTTP runtime

- [Ktor application](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/app/src/main/kotlin/Application.kt): `app/src/main/kotlin/Application.kt`
- [User routes](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-api/src/main/kotlin/UserRoutes.kt): `features/user/user-api/src/main/kotlin/UserRoutes.kt`
- [Auth routes](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-api/src/main/kotlin/AuthRoutes.kt): `features/user/user-api/src/main/kotlin/AuthRoutes.kt`
- [Group feature modules](https://github.com/sander-homelabs/kilometertrackerbackend/tree/main/features/group): `features/group`
- [Trip feature modules](https://github.com/sander-homelabs/kilometertrackerbackend/tree/main/features/trip): `features/trip`

### User lifecycle

- [Registration](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/RegisterUserUseCase.kt): `features/user/user-service/src/main/kotlin/RegisterUserUseCase.kt`
- [Activation](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/ActivateUserUseCase.kt): `features/user/user-service/src/main/kotlin/ActivateUserUseCase.kt`

### Authentication

- [Login](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/LoginUseCase.kt): `features/user/user-service/src/main/kotlin/LoginUseCase.kt`
- [Token refresh](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/features/user/user-service/src/main/kotlin/RefreshAccessTokenUseCase.kt): `features/user/user-service/src/main/kotlin/RefreshAccessTokenUseCase.kt`
- [JWT token service](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/security/src/main/kotlin/JwtTokenService.kt): `core/security/src/main/kotlin/JwtTokenService.kt`

### Persistence and email

- [Refresh token repository](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/user/RefreshTokenRepositoryImpl.kt): `core/database/src/main/kotlin/user/RefreshTokenRepositoryImpl.kt`
- [User repository](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/user/UserRepositoryImpl.kt): `core/database/src/main/kotlin/user/UserRepositoryImpl.kt`
- [Confirmation codes](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/user/UserConfirmationCodeRepositoryImpl.kt): `core/database/src/main/kotlin/user/UserConfirmationCodeRepositoryImpl.kt`
- [Database wiring](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/database/src/main/kotlin/di/DatabaseModule.kt): `core/database/src/main/kotlin/di/DatabaseModule.kt`
- [Email delivery](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/email/src/main/kotlin/EmailService.kt): `core/email/src/main/kotlin/EmailService.kt`
- [Email workflows](https://github.com/sander-homelabs/kilometertrackerbackend/blob/main/core/email/src/main/kotlin/EmailWorkflow.kt): `core/email/src/main/kotlin/EmailWorkflow.kt`

### Other components

- **API client**
- **PostgreSQL**
- **Knock**

## Connections

- API client → Ktor application: sends requests
- Ktor application → User routes: registers routes
- Ktor application → Auth routes: registers routes
- User routes → Registration: dispatches registration
- User routes → Activation: dispatches activation
- Auth routes → Login: dispatches login
- Auth routes → Token refresh: dispatches refresh
- JWT token service → Refresh token repository: reads and updates
- Database wiring → User repository: binds repository
- Database wiring → Confirmation codes: binds repository
- Database wiring → Refresh token repository: binds repository
- User repository → PostgreSQL: reads and writes
- Confirmation codes → PostgreSQL: reads and writes
- Refresh token repository → PostgreSQL: reads and writes
- Email delivery → Knock: triggers workflows