The question bank

Every question, one shared category tree, and the machinery that gets questions in and files them.

• Importing a document — PDF upload, spreadsheet and QTI import, and the draft stage everything lands in.

• Extraction modes — the seven strategies, and which document each one is for.

• Reviewing drafts — the workbench, the batch, and the one moment a question id is taken.

• Writing and editing a question — the editor, and what an edit does to answers already given.

• Categories — the tree shared by questions, articles and decks, and how multi-category filtering works.

• Tags — what is live, what was retired, and how classification is actually run.

• Exams and blueprints — study objectives, content outlines and weighted papers.

Nothing lands in the bank directly

Every ingestion path — PDF extraction, spreadsheet import, QTI import — produces draft questions in a draft batch. Nothing creates a live question or a live quiz on its own. A person reads the drafts and moves the ones worth keeping into the bank.

A question

Field	Notes
question_text	The stem. Bank content — everybody sees it.
options	Likewise.
correct_answer, explanation, option_explanations, key_points, attending_tip	The answer side. Redacted for anybody who may not edit it, and refused outright outside an attempt.
question_category_id	The primary filing.
additional categories	Rows in a link table — a question may sit in more than one place.
difficulty	easy, medium, hard.
source_quiz_id	Where it came from. Note the name: the Python attribute is source_quiz_id and the database column is quiz_id.
user_id	Always NULL. The bank has no owners.
deleted_at	Soft delete.
embedding	1024 dimensions, in pgvector, alongside the row.

Figures on a question

Two different mechanisms, easy to conflate:

• has_figure is a transient signal from the extraction model — "answering this needs the picture". It is not a column. It decides only whether an extracted page image is attached to the draft at all, which is what keeps every question from acquiring whatever happened to be on its page.
• Persisted figures are QuestionMedia rows: any number per question, each with a role (stem, explanation), a label, a caption specific to this question, and a position. An explanation-role figure also carries the library's own title, caption, source and overlay — surfaced only once the answer is revealed, never on the stem.

The older image_path and explanation_image_path columns still exist for compatibility.

Question versioning

Every edit snapshots the question first. See Revisions and restoring.