# lllnightlll/datamatch_analytics architecture

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

- Interactive diagram: https://gitdiagram.com/lllnightlll/datamatch_analytics
- Repository: https://github.com/lllnightlll/datamatch_analytics

## Overview

Datamatch Analytics is a hockey-data analytics application that serves dataset inventory, expected-goals, action-value, time-on-ice, player-rating, validation, and rating-deliverable results. Its principal workflow is an HTTP request routed to a service, which loads match, roster, or event data and computes a report; rating combines reconstructed ice time, action credits, and stint-based modeling. The graph also shows the shared DuckDB access layer. Several service and domain connections are supported by the source index, but unsampled implementations are not assumed to have additional dependencies.

Main entry points: [`src/main/kotlin/app/api/InventoryHttpServer.kt`](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/api/InventoryHttpServer.kt) (HTTP API), [`src/main/kotlin/app/service/RatingService.kt`](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/RatingService.kt) (Player ratings), [`src/main/kotlin/app/data`](https://github.com/lllnightlll/datamatch_analytics/tree/main/src/main/kotlin/app/data) (Dataset repositories), [`src/main/kotlin/app/service/ActionValueService.kt`](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/ActionValueService.kt) (Action value)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_app["Application wiring<br/>[DatamatchApp.kt]"]
  node_http["HTTP API"]
end

subgraph group_data["Data access"]
  node_repositories["Dataset repositories"]
  node_duckdb["DuckDB session<br/>[DuckDbSession.kt]"]
end

subgraph group_analytics["Analytics services"]
  node_inventory["Dataset inventory"]
  node_xgservice["Expected goals<br/>[XgService.kt]"]
  node_threatservice["Action value"]
  node_toiservice["Time on ice<br/>[ToiService.kt]"]
  node_ratingservice["Player ratings<br/>[RatingService.kt]"]
  node_validation["Rating validation"]
end

subgraph group_domain["Domain computation"]
  node_xgmodel["Shot model"]
  node_threatmodel["Threat valuation<br/>[ActionValuator.kt]"]
  node_toimodel["TOI reconstruction"]
  node_stints["On-ice stints"]
  node_rapm["Ridge RAPM<br/>[RidgeRapm.kt]"]
  node_ratingaggregate["Stint aggregation"]
  node_validationledger["Half-split ledger"]
  node_splitter["Match splitter"]
end

subgraph group_delivery["Reports and exports"]
  node_deliverable["Ratings export"]
  node_exporter["Official CSV exporter"]
end

node_browser(("Analytics user"))
node_datasets[("Analytics datasets")]

node_browser -.->|"requests results"| node_http
node_app -->|"starts server"| node_http
node_http -->|"routes requests"| node_inventory
node_http -->|"routes requests"| node_xgservice
node_http -->|"routes requests"| node_threatservice
node_http -->|"routes requests"| node_toiservice
node_http -->|"routes requests"| node_ratingservice
node_http -->|"routes requests"| node_validation
node_http -->|"routes requests"| node_deliverable
node_inventory -->|"loads inventory data"| node_repositories
node_xgservice -->|"loads shot data"| node_repositories
node_xgservice -->|"fits model"| node_xgmodel
node_threatservice -->|"reads event policy"| node_inventory
node_threatservice -->|"loads event data"| node_repositories
node_threatservice -->|"values actions"| node_threatmodel
node_toiservice -->|"loads shifts"| node_repositories
node_toiservice -->|"reconstructs TOI"| node_toimodel
node_ratingservice -->|"reads TOI"| node_toiservice
node_ratingservice -->|"reads action credits"| node_threatservice
node_ratingservice -->|"loads games and shifts"| node_repositories
node_ratingservice -->|"builds stints"| node_stints
node_ratingservice -->|"aggregates stints"| node_ratingaggregate
node_ratingservice -->|"fits ratings"| node_rapm
node_validation -->|"loads validation data"| node_repositories
node_validation -->|"builds stints"| node_stints
node_validation -->|"reads credits"| node_threatservice
node_validation -->|"records evidence"| node_validationledger
node_validationledger -->|"uses match halves"| node_splitter
node_deliverable -->|"exports report"| node_ratingservice
node_deliverable -->|"writes CSV"| node_exporter
node_repositories -->|"queries"| node_duckdb
node_duckdb -->|"reads files"| node_datasets

click node_app "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/DatamatchApp.kt"
click node_http "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/api/InventoryHttpServer.kt"
click node_inventory "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/DatasetInventoryService.kt"
click node_xgservice "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/XgService.kt"
click node_threatservice "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/ActionValueService.kt"
click node_toiservice "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/ToiService.kt"
click node_ratingservice "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/RatingService.kt"
click node_validation "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/ValidationService.kt"
click node_deliverable "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/DeliverableService.kt"
click node_repositories "https://github.com/lllnightlll/datamatch_analytics/tree/main/src/main/kotlin/app/data"
click node_duckdb "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/data/DuckDbSession.kt"
click node_xgmodel "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/xg/LogisticRegression.kt"
click node_threatmodel "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/threat/ActionValuator.kt"
click node_toimodel "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/toi/ToiReconstructor.kt"
click node_stints "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/OnIceStintBuilder.kt"
click node_rapm "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/RidgeRapm.kt"
click node_ratingaggregate "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/StintActionAggregator.kt"
click node_validationledger "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/validate/PlayerHalfLedger.kt"
click node_splitter "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/validate/MatchHalfSplitter.kt"
click node_exporter "https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/OfficialRatingsExporter.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_app,node_http,node_browser toneBlue
class node_repositories,node_duckdb,node_datasets toneAmber
class node_inventory,node_xgservice,node_threatservice,node_toiservice,node_ratingservice,node_validation toneMint
class node_xgmodel,node_threatmodel,node_toimodel,node_stints,node_rapm,node_ratingaggregate,node_validationledger,node_splitter toneRose
class node_deliverable,node_exporter toneIndigo
```

## Components

### Application entry

- [Application wiring](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/DatamatchApp.kt): `src/main/kotlin/app/DatamatchApp.kt`
- [HTTP API](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/api/InventoryHttpServer.kt): `src/main/kotlin/app/api/InventoryHttpServer.kt`

### Data access

- [Dataset repositories](https://github.com/lllnightlll/datamatch_analytics/tree/main/src/main/kotlin/app/data): `src/main/kotlin/app/data`
- [DuckDB session](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/data/DuckDbSession.kt): `src/main/kotlin/app/data/DuckDbSession.kt`

### Analytics services

- [Dataset inventory](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/DatasetInventoryService.kt): `src/main/kotlin/app/service/DatasetInventoryService.kt`
- [Expected goals](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/XgService.kt): `src/main/kotlin/app/service/XgService.kt`
- [Action value](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/ActionValueService.kt): `src/main/kotlin/app/service/ActionValueService.kt`
- [Time on ice](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/ToiService.kt): `src/main/kotlin/app/service/ToiService.kt`
- [Player ratings](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/RatingService.kt): `src/main/kotlin/app/service/RatingService.kt`
- [Rating validation](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/ValidationService.kt): `src/main/kotlin/app/service/ValidationService.kt`

### Domain computation

- [Shot model](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/xg/LogisticRegression.kt): `src/main/kotlin/app/domain/xg/LogisticRegression.kt`
- [Threat valuation](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/threat/ActionValuator.kt): `src/main/kotlin/app/domain/threat/ActionValuator.kt`
- [TOI reconstruction](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/toi/ToiReconstructor.kt): `src/main/kotlin/app/domain/toi/ToiReconstructor.kt`
- [On-ice stints](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/OnIceStintBuilder.kt): `src/main/kotlin/app/domain/rating/OnIceStintBuilder.kt`
- [Ridge RAPM](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/RidgeRapm.kt): `src/main/kotlin/app/domain/rating/RidgeRapm.kt`
- [Stint aggregation](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/StintActionAggregator.kt): `src/main/kotlin/app/domain/rating/StintActionAggregator.kt`
- [Half-split ledger](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/validate/PlayerHalfLedger.kt): `src/main/kotlin/app/domain/validate/PlayerHalfLedger.kt`
- [Match splitter](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/validate/MatchHalfSplitter.kt): `src/main/kotlin/app/domain/validate/MatchHalfSplitter.kt`

### Reports and exports

- [Ratings export](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/service/DeliverableService.kt): `src/main/kotlin/app/service/DeliverableService.kt`
- [Official CSV exporter](https://github.com/lllnightlll/datamatch_analytics/blob/main/src/main/kotlin/app/domain/rating/OfficialRatingsExporter.kt): `src/main/kotlin/app/domain/rating/OfficialRatingsExporter.kt`

### Other components

- **Analytics user**
- **Analytics datasets**

## Connections

- Analytics user → HTTP API: requests results
- Application wiring → HTTP API: starts server (evidence: `src/main/kotlin/app/DatamatchApp.kt`)
- HTTP API → Dataset inventory: routes requests (evidence: `src/main/kotlin/app/api/InventoryHttpServer.kt`)
- HTTP API → Expected goals: routes requests (evidence: `src/main/kotlin/app/api/InventoryHttpServer.kt`)
- HTTP API → Action value: routes requests (evidence: `src/main/kotlin/app/api/InventoryHttpServer.kt`)
- HTTP API → Time on ice: routes requests (evidence: `src/main/kotlin/app/api/InventoryHttpServer.kt`)
- HTTP API → Player ratings: routes requests (evidence: `src/main/kotlin/app/api/InventoryHttpServer.kt`)
- HTTP API → Rating validation: routes requests (evidence: `src/main/kotlin/app/api/InventoryHttpServer.kt`)
- HTTP API → Ratings export: routes requests (evidence: `src/main/kotlin/app/api/InventoryHttpServer.kt`)
- Dataset inventory → Dataset repositories: loads inventory data (evidence: `src/main/kotlin/app/service/DatasetInventoryService.kt`)
- Expected goals → Dataset repositories: loads shot data (evidence: `src/main/kotlin/app/service/XgService.kt`)
- Expected goals → Shot model: fits model (evidence: `src/main/kotlin/app/service/XgService.kt`)
- Action value → Dataset inventory: reads event policy (evidence: `src/main/kotlin/app/service/ActionValueService.kt`)
- Action value → Dataset repositories: loads event data (evidence: `src/main/kotlin/app/service/ActionValueService.kt`)
- Action value → Threat valuation: values actions (evidence: `src/main/kotlin/app/service/ActionValueService.kt`)
- Time on ice → Dataset repositories: loads shifts (evidence: `src/main/kotlin/app/service/ToiService.kt`)
- Time on ice → TOI reconstruction: reconstructs TOI (evidence: `src/main/kotlin/app/service/ToiService.kt`)
- Player ratings → Time on ice: reads TOI (evidence: `src/main/kotlin/app/service/RatingService.kt`)
- Player ratings → Action value: reads action credits (evidence: `src/main/kotlin/app/service/RatingService.kt`)
- Player ratings → Dataset repositories: loads games and shifts (evidence: `src/main/kotlin/app/service/RatingService.kt`)
- Player ratings → On-ice stints: builds stints (evidence: `src/main/kotlin/app/service/RatingService.kt`)
- Player ratings → Stint aggregation: aggregates stints (evidence: `src/main/kotlin/app/service/RatingService.kt`)
- Player ratings → Ridge RAPM: fits ratings (evidence: `src/main/kotlin/app/service/RatingService.kt`)
- Rating validation → Dataset repositories: loads validation data (evidence: `src/main/kotlin/app/service/ValidationService.kt`)
- Rating validation → On-ice stints: builds stints (evidence: `src/main/kotlin/app/service/ValidationService.kt`)
- Rating validation → Action value: reads credits (evidence: `src/main/kotlin/app/service/ValidationService.kt`)
- Rating validation → Half-split ledger: records evidence (evidence: `src/main/kotlin/app/service/ValidationService.kt`)
- Half-split ledger → Match splitter: uses match halves (evidence: `src/main/kotlin/app/domain/validate/PlayerHalfLedger.kt`)
- Ratings export → Player ratings: exports report (evidence: `src/main/kotlin/app/service/DeliverableService.kt`)
- Ratings export → Official CSV exporter: writes CSV (evidence: `src/main/kotlin/app/service/DeliverableService.kt`)
- Dataset repositories → DuckDB session: queries (evidence: `src/main/kotlin/app/data/GameRepository.kt`)
- DuckDB session → Analytics datasets: reads files
