Getting Started
Riftseer is a Riftbound TCG card data platform. It exposes a REST API, a Next.js web site, and a set of bots and extensions that all share the same card data model.
What's in the monorepo
| Package | Path | Description |
|---|---|---|
| Types | packages/types/ | Shared card types, parser, icons, slug and image helpers |
| Core | packages/core/ | CardDataProvider interface, Supabase provider, search |
| API | apps/api/ | ElysiaJS REST API on Cloudflare Workers |
| Web | apps/web/ | Next.js App Router site on Cloudflare Workers |
| Ingest Worker | apps/ingest-worker/ | Cloudflare Worker — scheduled ingest from RiftCodex into Supabase |
| Discord Bot | apps/discord-bot/ | Slash commands on Cloudflare Workers |
| Reddit Bot | apps/reddit-bot/ | [[Card Name]] mention triggers via Devvit (standalone npm project) |
Prerequisites
- Bun ≥ 1.2 — required. The API layer (Elysia) is Bun-first and will not work on Node.
- A Supabase project with the schema applied (see Supabase docs).
- Optionally: a Cloudflare account for the Discord bot, ingest worker, and web deploy.
Running locally
1. Install dependencies
bun install
This installs all workspace dependencies in one pass. The Reddit bot (apps/reddit-bot/) is excluded from the workspace — cd into it and run npm install separately if needed.
2. Configure environment
Copy .env.example to .env and fill in the required values:
cp .env.example .env
The minimum required variables to run the API against Supabase:
| Variable | Purpose |
|---|---|
CARD_PROVIDER | Set to supabase |
SUPABASE_URL | Your Supabase project URL |
SUPABASE_SERVICE_ROLE_KEY | Your Supabase service-role JWT |
See the full variable reference in the API docs.
3. Start the dev server
bun dev # API (:8789) + web (:3000) together
bun run dev:api # API only — Swagger UI at http://localhost:8789/api/swagger
bun run dev:web # Web only
Running tests
bun test
Tests use bun test (Jest-compatible). API route tests use app.handle(new Request(...)) — no live server needed.
Architecture overview
- Catalogue data flows in one direction: RiftCodex → Ingest Worker → Supabase → API → clients.
- The API never writes card catalogue data to Supabase — catalogue writes are done by the ingest worker (account/deck/admin routes are separate).
- Bots call the public API, not the provider directly.
Next steps
| Topic | Link |
|---|---|
| REST API reference | API |
| Next.js site | Web |
| Card data types and provider interface | Core |
| Discord and Reddit bots | Clients & Bots |
| Ingest pipeline | Ingest Worker |
| Database schema | Supabase |
| This docs site | Docs Site |