Ask for a demo! We can host the software and support your convention or you can run the entire project yourself! Everything starts with the Rules Lawyer Backend project on Github. An Infrastructure as Code project is included to easily spin up your own instance on AWS.
Requirements
- Docker / Docker Compose
- Auth0 tenant (for auth)
- Node.js 24 (pinned via
.nvmrc; only needed to run tests and tooling locally — the app itself runs in Docker)
Installation
Clone the backend and both frontend repositories into the same parent directory. The pnw-picker (Play & Win prize-picker tool) is a standalone utility, not part of the Docker stack, but lives alongside the others:
git clone https://github.com/rules-lawyer/ruleslawyer-backend.git
git clone https://github.com/rules-lawyer/ruleslawyer-frontend.git
git clone https://github.com/rules-lawyer/ruleslawyer-infrastructure.git
git clone https://github.com/rules-lawyer/legacy-frontends.git
git clone https://github.com/rules-lawyer/pnw-picker.git
Resulting layout:
ruleslawyer/
├── ruleslawyer-backend/
├── ruleslawyer-frontend/
├── ruleslawyer-infrastructure
├── pnw-picker/
└── legacy-frontends/
├── board-game-admin/
├── librarian/
└── play-prize-entry/Create an .env file from the .env.template in each project (backend, plus each frontend). Note: ruleslawyer-frontend uses .env.docker.
Running the app
docker compose --profile all up
On startup the backend container automatically runs Prisma migrations and seeds the database, so no manual migration step is required.
| Service | URL |
|---|---|
| Backend | http://localhost:8080 |
| Backend debugger | localhost:9229 |
| Admin | http://localhost:8081/legacy/admin |
| Librarian | http://localhost:8082/legacy/librarian |
| Play and Win | http://localhost:8083/legacy/playandwin |
| Ruleslawyer dashboard | http://localhost:8084 |
| Database (Postgres) | localhost:5432 |
Post Deployment Setup
Post-deployment setup can be accomplished either through Bruno/Swagger or the Prisma seed file.
Using Bruno or Swagger:
- Authenticate with Auth0.
- Run the Get Status route. The system will detect the first user login and assign them Super Admin permissions.
- Run the Create Organization route.
Using the Prisma seed:
Refer to prisma/example-seed.ts.
Documentation
Two top-level docs live at the repo root:
- AUTHORIZATION.md — the authentication flow (Auth0 + JWT) and the permission model (super admin, organization roles, convention roles) enforced by the route guards.
- DEPLOYMENT.md — the full deployment process, prerequisites, and per-service reference for all repos.
The rest of the documentation lives in Documentation/:
| Document | Covers |
|---|---|
| DATABASE.md | Database structure — domain overview, ER diagram, and per-model field/relationship tables. The schema of record is prisma/schema.prisma. |
| AUTH0_TENANT_SETUP.md | How to configure the Auth0 tenant (API/resource server, custom-claims Action, application clients) the apps authenticate against. |
| BOARDGAMEGEEK.md | The read-only BoardGameGeek (BGG) integration that pulls game metadata and cover art into local Game rows. |
| TABLETOPEVENTS.md | The read-only Tabletop.Events (TTE) integration that pulls attendee/badge data for badge-barcode lookups. |
| ATTENDEE_BADGE_SETUP.md | How attendee badge barcodes tie attendees to checkouts, prize entries, and game sessions. |
| PHYSICAL_LIBRARY_SETUP.md | The barcode-based physical library model — Games (titles) vs. Copies (physical items). |
| ON_SITE_SETUP.md | Operational runbook for standing up the system at a convention: stations, pre-doors prep, and the Play & Win drawing. |
| LEGACY_CONTROLLER.md | The legacy admin/library controller — its root-mounted routes and older response envelope. |
Architecture references also live in Documentation/: the entity-relationship diagram in Documentation/ERD/ and the system diagram (System Diagram.drawio.png).
