How keiran101/mahjong-ledger works
This is a local, browser-based Guangdong Mahjong ledger. Players create or join a room, enter a round by text or photo, review a score preview, then confirm or edit it; the room board, settlement transfers, and history are derived from the recorded events. Scoring is deterministic and separate from text and vision recognition. The README and sampled server excerpts support the main API flow; unsampled frontend and storage details are represented only where documented, so some internal links are omitted.
Main entry points: server.mjs API and static server · vision.mjs Photo draft · store.mjs Event ledger and replay · pattern.ts Hand pattern inference
Components 16
Player interface
- Room interface
public/app.js - Board and history
public/app.js
HTTP service
- API and static server
server.mjs - Room and event API
server.mjs
Round recognition
- Text parser
lib/parse.mjs - Text LLM client
lib/llm.mjs - Photo draft
lib/vision.mjs - Vision model client
lib/vlm.mjs - Hand pattern inference
lib/pattern.ts - Tile utilities
lib/tiles.ts
Rules and scoring
- Mahjong rules
lib/rules.ts - Round scoring
lib/score.ts
Ledger and results
- Event ledger and replay
lib/store.mjs - Minimum transfers
lib/settle.ts
Other components
- Player
- AI model services
Connections 21
- Player → Room interface: enters rounds
README.md - Room interface → API and static server: calls APIs
README.md - API and static server → Room interface: serves interface
README.md - API and static server → Text parser: parses text
server.mjs - Text parser → Text LLM client: extracts fields
lib/parse.mjs - Text LLM client → AI model services: sends prompts
lib/llm.mjs - API and static server → Photo draft: recognizes photo
server.mjs - Photo draft → Vision model client: requests vision
lib/vision.mjs - Vision model client → AI model services: sends image
lib/vlm.mjs - Photo draft → Hand pattern inference: suggests pattern
lib/vision.mjs - Photo draft → Tile utilities: normalizes tiles
lib/vision.mjs - Hand pattern inference → Tile utilities: uses tile encoding
lib/pattern.ts - Hand pattern inference → Mahjong rules: uses rule tiers
lib/pattern.ts - API and static server → Round scoring: previews score
server.mjs - Round scoring → Mahjong rules: applies rules
lib/score.ts - API and static server → Event ledger and replay: appends events
server.mjs - Event ledger and replay → Minimum transfers: computes settlement
lib/store.mjs - Event ledger and replay → Mahjong rules: uses room rules
lib/store.mjs - Event ledger and replay → Board and history: provides replayed state
README.md - Minimum transfers → Board and history: supplies transfers
README.md - Player → Board and history: views room results
README.md