THE ACHIEVEMENTS STARTER / How it works Open source
THOUGHTFUL ON THE INSIDE, TOO

Small packages. Clear boundaries.

A working example of the libraries, with the application decisions out in the open.

The engine

achievements-engine evaluates definitions and produces achievement state. It works in the browser and on the server.

The React layer

react-achievements turns that state into hooks, progress, and an achievement widget. This app uses the published package.

This application

Next.js owns lessons and routes. Supabase provides identity and Postgres. The database adapter lives here.

One action. One consistent result.

  1. Validate the request

    The server verifies the signed-in user and known lesson ID. The browser never chooses who earns a reward.

  2. Lock and record

    A database transaction locks the learner row and records a unique lesson completion. Repeated requests count once.

  3. Derive and evaluate

    The server calculates the completion total and passes absolute metrics to the engine using a repository bound to that same transaction.

  4. Commit, then display

    Lesson completion and achievement state commit together. A failure rolls both back. The UI displays the committed snapshot.

Consistency comes from the database transaction. A retry may miss a celebration, but it cannot duplicate completed progress.

A playground with its own sandbox

The preview runs locally in memory. Safe configuration controls produce real definitions and complete code exports. Resetting the preview never touches saved learning progress.

Read the technical architecture
Take a closer look.

Every route, migration, and design decision is available in the source.

Start building