Quartz 4

guild-quest-hub-network

4 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

Jersey City Partner Quests

The local business partnership model has a clear geographic target: Jersey City indie businesses — coffee shops, game stores, breweries, other indie retailers. The quest framing is “go on quests to hit businesses” — members earn XP for visiting partner locations as part of a quest chain rather than just passive check-ins.

Quest examples:

  • “The Brewer’s Route” — check in at 3 local breweries in one week
  • “Scholar’s Circuit” — visit the library, a partner café, and Dungeon Books in one day
  • “The Merchant’s Road” — check in at 5 Jersey City small businesses this month

The shop becomes the quest hub and home base; the surrounding neighborhood is the dungeon. Partners don’t need to understand the game — they just need an NFC reader. Their benefit is foot traffic; the guild handles the narrative.

This is also the Pokémon Go sponsored-location model, but inverted: instead of Niantic selling locations to enterprise partners, we’re building a small-business-native version where indie shops can participate without enterprise contracts or sponsorship fees.

Graph View

Backlinks