Builders
How the repository is organised, the one rule that keeps it honest, and where to start reading.
GAVEL is one strict TypeScript monorepo with seven workspace packages under packages/. This track is for people who read, run, change or review the code. Every page here was written from the source; each package page names the files and the tests that guard its rules.
The picture
An arrow means "may import". The arrows are the table ALLOWED in .dependency-cruiser.cjs; CI enforces them, so a package cannot quietly reach into one that is not listed.
shared
Money in cents, ids, wire messages, ports, config schema.
engine
The pure auction core and the hash-chained ledger.
payments
PayPal holds, the settlement saga, webhooks, the fake PayPal.
server
The single process that hosts rooms, HTTP, WebSocket and settlement.
voice
Speech-to-text clients, bid parser, the AUTO or CONFIRM decision.
web
The browser client.
e2e
Scenario DSL and end-to-end specs.
infra
Workflows, deploy files and the checks around them.
The dependency rule
Direction is shared, then engine, then payments; voice depends on shared only; server sits on top of the four; web imports shared and voice only.
| Package | May import |
|---|---|
shared | nothing from the workspace |
engine | shared |
payments | shared, engine |
voice | shared |
server | shared, engine, payments, voice |
web | shared, voice |
Two further rules are in the same file or its companion scripts:
- The engine is pure. The rule
engine-no-node-ioforbidsfs,net,http,child_process,osand the other Node I/O modules underpackages/engine/src/, except the foldersnode/andtesting/.packages/engine/scripts/check-imports.mjsrepeats the check and also fails when the engine declares a runtime dependency. - Payments keeps one runtime dependency. The root script
check:depsrunsdepcruise,scripts/check-engine-purity.mjsand the payments check thatzodis the only runtime dependency.
How to read the repo
Read packages/shared/src/index.ts for the vocabulary the other packages share, then shared.
Read the engine's decide/index.ts and evolve.ts: one command in, entries out, state folded from entries. See engine.
Read packages/payments/src/saga/machine.ts (the transition table), then payments.
Read packages/server/src/boot/compose.ts: it is the one place where every package is wired together. See server.
More for builders
- Run and test, repo layout and contributing.
- Architecture, events, configuration, data model and WebSocket protocol.
- .dependency-cruiser.cjsthe dependency direction rules
- scripts/check-engine-purity.mjsthe engine purity check run by check:deps
- packages/server/src/boot/compose.tswhere every package is wired
Last updated on