Designing Versioned, Immutable Quiz Results in Next.js

Loretypes is a free website featuring six self-discovery quizzes: Aura Color, Archetype, Moral Alignment, Past Life, Color Season, and Spirit Animal. These quizzes are meant for reflection and enjoyment rather than diagnosis. The most challenging aspect of creating these quizzes was determining how to format their result URLs, which are currently structured as /[cluster]/r/[shareId].

This URL must function properly even if the result content changes over time. This article will outline the necessary steps to design versioned, immutable quiz results in Next.js.

1. The server determines the result: When a user submits a quiz, only their answers are sent to the server via a POST request to the `/api/tests/[slug]/results/` endpoint. The server then uses a quiz definition to process the answers and compute the result. The scoring process follows a predefined strategy table in `lib/scoring/engine.ts`, which includes four implemented strategies: dimensional sum, bipolar dimensions, alignment axis grid, and seasonal profile. The scoring itself is straightforward arithmetic.

2. Store what was decided, not what was asked: After scoring the quiz, the result is stored in a record containing a 12-character alphanumeric share ID, the test slug and version, a creation timestamp, and an expiry field set to null. The raw answer array is excluded from the record to maintain stability, as the link should render based on the computed payload at the time of creation.

If a generated ID collides with an existing one, the save loop will attempt a fresh ID up to five times before rethrowing any other storage errors.

3. Choose a read policy for versioned records: While simply storing testVersion with every record is an option, choosing how to handle old records after quiz modifications is crucial. For Archetype, a small read-only adapter is used to translate older payloads into the current field names at read time. Other quizzes, such as Spirit Animal, Aura, and Color Season, use explicit version maps, exact match on current version only, or fall back to the current definition, respectively.

When a user accesses a result page, the URL is validated, the record is loaded, the definition for that record's version is resolved, and the corresponding result component is displayed. If an unknown ID or incompatible version is encountered, a 404 error will be returned.

4. Immutable records enable safe caching: Each result also includes an Open Graph image at `/og/[shareId].png`, which is rendered on demand using `ImageResponse` from `next/og`. The image route follows the same process as the result page: validate the ID, load the record, resolve the versioned definition, and choose a renderer based on the definition's OG template ID.

A successful render is served with a `Cache-Control` header set to `public, max-age=31536000, immutable`, ensuring the image remains unchanged and cacheable for 31,536,000 seconds (one year). This decision is valid due to the immutability of the stored results.