Case study
雀心 Janshin
A multiplayer version of riichi mahjong, the Japanese tile game, for one to four players, with AI opponents filling any open seat. A Node.js server enforces every rule and calculates every score in real time, while the browser simply displays the state it receives.
- Role
- Solo project covering game design, frontend, backend, testing and deployment
- Tech stack

Overview
Janshin (雀心) brings riichi mahjong, a Japanese tile game for four players known for its intricate scoring, to the browser. Players choose a short or full match and are seated with up to three others. Any empty seat is filled by a bot, so a game can always begin immediately.
Scoring a winning hand involves recognising dozens of patterns and applying numerous special rules. The core of the work was a rules engine that handles those details accurately, and a server architecture that keeps four players synchronised in real time.
Key highlights
- The full competition ruleset, including every scoring pattern and rare special case
- 293 automated tests using the test runner built into Node.js, with a required minimum of 80% line coverage
- Continuous integration on GitHub Actions, running a dependency audit and the full test suite on every push and pull request
- Player profiles, statistics, achievements, friends and match history stored in SQLite
- Every tile drawn as inline SVG, with music, sound effects and selectable voice packs
- A lean setup with only two runtime dependencies (Express and ws) and no frontend build step
How it fits together
Up to four players. Draws the table from the state it receives and sends each action the player takes.
Owns the game. Every move is checked here before it changes the table.
- WebSocket server and matchmaking
- Game room: the single source of truth
- Scoring engine: a pure, separately tested module
- Bots for any empty seat
Profiles, statistics, achievements, friends and match history.
Challenges & decisions
Server authority
All game state lives on the server, and the client never decides whether a move is legal. Each player receives a filtered view of the table, showing their own tiles in full and opponents’ tiles only as counts, so no hidden information can be read from the browser.
Accurate, testable scoring
Hand evaluation and scoring sit in a pure module that knows nothing about turns, networking or players. This separation allows every rule to be unit tested in isolation, while integration tests play complete rounds through the real game room.
Instant matchmaking
Each game mode has a shared waiting room, and bots that follow set rules fill any empty seat. A solo player can start immediately, and up to four people can share a table.
Lightweight data storage
Profiles and match history were moved from JSON files to SQLite using the node:sqlite module built into Node.js, keeping dependencies minimal and deployment on Railway straightforward.
What I learned
- Keeping the scoring rules in a pure module paid off repeatedly. When I later added stronger bots and a replay review, both reused the same logic instead of reimplementing it.
- Moving the tests to node:test with an 80% coverage gate in CI meant a change to one scoring rule could no longer quietly break another.
- Real player data needs care. Moving from JSON files to SQLite took a one-off migration script, and fixing a value already saved in match history took a repair script of its own.