# jcarolus/android-chess architecture

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

- Interactive diagram: https://gitdiagram.com/jcarolus/android-chess
- Repository: https://github.com/jcarolus/android-chess

## Overview

Chess for Android is a multi-mode chess application. The central workflow is selecting or starting a game, viewing and playing positions through the board UI, and using the native chess engine for legal moves and analysis. Major branches add online play, puzzles, local game and practice content, board setup, opening lookup, board sharing, and third-party engines. The tree and README establish these capabilities; sampled source confirms engine, import, ECO, Lichess service, and socket-sharing behavior, but does not expose all activity-to-subsystem wiring.

Main entry points: [`app/src/main/java/jwtc/chess/JNI.java`](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/chess/JNI.java) (Chess JNI), [`app/src/main/java/jwtc/android/chess/play/PlayActivity.java`](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/play/PlayActivity.java) (Game screen), [`app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardService.java`](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardService.java) (Sharing service), [`app/src/main/java/jwtc/android/chess/engine/OexEngine.java`](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/engine/OexEngine.java) (OEX engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Chess play"]
  node_game_list["Game selection"]
  node_play_ui["Game screen<br/>[PlayActivity.java]"]
  node_board_view["Board display"]
  node_game_api["Game state API<br/>[GameApi.java]"]
end

subgraph group_content["Games and learning"]
  node_local_store[("Game database<br/>[MyPGNProvider.java]")]
  node_import_service["Content import<br/>[ImportService.java]"]
  node_practice["Practice mode"]
  node_puzzles["Puzzle mode"]
  node_setup["Board setup<br/>[SetupActivity.java]"]
  node_eco["Opening explorer<br/>[EcoService.java]"]
end

subgraph group_online["Online and sharing"]
  node_lichess["Lichess play"]
  node_lichess_service["Lichess session"]
  node_lichess_api["Lichess API<br/>[LichessApi.java]"]
  node_fics["FICS client<br/>[ICSClient.java]"]
  node_fics_server["FICS server<br/>[ICSServer.java]"]
  node_board_share["Board sharing"]
  node_share_service["Sharing service"]
  node_socket_service["Socket transport"]
end

subgraph group_engine["Engine and rules"]
  node_native_chess["Native chess core<br/>[ChessBoard.cpp]"]
  node_jni["Chess JNI<br/>[JNI.java]"]
  node_local_engine["Built-in engine<br/>[LocalEngine.java]"]
  node_oex_engine["OEX engine<br/>[OexEngine.java]"]
  node_oex_resolver["OEX discovery"]
end

subgraph group_app["App experience"]
  node_preferences["Accessibility settings"]
end

node_player(("Player"))
node_lichess_external(("Lichess"))
node_fics_external(("FICS"))
node_oex_external(("Third-party engine"))
node_chromecast(("Chromecast device"))

node_player -->|"selects game"| node_game_list
node_game_list -->|"starts play"| node_play_ui
node_play_ui -->|"renders board"| node_board_view
node_play_ui -->|"uses game state"| node_game_api
node_game_api -->|"accesses rules"| node_jni
node_jni -->|"calls native core"| node_native_chess
node_local_engine -->|"searches position"| node_jni
node_play_ui -->|"requests analysis"| node_local_engine
node_player -->|"imports content"| node_import_service
node_import_service -->|"imports game data"| node_local_store
node_player -->|"opens practice"| node_practice
node_player -->|"solves puzzles"| node_puzzles
node_player -->|"sets position"| node_setup
node_player -->|"explores openings"| node_eco
node_player -->|"plays online"| node_lichess
node_lichess -->|"shares session"| node_lichess_service
node_lichess_service -->|"owns API"| node_lichess_api
node_lichess_api -->|"connects to"| node_lichess_external
node_player -->|"plays online"| node_fics
node_fics -->|"communicates with"| node_fics_server
node_player -->|"shares board"| node_board_share
node_board_share -->|"controls service"| node_share_service
node_share_service -->|"uses sockets"| node_socket_service
node_share_service -->|"reads position"| node_jni
node_socket_service -.->|"sends board data"| node_chromecast
node_player -->|"chooses engine"| node_oex_engine
node_oex_engine -->|"resolves executable"| node_oex_resolver
node_oex_resolver -->|"discovers engine"| node_oex_external
node_oex_engine -->|"maps engine moves"| node_jni
node_player -->|"configures access"| node_preferences

click node_game_list "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/GamesListActivity.java"
click node_play_ui "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/play/PlayActivity.java"
click node_board_view "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/views/ChessBoardView.java"
click node_game_api "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/services/GameApi.java"
click node_local_store "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/helpers/MyPGNProvider.java"
click node_import_service "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/tools/ImportService.java"
click node_practice "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/practice/PracticeActivity.java"
click node_puzzles "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/puzzle/PuzzleActivity.java"
click node_setup "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/setup/SetupActivity.java"
click node_eco "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/services/EcoService.java"
click node_lichess "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/lichess/LichessGameActivity.java"
click node_lichess_service "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/lichess/LichessService.java"
click node_lichess_api "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/lichess/LichessApi.java"
click node_fics "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/ics/ICSClient.java"
click node_fics_server "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/ics/ICSServer.java"
click node_board_share "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardActivity.java"
click node_share_service "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardService.java"
click node_socket_service "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/services/SocketConnectService.java"
click node_native_chess "https://github.com/jcarolus/android-chess/blob/master/native/project/jni/ChessBoard.cpp"
click node_jni "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/chess/JNI.java"
click node_local_engine "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/engine/LocalEngine.java"
click node_oex_engine "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/engine/OexEngine.java"
click node_oex_resolver "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/engine/oex/OexEngineResolver.java"
click node_preferences "https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/activities/AccessibilityPreferences.java"

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_game_list,node_play_ui,node_board_view,node_game_api toneBlue
class node_local_store,node_import_service,node_practice,node_puzzles,node_setup,node_eco toneAmber
class node_lichess,node_lichess_service,node_lichess_api,node_fics,node_fics_server,node_board_share,node_share_service,node_socket_service toneMint
class node_native_chess,node_jni,node_local_engine,node_oex_engine,node_oex_resolver toneRose
class node_preferences,node_player,node_lichess_external,node_fics_external,node_oex_external,node_chromecast toneIndigo
```

## Components

### Chess play

- [Game selection](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/GamesListActivity.java): `app/src/main/java/jwtc/android/chess/GamesListActivity.java`
- [Game screen](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/play/PlayActivity.java): `app/src/main/java/jwtc/android/chess/play/PlayActivity.java`
- [Board display](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/views/ChessBoardView.java): `app/src/main/java/jwtc/android/chess/views/ChessBoardView.java`
- [Game state API](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/services/GameApi.java): `app/src/main/java/jwtc/android/chess/services/GameApi.java`

### Games and learning

- [Game database](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/helpers/MyPGNProvider.java): `app/src/main/java/jwtc/android/chess/helpers/MyPGNProvider.java`
- [Content import](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/tools/ImportService.java): `app/src/main/java/jwtc/android/chess/tools/ImportService.java`
- [Practice mode](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/practice/PracticeActivity.java): `app/src/main/java/jwtc/android/chess/practice/PracticeActivity.java`
- [Puzzle mode](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/puzzle/PuzzleActivity.java): `app/src/main/java/jwtc/android/chess/puzzle/PuzzleActivity.java`
- [Board setup](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/setup/SetupActivity.java): `app/src/main/java/jwtc/android/chess/setup/SetupActivity.java`
- [Opening explorer](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/services/EcoService.java): `app/src/main/java/jwtc/android/chess/services/EcoService.java`

### Online and sharing

- [Lichess play](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/lichess/LichessGameActivity.java): `app/src/main/java/jwtc/android/chess/lichess/LichessGameActivity.java`
- [Lichess session](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/lichess/LichessService.java): `app/src/main/java/jwtc/android/chess/lichess/LichessService.java`
- [Lichess API](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/lichess/LichessApi.java): `app/src/main/java/jwtc/android/chess/lichess/LichessApi.java`
- [FICS client](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/ics/ICSClient.java): `app/src/main/java/jwtc/android/chess/ics/ICSClient.java`
- [FICS server](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/ics/ICSServer.java): `app/src/main/java/jwtc/android/chess/ics/ICSServer.java`
- [Board sharing](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardActivity.java): `app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardActivity.java`
- [Sharing service](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardService.java): `app/src/main/java/jwtc/android/chess/hotspotboard/HotspotBoardService.java`
- [Socket transport](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/services/SocketConnectService.java): `app/src/main/java/jwtc/android/chess/services/SocketConnectService.java`

### Engine and rules

- [Native chess core](https://github.com/jcarolus/android-chess/blob/master/native/project/jni/ChessBoard.cpp): `native/project/jni/ChessBoard.cpp`
- [Chess JNI](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/chess/JNI.java): `app/src/main/java/jwtc/chess/JNI.java`
- [Built-in engine](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/engine/LocalEngine.java): `app/src/main/java/jwtc/android/chess/engine/LocalEngine.java`
- [OEX engine](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/engine/OexEngine.java): `app/src/main/java/jwtc/android/chess/engine/OexEngine.java`
- [OEX discovery](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/engine/oex/OexEngineResolver.java): `app/src/main/java/jwtc/android/chess/engine/oex/OexEngineResolver.java`

### App experience

- [Accessibility settings](https://github.com/jcarolus/android-chess/blob/master/app/src/main/java/jwtc/android/chess/activities/AccessibilityPreferences.java): `app/src/main/java/jwtc/android/chess/activities/AccessibilityPreferences.java`

### Other components

- **Player**
- **Lichess**
- **FICS**
- **Third-party engine**
- **Chromecast device**

## Connections

- Player → Game selection: selects game
- Game selection → Game screen: starts play
- Game screen → Board display: renders board
- Game screen → Game state API: uses game state
- Game state API → Chess JNI: accesses rules
- Chess JNI → Native chess core: calls native core
- Built-in engine → Chess JNI: searches position
- Game screen → Built-in engine: requests analysis
- Player → Content import: imports content
- Content import → Game database: imports game data
- Player → Practice mode: opens practice
- Player → Puzzle mode: solves puzzles
- Player → Board setup: sets position
- Player → Opening explorer: explores openings
- Player → Lichess play: plays online
- Lichess play → Lichess session: shares session
- Lichess session → Lichess API: owns API
- Lichess API → Lichess: connects to
- Player → FICS client: plays online
- FICS client → FICS server: communicates with
- Player → Board sharing: shares board
- Board sharing → Sharing service: controls service
- Sharing service → Socket transport: uses sockets
- Sharing service → Chess JNI: reads position
- Socket transport → Chromecast device: sends board data
- Player → OEX engine: chooses engine
- OEX engine → OEX discovery: resolves executable
- OEX discovery → Third-party engine: discovers engine
- OEX engine → Chess JNI: maps engine moves
- Player → Accessibility settings: configures access