Module Structure

Overview

Lichess is organized as a modular monolith with 83 Scala modules in the modules/ directory. Each module represents a distinct feature or domain, promoting separation of concerns and maintainability.

Architecture Principles

The module structure follows a layered dependency architecture:

Low-level modules provide core functionality (database, common utilities)
Mid-level modules implement domain logic (game, user, rating)
High-level modules provide features and UI (tournament, study, web)

Key Benefits

Separation of concerns: Each module handles a specific domain
Clear dependencies: Modules declare explicit dependencies
Testability: Modules can be tested in isolation
Compilation order: sbt compiles modules in dependency order

Module Layers

The build.sbt file defines the compilation order based on dependency levels:

Level 1: Foundation

core, coreI18n

core: Base types, utilities, and domain primitives
coreI18n: Internationalization core functionality

Level 2: Presentation

ui, common, tree

ui: UI templates and routing (uses scalatags)
common: Shared utilities used across modules
tree: Chess move tree data structures

Level 3: Infrastructure

db, room, search

db: MongoDB database access layer
room: Real-time room functionality (chat, presence)
search: Elasticsearch integration

Level 4: Services

memo, rating

memo: Caching and memoization (using Caffeine)
rating: Glicko-2 rating calculations

Level 5: Core Domain

game, gathering, study, user, puzzle, analyse,
report, pref, chat, playban, lobby, mailer, oauth

Key modules:

game: Chess game logic and storage
user: User accounts and profiles
study: Shared chess analysis boards
puzzle: Chess puzzles and training
analyse: Computer analysis integration
tournament: Tournament system base
gathering: Base for tournaments and simuls

Level 6: Analytics

insight, evaluation, storm

insight: Player statistics and insights
evaluation: Position evaluation
storm: Speed puzzle training mode

Level 7: Features

relay, security, tournament, plan, round, swiss,
fishnet, tutor, mod, challenge, web, team, forum,
streamer, simul, activity, msg, ublog, notifyModule,
clas, perfStat, opening, timeline, setup, video,
fide, title, push, pool, relation, tv, coordinate,
feed, history, recap, shutup, appeal, irc, explorer,
learn, event, coach, practice, evalCache, irwin,
bot, racer, cms, i18n, jsBot, socket, bookmark,
studySearch, gameSearch, forumSearch, teamSearch

Key Modules Explained

Game and Play

game

modules/game/src/main/ Core game logic:

Game state management
Move validation (via scalachess)
Game storage and retrieval
PGN export

module("game",
  Seq(tree, rating, memo),
  Seq(compression) ++ tests.bundle
)

round

modules/round/src/main/ Live game rounds:

Real-time game orchestration
Move processing
Time control
Resignation/draw offers

module("round",
  Seq(room, game, user, playban, pref, chat),
  Seq(hasher, kamon.core, lettuce) ++ tests.bundle
)

user

modules/user/src/main/ User management:

User accounts
Authentication
Profiles and preferences
Rankings and leaderboards

team

modules/team/src/main/ Team functionality:

Team creation and management
Team forums
Team tournaments

relation

modules/relation/src/main/ Social connections:

Following/followers
Blocking
Friend relationships

Learning and Training

puzzle

modules/puzzle/src/main/ Puzzle system:

Puzzle database
Difficulty rating
User progress tracking

study

modules/study/src/main/ Collaborative analysis:

Shared analysis boards
Chapters and variations
Comments and glyphs
Study search (studySearch)

learn

modules/learn/src/main/ Interactive chess lessons for beginners.

Tournaments and Events

tournament

modules/tournament/src/main/ Arena tournaments:

Tournament creation
Pairing algorithms
Standings calculation
Berserk mode

swiss

modules/swiss/src/main/ Swiss-system tournaments with perfect pairing.

simul

modules/simul/src/main/ Simultaneous exhibitions where one player faces many.

Analysis and AI

analyse

modules/analyse/src/main/ Game analysis:

Server-side analysis requests
Analysis display
Computer evaluation

fishnet

modules/fishnet/src/main/ Stockfish cluster integration:

Analysis job distribution
Move evaluation
Client management

evalCache

modules/evalCache/src/main/ Caches position evaluations to avoid redundant analysis.

Moderation

mod

modules/mod/src/main/ Moderation tools:

User reports
Mod actions
IP/email checks

report

modules/report/src/main/ User reporting system.

irwin

modules/irwin/src/main/ Cheat detection integration.

appeal

modules/appeal/src/main/ User ban appeals.

Infrastructure

db

modules/db/src/main/ Database utilities:

MongoDB connection management
Collection helpers
Query builders

socket

modules/socket/src/main/ WebSocket integration with lila-ws:

Socket communication
Redis pub/sub
User presence

search

modules/search/src/main/ Elasticsearch integration for game/forum/study/team search.

mailer

modules/mailer/src/main/ Email notifications and transactional emails.

Web and API

web

modules/web/src/main/ Web server and HTTP handling:

Play Framework integration
Request routing
Response rendering

api

modules/api/src/main/ Public HTTP API:

REST endpoints
API documentation
Rate limiting
OAuth integration

Module Definition

Modules are defined in build.sbt using the module() helper:

lazy val game = module("game",
  Seq(tree, rating, memo),  // Dependencies on other modules
  Seq(compression) ++ tests.bundle  // External library dependencies
)