Backend Architecture

Overview

Lichess’s backend is built with Scala 3 and the Play Framework 2.8, following a highly modular architecture that separates concerns into independent modules. The server is fully asynchronous, leveraging Scala Futures and Akka Streams for high-performance concurrent operations.

Technology Stack

Core Technologies

Scala 3: Primary backend language providing type safety and functional programming features
Play Framework 2.8: Web framework handling HTTP requests and routing
Akka: Actor system and streaming library for concurrency
Macwire: Compile-time dependency injection
Scalatags: Type-safe HTML templating
ReactiveMongo: Asynchronous MongoDB driver

Key Dependencies

// From build.sbt
libraryDependencies ++= Seq(
  akka.bundle,           // Akka actors and streams
  playWs.bundle,         // Web services client
  macwire.bundle,        // Dependency injection
  reactivemongo.driver,  // MongoDB async driver
  kamon.core,            // Application monitoring
  scaffeine, caffeine,   // In-memory caching
  lettuce               // Redis client
)

Modular Architecture

Module System

Lichess is organized into 85+ independent modules, each responsible for a specific domain. The build.sbt defines module dependencies in a strict hierarchy:

Level 1: core, coreI18n
Level 2: ui, common, tree
Level 3: db, room, search
Level 4: memo, rating
Level 5: game, gathering, study, user, puzzle, analyse
Level 6+: tournament, round, relay, security, etc.

This dependency hierarchy ensures clean separation and prevents circular dependencies.

Key Modules

Core Modules

core: Foundation types and interfaces used across all modulescommon: Shared utilities, caching, text processingdb: MongoDB connection management and database abstractionsmemo: Caching layer with Caffeine/Scaffeine integrationi18n: Internationalization supporting 140+ languages

Game Domain Modules

game: Game data models, moves, PGN handling

Location: modules/game/src/main/
Dependencies: tree, rating, memo
Features: Game compression, move validation, game queries

round: Live game management and real-time play

Location: modules/round/src/main/
Dependencies: room, game, user, playban, pref, chat
Features: Move processing, game lifecycle, actor-based game instances

analyse: Computer analysis and engine evaluation

Dependencies: tree, memo, ui
Integrates with Fishnet for Stockfish analysis

Game Modes & Features

tournament: Arena and Swiss tournamentssimul: Simultaneous exhibitionspuzzle: Tactical puzzles and trainingstudy: Shared analysis boards and studiesrelay: Broadcasting live games

Application Initialization

The application bootstraps through a dependency injection hierarchy defined in app/Env.scala:

final class Env(
    val config: Configuration,
    val controllerComponents: ControllerComponents,
    environment: Environment,
    shutdown: akka.actor.CoordinatedShutdown
)(using val system: akka.actor.ActorSystem, executor: Executor):
  
  // Core infrastructure
  val mongo: lila.db.Env = wire[lila.db.Env]
  val memo: lila.memo.Env = wire[lila.memo.Env]
  val socket: lila.socket.Env = wire[lila.socket.Env]
  
  // Domain modules (85+ modules)
  val user: lila.user.Env = wire[lila.user.Env]
  val game: lila.game.Env = wire[lila.game.Env]
  val round: lila.round.Env = wire[lila.round.Env]
  val tournament: lila.tournament.Env = wire[lila.tournament.Env]
  // ... many more modules

Macwire performs compile-time dependency injection, ensuring type safety and eliminating runtime reflection overhead.

Asynchronous Processing

Scala Futures

All I/O operations are non-blocking and return Future[T]:

// Typical pattern for async operations
def getGame(id: GameId): Future[Option[Game]] = 
  gameRepo.find(id)

def analyzeGame(game: Game): Future[Analysis] =
  for
    moves <- Future.successful(game.moves)
    eval  <- fishnetApi.analyze(moves)
  yield Analysis(game, eval)

Akka Streams

Lichess uses Akka Streams for processing continuous data flows:

Real-time game event broadcasting
Large dataset processing (exports, database migrations)
Backpressure handling for external API integrations

Actor System

Critical real-time features use Akka actors:

Game instances: Each active game runs in its own actor
Tournament management: Tournament lifecycle managed by actors
Message routing: Event bus for cross-module communication

Routing

Play Framework’s routing is defined in conf/routes and split across multiple files:

// conf/routes
GET  /game/:id         controllers.Game.show(id: GameId)
POST /game/:id/move    controllers.Round.move(id: GameId)
GET  /tournament/:id   controllers.Tournament.show(id: TourId)

# Include sub-routes
->   /team             team.Routes
->   /clas             clas.Routes

Routes are type-safe with custom parameter extractors for domain types like GameId, UserId, etc.

Controllers

Controllers follow Play Framework conventions:

final class Game(env: Env) extends LilaController(env):
  
  def show(id: GameId) = Open:
    gameRepo.find(id).flatMap:
      case None => NotFound
      case Some(game) => 
        val data = gameData(game)
        Ok(views.game.show(game, data))

Key controller patterns:

Action composition: Authentication, rate limiting via action builders
Async actions: All actions return Future[Result]
JSON responses: Game API endpoints return Play JSON

Performance Optimizations

Caching Strategy

Scaffeine (Scala wrapper for Caffeine) provides high-performance in-memory caching:

val userCache = scaffeine()
  .maximumSize(100_000)
  .expireAfterWrite(20.minutes)
  .build[UserId, User]()

Cached data includes:

User profiles and preferences
Game metadata
Leaderboards and rankings
Feature flags and settings

Database Query Optimization

Projection: Only fetch required fields from MongoDB
Indexing: Extensive indexes on frequently queried fields
Batching: Bulk operations for mass updates
Connection pooling: ReactiveMongo manages connection pool

Monitoring

Kamon integration provides:

Request tracing and latency metrics
JVM metrics (memory, GC, threads)
Custom business metrics
InfluxDB and Prometheus export

Chess Logic

Pure chess logic is isolated in the scalachess submodule:

Move generation and validation
Chess variants (Chess960, Crazyhouse, etc.)
PGN parsing and generation
Position evaluation basics

This separation keeps game rules independent of server infrastructure.

Configuration

Configuration uses HOCON format in conf/base.conf:

http.port = 9663
mongodb {
  uri = "mongodb://127.0.0.1:27017?appName=lila"
}
net {
  domain = "localhost:9663"
  socket.domains = ["localhost:9664"]
}
akka {
  actor {
    default-dispatcher.fork-join-executor {
      parallelism-max = 64
    }
  }
}

Get Started

Core Features

Development

Architecture

Contributing

Backend Architecture

Overview

Technology Stack

Core Technologies

Key Dependencies

Modular Architecture

Module System

Key Modules

Application Initialization

Asynchronous Processing

Scala Futures

Akka Streams

Actor System

Routing

Controllers

Performance Optimizations

Chess Logic

Configuration

See Also

​Overview

​Technology Stack

​Core Technologies

​Key Dependencies

​Modular Architecture

​Module System

​Key Modules

​Application Initialization

​Asynchronous Processing

​Scala Futures

​Akka Streams

​Actor System

​Routing

​Controllers

​Performance Optimizations

​Chess Logic

​Configuration

​See Also

Overview

Technology Stack

Core Technologies

Key Dependencies

Modular Architecture

Module System

Key Modules

Application Initialization

Asynchronous Processing

Scala Futures

Akka Streams

Actor System

Routing

Controllers

Performance Optimizations

Chess Logic

Configuration

See Also