bldg-admin-api — JOYSTICK
The API, the admin and driver web apps, Claire, and the Goldline games for JOYSTICK.
Start with ARCHITECTURE.md. It is the canonical guide: what JOYSTICK is,
who owns each business fact, and the one legal path from real evidence to a game consequence.
docs/JOYSTICK_SYSTEM_MAP.md defines the vocabulary.
Before you change anything
- Another repo depends on this one in production. The resident app (
app.bldg.chat) calls
this API over HTTP. Renaming a resident agent tool, changing its input or output shape, or
rotating ADMIN_AGENT_SHARED_SECRET / APP_SHARED_API_SECRET breaks residents without failing
any build or test here. CLAUDE.md §1 lists exactly what it relies on.
scripts/migrate.mjs is the production schema authority. pnpm start runs it before the
server. It does not run drizzle/*.sql; a numbered migration is not live until an idempotent
copy is added there.- Games have one canonical build each. Small Comforts (the three mice in the suitcase) is
preview/small-comforts/, and STORY.md says what happens in each chapter. Read a game's README before
touching it; older branches, artifacts and prototypes of the same game exist and are wrong.
Layout
| Path | What it is |
|---|
client/ | React app: admin, driver, Claire Desk, Lantern City and the games |
server/ | Express + tRPC API, Claire, Daphne, President, Mitch, and the background workers |
shared/ | Types and contracts used by both |
drizzle/ | Drizzle schema (schema.ts) and historical numbered migrations |
e2e/ | Playwright suites, one playwright.*.config.ts per suite at the root |
docs/ | Architecture and design notes; docs/goldline/ docs marked binding constrain new work |
docs/history/ | Superseded handoffs and reports, kept as records |
scripts/ | Build, migration and CI guard scripts |
preview/ | Standalone previews and canonical game builds |
artifacts/ | Captured evidence from past work |
The root config files stay at the root. CI workflows, open PRs and the configs' own relative
paths depend on that, and GOLDLINE_CANON.md is pinned there by its own header and a test.
Run it
pnpm install
cp .env.example .env
pnpm dev # API with the client
pnpm check # tsc
pnpm test # vitest unit tests
Integration tests (vitest.integration.config.ts) need MySQL. The production database is on
Railway's private network, so DB-backed screens generally cannot be exercised locally. Say so
rather than claiming you verified them.
Deploy
- Railway runs the API:
pnpm build, then pnpm start. The build also bundles the
procurement, Mitch and President workers into dist/.
- Vercel serves the gojoystick.com front door from
vercel.json and middleware.js; both
must stay at the root.
- CI is per-area workflows in
.github/workflows/. The naming, tenant-default and
domain-boundary guards run on every PR to main.
