Quartz 4

guild-quest-hub-network

3 min read

Guild Quest Hub — Partner Network

Dungeon Books as the central “quest hub” in a network of local partner businesses. Members carry one guild card, tap it at any partner shop, and earn XP everywhere.

Current State

The kiosk architecture already supports multi-shop check-ins:

  • Each partner shop gets its own record under the same Organization in Payload
  • Each shop gets its own kioskApiKey
  • Each shop gets its own Pi (or device) with KIOSK_SHOP_ID + KIOSK_API_KEY env vars
  • Check-ins are scoped to the correct shop
  • XP and points accumulate across all locations (same member, same org)

No code changes are needed for the basic model.

Phone-as-Reader (Scalable Alternative to Pi + WalletMate)

Instead of giving every partner a Raspberry Pi + NFC reader, partners could use a phone:

Android (Web NFC API)

  • Works in Chrome — staff opens /kiosk on their phone
  • Member taps their NTAG215 card on the back of the phone
  • Web NFC reads the UID, same pipeline as the HID reader
  • No app install needed — just a URL
  • Requires HTTPS (Tailscale funnel or public deploy)

iOS (Limited)

  • Safari does not support Web NFC
  • Would need a native app or iOS Shortcut via Core NFC
  • Apple doesn’t expose raw tag UIDs to the web
  • Not a viable web-only path for iOS

Phone-to-Phone (Host Card Emulation)

  • Member’s phone emulates an NFC tag, reader phone picks it up
  • Android supports HCE natively
  • iOS: recently opened but very limited
  • Requires a companion app on the member’s phone — higher friction
  • Not recommended for v1

Recommendation

Phone-as-reader with Web NFC on Android is the lowest-friction option for partner shops. The kiosk client component would need a second input mode — alongside HID keyboard capture, call navigator.nfc.read() when available. The card UID comes back the same way, so the server action and loyalty pipeline are identical.

Implementation for Partner Check-ins

What works today (no changes needed)

  1. Create partner shop in Payload admin under the same Organization
  2. Generate a kioskApiKey for the partner shop
  3. Give partner a Pi with the guild app, or an Android phone pointed at /kiosk
  4. Member taps their guild card → check-in logged to partner shop → XP awarded

Future enhancements

  • Quest system — “Check in at 5 partner shops this month for bonus XP”
  • Partner onboarding flow — self-serve setup instead of manual Payload admin
  • Multi-shop kiosk selector — one device, multiple shops (URL param or shop picker)
  • Partner dashboard — foot traffic analytics, how many guild members visited
  • Web NFC input mode — for phone-as-reader at partner locations

Graph View

Backlinks