Exams and blueprints

An exam is a study objective

Not a sitting. An Exam sits at the top of the hierarchy, above systems and disciplines: a particular board or step exam a learner is working toward.

Field	Is
slug, name
family	Groups related exams
sort_order, is_active
description
article_views	A JSON list restricting which article views apply — short, long, clinical. Null means all of them.

article_views is why a learner working toward one exam may see only the summary and clinical views of an article while another sees all three. The server filters sections by it; it is not a client-side preference.

Membership is a link table on both sides — one question, and one article, can belong to several exams.

A learner picks theirs with PUT /exams/active. That choice then feeds:

• which article views they are shown
• the weights the adaptive builder uses
• the relevance term in recommendations
• the scope of the attempts the ranking considers

A blueprint is the board's published content outline

One ExamBlueprint row is one line of that outline.

Field	Is
exam_id
parent_id	Null for a domain; set for a subdomain nested under one
code	The board's own numbering — 4.A
weight	The percentage of the paper. Set on domains only.

A separate link table maps a blueprint line to one or more categories. It is a mapping, not a reshaping of the taxonomy — the board's outline and your category tree stay independent things that happen to be related.

Allocation

allocate() distributes a target paper size across domains by weight using largest-remainder rounding, redistributing the shortfall from thin domains, so a 40-question paper built from percentages actually contains 40 questions.

This is what both the blueprint builder algorithm and the blueprint-shaped study plans use.

The endpoints

Endpoint	Does	Gate
GET /exams/	List, with per-exam question counts	any user
PUT /exams/active	Set the learner's objective	any user
POST /exams/, PATCH /exams/{id}	Create and edit	moderator
POST /exams/{id}/assign, DELETE /exams/{id}/assign	Assign or unassign questions by category	moderator
GET /exams/{id}/blueprint	Read the domains
PUT /exams/{id}/blueprint/{blueprint_id}/categories	Map a blueprint line to categories	moderator

Assignment works by category rather than question by question, because the outline is about topics and so is the tree.