Arkyvree
A programmable ruleset engine for tabletop RPGs.
Original idea and core architecture implemented by myself, the rest was done by AI agents.
Hosted app · Help · Changelog · Contributing · Issues · Security · Support on Ko-fi
Prerequisites
- Bun v1.3+
- Docker with Compose for PostgreSQL and local email
Getting Started
- Clone the repository and install dependencies
git clone https://github.com/PhilippeChab/arkyvree.git
cd arkyvree
git switch develop
bun install
- Create local environment files from the supplied examples
cp .env.example .env
cp .env.test.example .env.test
- Start the database and seed it
bun dev:db
bun dev:mail
bun dev:db:reset
The reset command deletes and recreates the configured development database.
Verify that .env points to the local arkyvree_dev database before running it.
- Run the development server
bun dev
The app will be available at http://localhost:5173, the API at
http://localhost:8000, and the Mailpit inbox at http://localhost:8025.
bun dev runs the frontend, API, and background worker. Seeded local accounts
include [email protected] with password LocalTest123!; use them only in
the disposable local setup.
Email/password development works without production service credentials. Google
sign-in and uploads require their own optional configuration; leave them
unconfigured unless you need to work on those features. The example environment
leaves monitoring credentials empty.
Testing
# Start test database and seed it
bun test:db
bun test:db:reset
# Run unit/integration tests
bun run test
# Run E2E tests
bunx playwright install chromium
bun test:e2e
# Run everything
bun test:all
Tests use the separate local arkyvree_test database on port 5433.
test:db:reset deletes and recreates that database; bun run test runs on copies
of it, the other test commands on it directly, and Playwright on a copy of its own.
Never point .env.test at production. Playwright serves the built client and the
API on port 8010.
See CONTRIBUTING.md for focused checks.
Project Structure
client/
src/
components/ # Shared UI by domain (auth, characters, common, contributors, customization, icons, invites, layout, notifications, onboarding, rulesets)
contexts/ # React contexts (theme, snackbar, websocket)
hooks/ # Shared hooks (useIsMobile, useListParams, useListboxQuery, useFormSync, …)
lib/ # The query client, shared queries and keys, formatters, validation rules
pages/ # Pages by domain, each with its own components, hooks and queries
services/ # RPC client and its ApiError
stores/ # What the browser keeps: Zustand stores (auth, user preferences, dirty forms), storage guards
theme/ # The theme: palette, components' looks, animations, global styles
server/
main.ts # The web server; worker.ts, the background worker
environment.ts # Every environment variable the server reads
routers/
application.ts # The app: middleware, the error envelope, the routes
api/ # API routes organized by domain
validation.ts # Shared Zod schemas (params, pagination, sanitized text)
authentication/ # Auth routes: signedOut/, then signedIn/ behind the session
static.ts # Static file serving + SEO (the shell: PageTemplates.ts)
ws.ts # The websocket; health.ts, the health probe
services/ # One folder per service, laid out like routers/api
activities/ # Activity log and the notifications it sends
attachments/ # Uploaded images (avatars, portraits)
authentication/ # Sign in / up, demo, account, linked accounts
campaigns/ # Campaign, player, invite, campaign character services
characters/ # Character, inventory, levels, modifiers, contributors, sharing services
levels/ # Level-up wizard (slot queries, pick queries, finalize): reads, asks the engine, writes
dashboard/ # Dashboard statistics
exports/ # PDF exports
notifications/ # Notifications
policies/ # Authorization policies
rulesets/ # Ruleset and ruleset entity services (feats, spells, classes, etc.)
customization/ # Modifiers, requirements, target paths
repositories/ # Database access layer (Drizzle ORM), in folders by domain; concerns/, the mixins they include
cache/ # In-memory cache (a ruleset's rows, its COW data, its target paths)
cow/ # Copy-on-write's writes: the copy of an inherited entity, the rows a change writes
database/ # Database connection, transactions, request-scoped query cache, job queue
middlewares/ # Session, validation, rate limiting, request logging, demo gate
errors/ # Error classes
jobs/ # Background jobs run by the worker (PDF export, emails, cleanup)
emails/ # Email sending (templates in emails/)
storage/ # S3 attachment storage
websockets/ # Server events pushed to the client
engine/ # The ruleset engine: computes a ruleset's rules over the rows it's given, reads and writes nothing
index.ts # Its one entry, Engine: the handles the server, the seeders and the codegen ask
api/ # Engine and its handles, each bound to a view and what it's about, asking the ruleset's module
core/ # Machinery: modifiers, requirements, the path language, the ruleset view, COW data, the module's contract
rulesets/dnd3.5/ # D&D 3.5e: the character, its components by domain, its entities, level-ups and printed sheet
lib/ # What the engine and the server share: the mixins (include)
content/
core/ # What every ruleset's content is written with: the customization builders, the seed types they share, a package's and a test character's shape
dnd3.5/ # The 3.5 content, data: its builders, its hand-written rows, the generated books, its packages, its test characters
codegen/
dnd3.5/ # The SRD scraper and generator: reference files, and the tools that write content/dnd3.5/generated
database/
packages/ # The content packages' runner and registry: each base rules' packages, seeder and test characters, which a database gets
seeders/ # What writes content to the database: core/ (ContentSeeder, a seeder's contract, and the steps every ruleset's content seeds alike), dnd3.5/ (its seeder)
drizzle/
schema.ts # Database schema (and relations.ts), pulled from the database
database.ts # What a query runs on: the schema with its relations, Db, Transaction
NNNN_*.sql, meta/ # Migrations, generated by drizzle-kit
shared/ # Types and pure helpers shared by the client, the server and the database packages
vocabulary/
dnd3.5/ # The 3.5 vocabulary, data only: its lists, labels, tables and bounds, which the engine, the content, the codegen and the seeders read
emails/ # Email templates (React Email)
scripts/ # Database scripts (reset, migrate, seed; db/seeds/, the dev and test data: users, each base rules' test characters) and ops scripts (prod diff, impersonate, validation)
docs/ # Developer docs
help/ # The user-facing help, linked from the app
tests/
routers/ # API route tests, through the typed client
services/ # Service-level tests
engine/ # The engine: its machinery, its operations, the 3.5 module's characters, level-ups and sheets
cache/ # Cache tests
cow/ # Copy-on-write's server part: the views it composes
seeds/ # The seeders, the seeded content, the package runner, the test data
codegen/ # The codegen, mirrored: its core's tools, each ruleset's parser tools
jobs/ # Background jobs
emails/ # The email service and its templates
middlewares/ # Rate limits, error wrapping
shared/ # Shared code, and its enums against the schema
vocabulary/ # A ruleset's vocabulary
scripts/ # The database scripts' guards, the prod diff
lint/ # The repo's own lint rules, and the docs that name them
client/ # Client logic that needs no browser
e2e/ # Playwright E2E tests
fixtures/ # Playwright's setup and auth fixture, the PDF bundle check's document
support/ # Shared test helpers, one module per topic, a ruleset's own in a folder of its name (dnd3.5/)
Architecture
3-layer backend: Routers -> Services -> Repositories
- Routers handle HTTP, validation, and response formatting
- Services contain business logic and transaction management
- Repositories execute SQL queries via Drizzle ORM
Ruleset system: Rulesets support COW forking (edit inherited content without modifying the parent), extensions, publishing, and multi-contributor collaboration. See docs/rulesets.md.
Ruleset engine: engine/ computes every ruleset rule over the data the server reads, through one entry, Engine (engine/index.ts): a handle bound to a ruleset's view and to what its rules are about (Engine.for(scope).character(input).describe(…)), whose operations take a character's rows or a request's body, and answer descriptions, plans of the writes the server makes, or refusals. A ruleset's module (engine/rulesets/dnd3.5/) builds a complete character state from its rows, reading its fields and evaluating modifiers and requirements, and projects level-ups before they're saved.
Community
Read CONTRIBUTING.md before opening a pull request, and target
develop. Community participation follows our Code of Conduct.
Use GitHub issues for questions
and bug reports. Report security issues privately as described in SECURITY.md.
License
The code is under the Elastic License 2.0: you may use, copy, modify and distribute it, but not provide
it to others as a hosted or managed service. The game content from the System Reference Document is Open Game
Content under the Open Game License 1.0a.
