README

Iodid

Open platform for League of Legends data: competitive profile, analytics, leaderboards and live metadata. Canonical source: Beebot com.safjnest.lol.

Iodid is Beebot's public layer dedicated to League of Legends. It exposes already normalized and indexed data (Summoner, Rank, Match, Participant, ProfileStatistics, Mastery) via stable HTTP APIs and provides tools for dashboards, Discord bots and balance experiments.

It is not a raw wrapper around Riot APIs: data goes through validation, canonicalization and read-through caching before being served. Clients receive ready-to-use models.

What it does

Complete profile — SummonerView aggregates identity, ranks, masteries, statistics and recent matches with consistent ResponseMetadata.
Ranked history — RankHistory with queries by season/patch/view and timeStart ordering.
Leaderboards — LeaderboardPage with pagination and MMR distribution.
Champion analytics — tier lists, statistics per patch/queue/rank/region/lane, optimal builds.
Records and matchups — global and per-profile records, matchup matrix per champion/opponent/duo.
Live game — direct read of the ongoing match state.

Stack

Component	Version	Reference	Role
Java	25	`pom.xml:15` `maven.compiler.source` / `java.version`	toolchain, compilation, runtime
Spring Framework	7.0.8	`pom.xml:18` `spring.version`	`spring-context`, `spring-webmvc` — controllers, parameter validation, error handling
Tomcat Embed	11.0.10	`pom.xml:19` `tomcat.version`	embedded HTTP runtime
MongoDB Driver Sync	5.8.0	`pom.xml:276`	sole runtime persistence — all LoL documents
Redis Jedis	5.1.0	`pom.xml:341`	cache only (`RedisClient`, `RedisKey`) — no authoritative data
R4J (Riot API for Java)	2.8.1	`pom.xml:261`	official Riot client, canonical enums re-exported via utils
Jackson	2.21.4	`pom.xml:134`	JSON serialization (`jackson-databind`, `jackson-datatype-jsr310`)
Caffeine	3.1.8	`pom.xml:244`	local in-memory cache
FastUtil	8.5.16	`pom.xml:108`	high-performance primitive structures
JDA	6.3.1	`pom.xml:209`	Discord bot — not used by the LoL flow, present only for Beebot integration

Full library details: see libraries.mdx.

Versions are defined as Maven properties in pom.xml:13 and referenced in <dependency> blocks. R4J enums (LeagueShard, GameQueueType, TierType, LaneType) are not exposed directly: they are wrapped by TierDivisionUtils, GameQueueTypeUtils, LeagueShardUtils, LaneTypeUtils in src/main/java/com/safjnest/lol/utils/.

API baseUrl

text

https://api.safjnest.com/api/lol

All routes are prefixed with /{shard} validated via LolApiParameters.requiredShard in src/main/java/com/safjnest/spring/controller/LolApiParameters.java:163. See getting-started.mdx and index.mdx for quick start.

Controller base path: src/main/java/com/safjnest/spring/controller/LolController.java:36 (@RequestMapping("/api/lol/{shard}")), ChampionController, LeaderboardController, RecordsController.

Production: https://api.safjnest.com/api/lol
No authentication required (public API, server-side parameter validation)
Uniform error envelope: src/main/java/com/safjnest/spring/dto/LolApiError.java:5

Documentation structure

File	Content
`index.mdx`	hero, tagline, curl quick start, feature list
`getting-started.mdx`	how to call the APIs, `LolApiParameters`, `LolApiError`, `ApiResult`, pagination
`concepts.mdx`	domain glossary: puuid, riotId, shard, filter, MMR, staleness
`architecture.mdx`	Mongo/Redis, 3 schedulers, `QueueHandler`/`Router`/`Registry`/`JobQueue`, match ingestion
`libraries.mdx`	library table with versions, links and notes `pom.xml:15`

Project principles

Canonical models in com.safjnest.lol.model — Spring controllers return models directly, without duplicate success DTOs (docs/architecture/README.md:92).
Summoner is the canonical identity (src/main/java/com/safjnest/lol/model/summoner/Summoner.java:18).
Rank is the canonical ranked model, Mastery the champion mastery model, riotId stays String (AGENTS.md).
Mongo is the sole runtime store (docs/architecture/README.md:98), Redis is only ephemeral and rebuildable cache.

To contribute: read AGENTS.md, docs/architecture/README.md, the relevant ADR and docs/HANDBOOK.md §5-§7 before any LoL change.