RanaZe: Step 3 Trainer

Environment deployment, database migration, and UAT-to-PRD promotion procedures are documented in ENVIRONMENTS.md.

Godot-based USMLE Step 3 study trainer with a bundled ASP.NET Core Questions API.

Local API

Run the Questions API:

dotnet run --project api/QuestionsApi/QuestionsApi.csproj

For deployed environments, set these as environment variables:

MongoDB__ConnectionString
MongoDB__DatabaseName
Jwt__Key
Jwt__Issuer
Jwt__Audience

Default local endpoint:

http://localhost:5008/api/questions/search

The Godot client reads this from project.godot:

step3/questions_api_url

Browser Pre-Alpha

The Web export is deployed at https://doctor.ranaze.com through the existing Cloudflare, Traefik, and Kubernetes stack. See WEB_DEPLOYMENT.md for DNS, routing, deployment, and verification details.

Question Bank PDF Imports

Use QBANK_PDF_IMPORT_RUNBOOK.md for the complete OCR, original-authoring, validation, independent-review, reference-review, bulk insertion, production-verification, and cleanup workflow.

Question Image Copyright Review

All questions containing images must receive a copyright and licensing review before publication or distribution. This applies both to newly submitted images and to every image already stored in the question bank.

For each image-bearing question, document:

• the original source and creator, when known;
• the applicable license or written permission;
• whether attribution is required and where it is displayed;
• whether the image was modified or generated;
• the reviewer and review date.

Do not publish an image when its source or reuse rights cannot be established. Remove or replace images that fail review. Images added for development or manual testing are not exempt from this requirement.

Outstanding action: audit every existing question with a non-empty media field before treating the current question bank as cleared for release.

Question Text Originality Review

Every question must also receive an originality and copyright review before publication or distribution. Review the stem, lead-in, answer choices, explanations, follow-up questions, teaching points, and distinctive combinations of patient details for substantial overlap with copyrighted question banks, books, articles, screenshots, or other source material.

Changing only names, ages, individual values, or a few words is not sufficient when the structure, sequence, and expression remain recognizably derived from a copyrighted source. Clinical facts and concepts may be used, but each question must express them independently with original organization and wording.

For each reviewed question, document the reviewer, review date, any reference materials consulted, and whether revisions were required. Do not publish a question when substantial textual or structural overlap remains unresolved.

Outstanding action: perform this review for every existing question in the question bank, not only newly submitted questions, before considering the bank cleared for release.

Question Verification References

Every question must provide direct reference links to authoritative sources that allow reviewers to verify the clinical, scientific, statistical, or ethical information used in the stem, answer key, and explanation. References are required before publication, even when the tested fact is considered standard knowledge.

Prefer current primary or authoritative sources, including professional society guidelines, government health agencies, original research, and official drug or product labeling. Use secondary sources only when a suitable primary or authoritative source is unavailable. Link to the specific guideline, article, or document rather than a search-results page or an organization's home page.

For each question, document:

• at least one direct reference URL;
• the title and publishing organization for each reference;
• which key claim or teaching point the reference supports;
• the date the source was accessed and the reviewer who verified it.

References must support the keyed answer and any management recommendations, diagnostic thresholds, formulas, or numerical claims. A citation does not grant permission to copy wording or media; the separate text-originality and image- copyright requirements still apply. Store each verified source in the question document's references array; published question writes require at least one complete reference. Legacy questions with an empty array remain readable while awaiting reference review.

Variable Distractor Pools

Published questions may contain more than the five choices shown to a learner. The player always presents the correct answer plus four randomly selected distractors and keeps that set stable for the duration of the active session. Choice IDs are stable content identifiers; the A-E labels shown in the player are based on presentation order and must not be stored as answer analytics.

Add only distractors that are plausible for the exact vignette while remaining unambiguously incorrect. Every added distractor requires its own explanation, stem-anchored wrong-answer follow-up, independent accuracy review, and authoritative reference coverage. There is no required number of additional distractors: record an exception instead of forcing a weak or co-correct answer. Do not expand production pools until the v2 exposure-statistics backfill metric reports completion.

See QBANK_DISTRACTOR_ENRICHMENT_RUNBOOK.md for the repeatable authoring, independent-audit, merge, and production verification procedure.

Duplicate Question Review

Every question must be checked for duplicates before publication. This review must detect both exact duplicates and near-duplicates that test the same concept with substantially equivalent stems, decisive findings, lead-ins, answer sets, or teaching objectives despite different wording or external IDs.

Repeated coverage of a learning objective is acceptable when the presentation, reasoning path, or learner task is meaningfully different. Reject exact copies and near-duplicates that merely change a patient age, reorder answers, or make minor value and wording changes. When substantial duplication remains, retain the stronger question, merge any useful unique teaching material, and remove or substantially differentiate the other version.

Document the reviewer, review date, compared question IDs, and disposition of each potential duplicate. Outstanding action: run this review across the entire existing question bank before considering it cleared for release.

Push Build

.github/workflows/questions-api.yml builds and publishes the Questions API Docker image to GitHub Container Registry on pushes to main.

Set deployment hosting to consume:

ghcr.io/<owner>/<repo>/questions-api:latest