The hard part is not editing the content. It is shipping those edits to production while real users have progress attached to it. This post is about how I update the exam content without losing anything the users did.

The problem

Exam content in my app is data in MongoDB: exams, model tests, modules, tasks and assets. Users produce their own data on top of it: accounts, attempts and submissions. Those two kinds of data live in the same database but have completely different lifecycles.

• Content is authored by me. It changes when I change the code.
• User data is created at runtime. It must never be lost.

If a content update wipes a user's attempts, or breaks the link between a user's progress and a model test, that is a bug I cannot take back. So the update mechanism has to be safe by construction.

The design I chose

The exam content lives in code, in the repository, as typed seed data. The database is a copy of it. That gives me version control, review and diffs for content, which I would not get from editing documents in a database console.

To keep the copy in sync I use one number, a SEED_VERSION in the backend. When the backend starts, it compares that number with the last applied version. If they differ, it reseeds. If they match, it does nothing.

A generic sketch:

export const SEED_VERSION = 1; // bumped on structural content changes

const CONTENT_COLLECTIONS = ['exams', 'modelTests', 'modules', 'tasks', 'assets'] as const;

async function seedIfNeeded(db: Db) {
  const applied = await getAppliedSeedVersion(db); // from a small meta document
  if (applied === SEED_VERSION) return;

  for (const name of CONTENT_COLLECTIONS) {
    await reseedCollection(db, name);
  }
  await setAppliedSeedVersion(db, SEED_VERSION);
}

The key line is the list of collections. A reseed touches the content collections and nothing else. Users, attempts and submissions are not in that list, so they cannot be affected, even if I make a mistake in the seeding code.

Why not a proper migration framework? For a solo project whose content is already versioned in git, the seed version is the migration. There is no history of up and down scripts to maintain, because the target state is always "the content in this commit". The price is that I have to be strict about what a reseed is allowed to touch, and that is what the explicit collection list is for.

It also keeps the mental model small. At any moment I can answer two questions: which version of the content is in the code, and which version is in the database. If they differ, the next start of the backend closes the gap.

Stable slugs keep progress linked

Attempts and progress refer to content. If they pointed at database-generated ids, a reseed would create new ids and orphan every attempt.

So model tests have stable slugs, written by me, that never change once a test is published. Progress is linked through the slug, not through an id that the seed process generates:

// pseudo-code: upsert by a stable key
await db.collection('modelTests').updateOne(
  { slug: test.slug },
  { $set: { ...test } },
  { upsert: true }
);

One more detail: because the seed is an upsert by slug, running it twice gives the same result as running it once. I like that property a lot. If a deploy is interrupted halfway, I can simply start the backend again.

With that, a reseed refreshes the content of "the same test" instead of creating a different one. The user's attempt still points at the same slug afterwards. The rule I follow: a slug is an identity, not a label. If I reword a title, the slug stays.

Small fixes without a reseed

Not every change deserves a version bump. A typo, a corrected explanation or a better hint is a small text change. For those I sync the changed text in place and leave SEED_VERSION alone. A reseed is for structural changes: new tasks, reordered modules, changed task types.

I keep that distinction on purpose. The smaller the operation, the less there is to go wrong, and fixing a typo should never feel like a migration.

Before a production reseed: a backup

Even with a narrow reseed, I take a database dump before I deploy a version bump. The dump is the answer to "what if I got something wrong in a way I did not expect". It is cheap, and my routine is:

1. Dump the database.
2. Deploy the new version.
3. Check that the backend started and seeded.
4. Open a test or two and look at them.

The dump also changes how I think about the deploy. When I know I can go back, I look at the result calmly instead of nervously. That alone is worth the extra minute.

What went wrong

1. Treating the whole database as seed data. My first idea was simpler: wipe and reseed everything on a version change. It works on a laptop, where nobody has progress. It would have been a disaster in production. Splitting "content" from "user data" and naming the content collections explicitly was the most important correction.

2. Using generated ids as references. An early version linked progress to ids produced during seeding. Changing the seed order changed the ids. Moving to stable slugs fixed it, but it showed me that identity has to be designed, not left to the database.

3. Bumping the version for everything. For a while every tiny text fix meant a version bump and a full content reseed. It was safe, but heavy, and it made me hesitate to fix small things. In-place sync for small text changes removed that friction.

4. Leaving the backup as a manual habit. The seeding code is safe by construction, but the backup depends on me remembering it. A habit is weaker than a script, and the obvious improvement is to make the dump a step of the deploy that cannot be skipped.

Takeaways

• Separate content from user data, in code and in the database.
• Make the reseed's scope an explicit list of collections, so mistakes have a small blast radius.
• Give published content a stable identity, and link user data to that identity.
• Keep a cheap path for small fixes and an explicit path for structural changes.
• Take a backup before every production reseed.

I built most of this with AI coding agents (Claude Code), and the explicit list of collections turned out to be a useful guardrail when reviewing their changes: it is easy to see if a change tries to touch something it should not.

I'm building this at examready.at, feedback welcome.

I'm a solo developer, and the first thing I had to get right wasn't the UI. It was the shape of the data. This post is about how I modeled exam content, what I got wrong along the way, and what I would do again.

The problem

A language exam looks like a list of questions. It isn't.

A full model test (a "Modellsatz") has four modules: reading (Lesen), listening (Hören), writing (Schreiben) and speaking (Sprechen). Each module has several tasks, and every task has its own format: true/false statements about a text, matching ads to situations, multiple choice, a listening task where the audio plays twice, writing an e-mail, speaking prompts. Tasks also come with assets such as audio files and images.

On top of that I had a few requirements:

• Tasks should look like the real exam, with the real structure.
• Objective tasks should be scored automatically and consistently.
• The same tasks should work inside short lessons, not only in full tests.
• The correct answers must never reach the browser before the user submits.

The design I chose

The hierarchy is plain and, I think, the natural one for exams:

Exam > Model test > Module > Task > Asset

A model test belongs to an exam, a module belongs to a model test, a task belongs to a module, and assets (audio, images) hang off tasks. Each level is its own MongoDB collection and references its parent by id. I did consider embedding everything in one big document per model test. I decided against it because tasks get reused in lessons and I wanted to load one task without loading a whole test.

The most important decision was that every task has a type, and the type decides everything else: the shape of the content, which component renders it, and how it is scored. A discriminated union in TypeScript makes this explicit:

type TaskContent =
  | { type: 'true_false'; text: string; statements: { id: string; text: string }[] }
  | { type: 'matching'; situations: Item[]; ads: Item[] }
  | { type: 'multiple_choice'; question: string; options: Item[] }
  | { type: 'listening_two_plays'; audioAssetId: string; questions: Item[] }
  | { type: 'email_writing'; prompt: string; points: string[] }
  | { type: 'speaking'; prompt: string };

type TaskType = TaskContent['type'];

interface Task {
  slug: string;
  moduleId: string;
  content: TaskContent;
}

The frontend switches on content.type to pick a renderer, and TypeScript narrows the rest. Adding a new task type is a compile error everywhere I forgot to handle it, which is exactly what I want.

Content and answer key are separate

The first rule I set was that the correct answer is never stored inside the task. Tasks live in one collection, answer keys live in another, linked by task id:

interface AnswerKey {
  taskId: string;
  type: TaskType;
  answers: Record<string, string>; // item id -> correct option id
  explanations?: Record<string, string>;
}

The flow is then simple. The client asks for a task and receives only the content. The user answers and submits. The server loads the key, scores the answer, and only in the response does the key (and the explanation) travel to the browser.

There is no "strip the answers before sending" step to forget. The endpoint that serves tasks does not query the key collection at all. If I make a mistake in a serializer, the worst outcome is a missing field, not a leaked answer.

A scoring registry

Each task type has a scoring function, and a registry maps the type to that function:

type Scorer = (key: AnswerKey, answer: unknown) => { points: number; max: number };

const scorers: Record<TaskType, Scorer> = {
  true_false: scoreTrueFalse,
  matching: scoreMatching,
  multiple_choice: scoreMultipleChoice,
  listening_two_plays: scoreListening,
  email_writing: scoreWriting,
  speaking: scoreSpeaking,
};

export function scoreTask(task: Task, key: AnswerKey, answer: unknown) {
  return scorers[task.content.type](key, answer);
}

This is a generic sketch, not my real code, but the idea is the same. Because the registry is typed as Record<TaskType, Scorer>, TypeScript refuses to compile if I add a task type without a scorer.

The part I like most: the same function scores full tests and mini tasks inside lessons. A lesson that ends with a true/false task calls scoreTask, and so does a full model test. There is one place where "what counts as correct" is defined.

What went wrong

I made three mistakes worth sharing.

1. Keeping the key next to the content. My first instinct was a correct: true flag on each option. It is convenient, and it is exactly how answers leak. Every endpoint then needs to remember to remove those flags. I moved the keys out before it became a habit, but it was a rewrite I could have avoided.

2. Stringly typed task types. Early on, a task type was just a string, checked in a few if statements in different places. Adding a type meant hunting for every place that cared. The union plus the Record registry fixed that, but it came after I had already spread the logic around.

3. Thinking of scoring as right or wrong. Multiple choice fits a boolean nicely. A matching task with several pairs, or a writing task, does not. Returning points and a maximum, instead of a boolean, made the registry usable for all types without special cases. I'm glad I changed this before building the results screens on top of it.

Why separate collections and not one big document

MongoDB makes it tempting to put a whole model test into one document: modules, tasks and all. It reads nicely in a console. But my tasks have a second life as mini tasks inside lessons, and a lesson should be able to load exactly one task without dragging a full test along. References between collections cost a little more at query time and buy a lot of flexibility.

Assets follow the same logic. Audio and images are referenced by id from the task, so one file can be reused and replaced without touching the task content.

Takeaways

• Model the real hierarchy of the thing you are teaching. For exams that is exam, test, module, task, asset.
• Give every task a type and let the type drive rendering and scoring.
• Store content and answer keys separately, so the safe path is the default path.
• Use one scoring registry for every context. Lessons and full tests should never disagree about what is correct.
• Let the compiler tell you what you forgot. A typed union and a Record over it are cheap and effective.

None of this is clever. It is mostly about deciding early where the boundaries are. I built this as a solo developer with a lot of help from AI coding agents (Claude Code), and having clear types and boundaries made it much easier to review what the agents wrote.

In the next posts I'll write about the lesson player, the hosting setup and how I update exam content in production without losing user progress.

I'm building this at examready.at, feedback welcome.