Architecture tour
Shoehive is one npm package, shoehive, with subpath exports
(ADR 0002), plus the
create-shoehive scaffolder. Everything lives in a pnpm monorepo.
The repository
Section titled “The repository”| Path | What |
|---|---|
packages/shoehive/src |
The package, one folder per subpath (below) |
packages/shoehive/test |
Unit, property, conformance and integration tests |
packages/shoehive/api |
API Extractor reports: the public API, reviewed in every PR |
packages/create-shoehive |
npm create shoehive, with its project templates |
examples/ |
Tic-tac-toe, quiz, blackjack and Hold'em, each with a web UI |
e2e/, examples/*/e2e |
Playwright tests that play the examples in real browsers |
docs/ |
ADRs, RFCs and the reference specs (synced into this site) |
website/ |
This site |
The layers
Section titled “The layers” shoehive (core: isomorphic, depends only on mutative) defineGame, engine, views, diff, rng, protocol types, errors ^ ^ ^ shoehive/server | shoehive/client | shoehive/testing | shoehive/cards sessions, lobby,| connection, | createTestTable, | decks, shoes, hands, transport (ws), | resume, patches, | fake clock, | visibility, pots store, wallet, | typed act() | conformance | limits | ^ | | | shoehive/react | |- Core (
src/core, exported asshoehive) is pure: no I/O and no Node built-ins, so it runs in browsers too.define.tsholdsdefineGameand its types.runtime.tsholdsTableRuntime, one per table: a serial queue that validates input, checks the phase, runs the action on a Mutative draft, commits, computes each viewer's view, diffs it against the last one sent (diff.ts) and emits patches.random.tsandclock.tsmake it deterministic. - Protocol (
src/protocol) holds the wire message types and parser for the wire protocol. - Server (
src/server) adds sessions and resume tokens (tokens.ts), the lobby, seats, the WebSocket and in-memory transports (transport.ts) and limits, around manyTableRuntimes in one Node process. - Stores (
src/store) persist each table as a snapshot plus an action log. Restart recovery is the same code path as replay (ADR 0009). - Client and React (
src/client,src/react) speak the protocol, apply patches and expose typed handles and hooks. They are isomorphic. - Testing (
src/testing) runs games without sockets and holds the store and wallet conformance suites. - Devtools (
src/devtools) is an inspector served by the server, loaded only when enabled (ADR 0011). Its UI source is insrc/devtools/uiand is bundled intoui-assets.generated.ts.
Rules that keep it honest
Section titled “Rules that keep it honest”- Isomorphic entry points (
shoehive,/client,/react,/cards) must not import Node built-ins. ESLint enforces it. - Public API changes show up in the API Extractor reports, and need a changeset.
- Engine invariants (rollback, replay equals state, views never leak) are property-tested.
- Integration tests use real sockets, never a mocked
ws.
For the reasoning behind each choice, read the ADRs.
