HedgeHunt

Creators edit hunts while explorers are actively solving them. If a creator modifies step 3 while an explorer is on step 1, the explorer could eventually reach content that changed mid-session. I needed complete isolation between editing and playing.

• Single document model. One Hunt document with all steps embedded. Simple to query. But publishing means either deep-cloning the entire document (expensive, hard to track versions) or adding version flags to every field (complexity explosion). Editing and playing would share the same data.
• Event sourcing. Store every edit as an event, reconstruct state on read. Powerful but overkill at this scale. Makes every read path more expensive for a problem that doesn't need temporal queries.
• Separate version documents. Hunt holds metadata and a pointer to the live version. HuntVersion holds the frozen content snapshot. Steps are linked per version.

Three models. Hunt is the master record with a liveVersion field pointing to whichever HuntVersion is currently live. Publishing clones the draft steps into a new HuntVersion. Releasing swaps the pointer. Rolling back swaps it to a different version.

The release itself is a single findOneAndUpdate:

const result = await Hunt.findOneAndUpdate(
  { huntId, liveVersion: currentLiveVersion },
  { liveVersion: version, releasedAt: new Date(), releasedBy: userId },
  { new: true, session }
);
if (!result) {
  throw new ConflictError('Hunt was modified. Retry.');
}

The filter liveVersion: currentLiveVersion acts as optimistic locking. If someone else released between the read and the write, the filter matches nothing and the server throws a conflict. No distributed locks, no queues. The same pattern protects saves, using the client's updatedAt timestamp to catch concurrent edits at both the hunt and step level.

Automatic version pruning protects against unbounded growth. Old published versions are cleaned up, but the currently live version is always protected from deletion.

More complex schema. Every read that needs step data requires two lookups (version, then steps). Publishing is heavier because it clones step documents. But version isolation is absolute. Creators can edit freely while explorers see consistent, frozen content. Rollback is a pointer swap.

Each challenge type has a completely different data shape. A Quiz has options, correct answers, and validation modes. A Mission has GPS coordinates, radius, and media requirements. A Task has AI prompts and audio settings. I needed storage that handles this polymorphism without fighting the schema.

• PostgreSQL with table-per-type inheritance. A base steps table joined to quiz_steps, mission_steps, etc. Strong typing via Prisma. But adding a new challenge type means a new migration, a new table, and updating every query that touches steps.
• PostgreSQL with JSONB. One steps table with a challenge JSONB column. Flexible storage, but Prisma doesn't validate JSONB contents. You lose type safety at the database layer.
• MongoDB with embedded documents. Steps are documents. The challenge field holds sub-objects for each type. Only one is populated. Adding a new challenge type means adding a field. No migrations.

MongoDB. Challenges are naturally document-shaped with variable structures that map cleanly to embedded objects. Publishing clones step documents with a straightforward insertMany rather than a multi-table transaction.

• Numeric IDs. A Counter collection with findOneAndUpdate and $inc gives sequential, race-condition-safe, human-readable IDs for URLs and display.
• No JOINs. Every "join" is an explicit batch query using $in on arrays of IDs, avoiding N+1 problems. withTransaction covers the critical paths: publish, release, and delete.
• TypeScript tradeoff. MongoDB's TypeScript support isn't as strong as Prisma's. But the OpenAPI spec is the source of truth, so Mongoose schemas just follow along.

No compile-time query validation like Prisma provides. Some denormalization is needed since you can't JOIN. But the polymorphic challenge structure maps naturally to documents, and the OpenAPI-first approach means type safety comes from the spec, not the ORM.

The full Step document contains everything: correct answers, AI validation prompts, scoring criteria, admin notes. Explorers must never see any of this. Filtering on the client is not an option because the data has already left the server. One missed field or a browser devtools inspection would leak answers.

• Client-side filtering. Send the full document, strip fields in the Explorer app. Fast to build. Fundamentally insecure. The data is already on the wire.
• GraphQL field-level auth. Let the client request only safe fields. Still risky if a field permission is misconfigured. A new sensitive field defaults to exposed unless someone remembers to restrict it.
• Server-side transformation. A dedicated function that takes a full Step and returns a StepPF (Player Format). The boundary is structural. The server never sends what it shouldn't.

PlayerExporter runs server-side. It takes a full Step and produces a StepPF containing only what the explorer needs: no answer keys, no AI prompts, no validation criteria. Quiz options are randomized so the order is consistent within a session but unpredictable across sessions.

The same exporter feeds two consumers: the play API and the builder preview. Both receive identical output. The preview always matches exactly what a real explorer would see.

Extra type definitions and a transformation function to maintain for every schema change. But the security boundary is structural, not behavioral. You can't accidentally leak answers because StepPF physically doesn't carry them. If a new sensitive field is added to Step, the compiler forces a decision about whether StepPF should include it.

Four challenge types (Clue, Quiz, Mission, Task) with completely different field schemas. Three things need to work at the same time:

• The builder lets creators switch a step between types without destroying shared data like title and description
• The API validates based on type
• The OpenAPI spec generates clean schemas for all four

• TypeScript discriminated union. ClueStep | QuizStep | MissionStep | TaskStep. Clean type narrowing with exhaustive switch statements. Each variant carries exactly the fields it needs. But OpenAPI codegen handles unions poorly. MongoDB stores one shape per document, so switching types means replacing the document. The builder form state would need to be destroyed and recreated on type change.
• Shared object with nullable fields. One Challenge shape with all four type sub-objects as optional. Only one is populated at a time. Switching types means nulling the old field and setting the new one. Same document, same form state.

Shared object. The schema marks clue, quiz, mission, and task as optional + nullable. A Zod discriminator at the API layer validates that exactly one is populated and matches the type field. The constraint is runtime, not compile-time.

This made three things simpler:

• OpenAPI generation works with one schema instead of union complexity
• MongoDB stores one document shape where partial updates work naturally
• The builder switches types by nulling one field and setting another. No document recreation, no form state loss

No compile-time exhaustiveness checking. If you access challenge.quiz when the type is actually mission, TypeScript won't stop you. I compensate with strict API validation and consistent access through helper functions that check the type before accessing the specific challenge field.

Two distinct AI use cases. Multiple providers handle different media types, and provider failures can never block an explorer mid-hunt.

• Validation. Checking explorer submissions for Missions (photos of specific locations or objects) and Tasks (audio recordings) where exact matching is impossible.
• Generation. Creating complete, playable hunts from a text prompt like "a treasure hunt around Central Park about American history."

• Validation with a single provider. Simpler integration. But a single point of failure. If OpenAI is down, all Mission and Task validation stops and explorers can't progress.
• Validation with multi-provider and hard failure. Multiple providers, reject submissions when AI is unavailable. Safe, but frustrating for explorers in the middle of a hunt.
• Validation with graceful degradation. Multiple providers, each specialized by media type. If all fail, auto-pass with a flag. Explorers never blocked.
• Generation with free-form JSON. Ask the LLM for JSON, parse, hope it validates. The model hallucinates field names, invents enum values, nests things wrong.
• Generation with structured outputs. Enforce the output schema during generation. Enrich with external data after.

Validation. GPT-4o handles text, Google Gemini handles image and audio. If a provider fails or times out at 15 seconds, validation auto-passes with a fallbackUsed flag. Explorers are never blocked by infrastructure. The prompt adapts based on attempt count: after 2 failures, subtle hints. After 3+, direct guidance.

Generation. OpenAI Structured Outputs with a Zod schema derived from the API types. The schema intentionally omits GPS coordinates since the model would hallucinate them. After generation, each step goes through a geocoding pipeline:

• Google Maps converts location descriptions to coordinates
• Only high-precision results are accepted
• If geocoding fails, the step silently converts from a Mission to a Clue

Every generated hunt is immediately playable. If schema validation fails, one retry feeds the specific Zod errors back to the model.

Auto-pass on validation failure means a bad answer could slip through. But blocking explorers when AI is down is worse for the experience. The generation quality gate trades geographic coverage for accuracy. Some locations become Clues instead of GPS challenges, but nothing requires manual fixes.