Work / SHERLOCK

SHERLOCK

A visual chess investigation and analysis environment. Repository: https://github.com/lughlammas/sherlock · commit e632035 · Android release v0.1.3

Status: v0.1.3 · Android APK release
Stack: React, TypeScript, Vite, Express, WebSocket, chess.js
Tests run: npm test → 8/8 · typecheck exit 0 · 2026-10-19
Source: github.com/lughlammas/sherlock @ e632035

01Problem

A chess engine is a command-line program that speaks a text protocol (UCI). Putting it behind a visual interface raises integration problems: starting and stopping the process, parsing its output, cancelling a search, and making sure that a late answer from an old search never overwrites the current position.

02Context

Its own project, also used as an engineering showcase. It integrates the engine Lughnasadh, version 0.2. A newer engine version (0.4.0) is maintained separately and has not been integrated or validated in SHERLOCK.

03Solution

Responsive board; load, copy and reset positions (FEN).
Analysis by depth or by time, with live depth, nodes, speed, evaluation and principal line, and a stop button.
Clear states: ready, investigating, best move, engine error (with retry and restart).
A mode in which two engine processes play each other.
An Android version.

SHERLOCK hub screen at 1440px: chessboard in the starting position and a case-file menu with Play, Analyze and Train options. — Real capture · commit e632035 · local production build · hub screen only (no engine binary on the capture machine, so no analysis is shown) · 2026-10-19 09:24 BRT

SHERLOCK hub screen at 390px mobile width: chessboard above the case-file menu. — Real capture · commit e632035 · local production build · hub screen only (no engine binary on the capture machine, so no analysis is shown) · 2026-10-19 09:24 BRT

04Architecture

Browser (React) → WebSocket → SHERLOCK controller → Lughnasadh adapter → engine as a child process. The interface never speaks raw UCI; the adapter owns the protocol, timeouts and session tokens, so stale replies are discarded (covered by the session tests). By design, the board position is kept across an engine timeout, crash or restart; that path is exercised only by the smoke scripts, which were not run here. On Android, the same interface runs in a WebView and reaches the native engine through a JavaScript bridge and ProcessBuilder, with no Node or WebSocket dependency in the APK.

05Evidence

8/8 tests passed in the run for this site on 2026-10-19: 6 UCI-parser tests and 2 session tests, including "drops stale info when session rotates". Typecheck clean.
Release v0.1.3 with its APK is public on GitHub, and the repository publishes the APK's SHA-256.

06Human role and AI tools

Built through human-directed AI-assisted development.

07Tests executed

Check	Result	Where
`npm test` (mock engine output, no binary)	8/8 passed	run on 2026-10-19
typecheck (client + server)	exit 0	run on 2026-10-19
Engine smoke (`npm run smoke`, `smoke:match`)	not run (needs the native binary)
CI	none: the repository has no workflow

08Limitations

No continuous integration.
Tests use mocked engine lines; real-engine behaviour is covered only by smoke scripts that were not run here.
Integrated engine is version 0.2; 0.4.0 not integrated.
No playing-strength or performance benchmark.
Engine-versus-engine mode runs two processes and uses substantial battery and memory.

09Commercial relevance

SHERLOCK shows integration work: a native process, a text protocol, a real-time interface and mobile packaging, with the failure cases (timeouts, crashes, late replies) handled explicitly. That is the kind of plumbing behind S02 · Custom Software and the diagnosis in S03 · AI Code Rescue.

→ Services · Discuss Your Project

Have a problem that should become software?

Describe what you have and what is not working.

Discuss Your Project See the work