# Knowledge graph index

_Generated by `kg.mjs index` — do not edit. Start with [README](README.md)._

214 nodes.

## entity (55)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [item](nodes/item.md) | A QTI 3.0 assessment item (question) - versioned row in `items` holding the item XML, derived answer key/scoring fields, metadata, workflow state and pub_state, owned by a bank. | 95 | 10 | content, core |
| [form](nodes/form.md) | A test form: a versioned, bank-owned assembly of sections and items plus a large form_settings JSON that drives the player; published for delivery. | 89 | 13 | forms, core |
| [bank](nodes/bank.md) | An item bank - the top-level content container (and permission scope) that owns items, stimuli, resources, media, forms, workflow states, custom fields and label bundles. | 67 | 14 | content, core |
| [session](nodes/session.md) | A test-taking session - one candidate's attempt at one form, carrying lifecycle state, player navigation position, PNP accommodations, score status and battery membership. | 64 | 10 | delivery, core |
| [shared-stimulus](nodes/shared-stimulus.md) | A passage/stimulus (QTI assessment-stimulus) in a bank that items reference via qti-assessment-stimulus-ref; has its own workflow state, lock, media and history. | 60 | 6 | content |
| [response](nodes/response.md) | A candidate's response to one item in a session (one row per session+item), holding the raw QTI response variables, machine/human score and marked/scored status. | 50 | 5 | delivery, scoring, core |
| [media](nodes/media.md) | A bank media asset (image, audio, video, CSS, font…) - DB row with name/URL/content type/alt text; bytes live in the public S3 bucket (optionally behind CloudFront). Linked to items, stimuli and resources through join tables derived from their QTI. | 37 | 3 | content |
| [standard](nodes/standard.md) | A node in the global academic-standards tree (authority > publication > subject > section > standard…) loaded from Academic Benchmarks; items (and traits) align to standards via item_standards. | 37 | 2 | content |
| [account](nodes/account.md) | A client tenant of AD (a host app such as Navvy/Abigail) that owns API credentials, bank access (account_banks), sessions and callback subscriptions. | 36 | 4 | accounts |
| [bank-state](nodes/bank-state.md) | A per-bank workflow state for items, shared stimuli or forms (e.g. Draft, Review, Approved), with allowed next states, role visibility and clone behaviour. | 35 | 2 | content |
| [section](nodes/section.md) | A section (testPart/section) of a form holding an ordered list of items and section-level settings (timer, calculators, rulers, exhibits, intro screen, labels); linear or CAT-adaptive. | 34 | 5 | forms |
| [credential](nodes/credential.md) | An OAuth client_id/secret pair belonging to an account; its permissions JSON (ListBanks / Bank+allow-list / Standards / Delivery / Scoring) is what every API permission check reads. | 31 | 3 | accounts, auth |
| [job-history](nodes/job-history.md) | A record of a long-running background job (QTI import/export, XPRT print, Navvy standards report) with status, progress, per-entity results and errors; temp files are cleaned up by a cron. | 28 | 3 | platform |
| [scoring-stat-set](nodes/scoring-stat-set.md) | A named, bank-scoped set of IRT a/b/c parameters that a form can reference (forms.scoring_stat_set_id) so its items are scored with those parameters. | 28 | 4 | stats, scoring |
| [trait](nodes/trait.md) | A scoring trait (rubric dimension) of a human-scored item - min/max/step/weight, optional standards and custom-field metadata - used for multi-trait human/AI scoring. | 28 | 3 | scoring, content |
| [cat-session](nodes/cat-session.md) | One row per (AD session, adaptive section) linking an AD session to its ad-cat session; holds the CAT seed, current item number, starting settings and the final ability estimate (theta, min/max theta, SEM). | 27 | 4 | cat, delivery |
| [stm](nodes/stm.md) | A form's scoring test map (STM) — one per form; holds reporting groups, the objectives that derive test-level outcomes, and attemptedness thresholds. | 27 | 3 | scoring |
| [battery-stm](nodes/battery-stm.md) | Bank-scoped battery scoring test map — combines several forms (units) into one scored battery with its own objectives, scoring mode and thresholds. | 26 | 5 | scoring, battery |
| [battery-attempt](nodes/battery-attempt.md) | The "virtual session" for one student's battery — keyed by a caller-supplied battery_attempt_id, groups unit sessions and holds battery status, flags, totals and outcomes. | 25 | 6 | scoring, battery |
| [objective](nodes/objective.md) | One scoring rule inside a form STM — its type (percent correct, lookup, IRT, RCP, …), input and JSON metadata determine which session outcomes it emits. | 24 | 3 | scoring |
| [session-outcome](nodes/session-outcome.md) | One derived test-level score of a submitted session (RAW_SCORE, PERCENT_CORRECT, THETA, scale score, subscore, standard roll-up …), keyed by (session_id, objective_key). | 24 | 3 | scoring |
| [callback-subscription](nodes/callback-subscription.md) | A callback URL registered for an account, flagged for session events and/or authoring events; the dispatcher's source of destinations for host callbacks. | 22 | 2 | accounts, callbacks |
| [response-trait-score](nodes/response-trait-score.md) | Score given to one trait (rubric dimension) of a response by a human scorer or OSCAR; summed (× trait weight) into the response score. | 22 | 3 | scoring, human-scoring |
| [form-setting-profile](nodes/form-setting-profile.md) | A reusable, bank-scoped bundle of form settings; when attached to a form (forms.setting_profile_id) its override set replaces the form's own settings at delivery, preview and in effective_* read fields. | 21 | 3 | forms, settings |
| [item-test-case](nodes/item-test-case.md) | A stored candidate response plus expected score/max score used to regression-test an item's QTI response processing; runs record the last result. | 20 | 2 | content, scoring |
| [battery-outcome](nodes/battery-outcome.md) | One computed battery-level score for a battery attempt, keyed by (battery_attempt_id, objective_key); mirrors session_outcomes. | 19 | 3 | scoring, battery |
| [resource](nodes/resource.md) | A non-item QTI content block in a bank (mainly section intro / instructions screens) with its own media links; copied into form section settings as intro_item. | 19 | 3 | content |
| [historical-stat-set](nodes/historical-stat-set.md) | A named, bank-scoped set of historical item statistics (classical/IRT/DIF/distractor data from past administrations) used mainly for form blueprinting queries. | 18 | 4 | stats |
| [item-history](nodes/item-history.md) | Append-only audit row written on every item save - who saved, how (saved_via), and a full JSON snapshot of the item after the save. | 18 | 3 | content |
| [callback-credential](nodes/callback-credential.md) | A global (not per-account) auth header name + AES-GCM-encrypted token that AD attaches when calling one exact callback URL. | 17 | 2 | accounts, callbacks, security |
| [cat-section](nodes/cat-section.md) | An ad-cat section — the CAT engine configuration (control file + item pool, optional field-test file) for one adaptive form section, content-addressed by an MD5-derived `sec:` id and stored as JSON in S3 by the Java service. | 17 | 1 | cat, java |
| [bank-secret](nodes/bank-secret.md) | Per-bank third-party service credentials (url, key, secret, metadata) keyed by (bank_id, service), e.g. "oscar" or "metametrics"; stored in plain text, masked on read. | 16 | 2 | content, integrations |
| [session-section](nodes/session-section.md) | Per-section progress record within a session (NOT_STARTED / IN_PROGRESS / SUBMITTED with start and submit timestamps), created lazily as the player enters sections. | 16 | 3 | delivery |
| [cat-adaptive-slot](nodes/cat-adaptive-slot.md) | One delivered position in a CAT session — the item ad-cat selected at a given sequence, its response shell, review-range flag and force-complete marker. | 15 | 5 | cat, delivery |
| [form-history](nodes/form-history.md) | An append-only audit snapshot of a form (full form JSON after the change) written on every SaveForm; also mined to backfill legacy CAT section items. | 15 | 2 | forms, audit |
| [legacy-cat-section-item](nodes/legacy-cat-section-item.md) | Items that were removed from an adaptive form's sections in a later edit but may still be served by an older ad-cat section — kept per form so delivery can still resolve them and scoring can exclude them. | 15 | 3 | cat, forms |
| [form-oscar-mapping](nodes/form-oscar-mapping.md) | Per-form mapping of a human-scored item (by identifier) to its OSCAR tenant/project/section/item refs; drives which responses are sent to OSCAR at saveoff. | 14 | 3 | scoring, integration |
| [shared-stimulus-history](nodes/shared-stimulus-history.md) | Append-only audit row written on every shared-stimulus save, holding a JSON snapshot of the stimulus after the save. | 14 | 3 | content |
| [label-bundle](nodes/label-bundle.md) | A per-bank, per-language bundle of player UI label/string overrides (buttons, modals, toolbar, tutorial…) that the player loads by language. | 13 | 2 | delivery, content |
| [feature-flag](nodes/feature-flag.md) | A row in feature_flags — unique key, boolean value and JSON config — read at runtime through FeatureFlagService (60 s cache) and edited from the admin UI. | 12 | 1 | platform |
| [oscar-score](nodes/oscar-score.md) | A raw score entry OSCAR returned for a response on callback (one row per score_id, the applied one flagged is_final); replaced wholesale on each callback. | 12 | 2 | scoring, integration |
| [bank-custom-field](nodes/bank-custom-field.md) | A per-bank custom metadata field definition (key, label, type, options) for items, stimuli, forms or media; values live in the content row's metadata jsonb. | 11 | 2 | content |
| [battery-objective](nodes/battery-objective.md) | One scoring rule of a battery STM — aggregates unit outcomes (sum/avg/weighted), derives (LOOKUP/CALCULATED/METAMETRICS) or re-scores merged unit responses with any form objective type. | 11 | 3 | scoring, battery |
| [battery-unit](nodes/battery-unit.md) | One ordered unit of a battery STM (e.g. MATH), listing the forms whose submitted session can satisfy it (battery_unit_forms). | 11 | 3 | scoring, battery |
| [scoring-stat](nodes/scoring-stat.md) | One item's IRT a/b/c scoring parameters within a scoring stat set, keyed by item identifier (follows the logical item across versions). | 11 | 3 | stats, scoring |
| [statistic-upload](nodes/statistic-upload.md) | LEGACY item-statistics path - an uploaded stats CSV (statistic_uploads) and its per-item/per-admin rows (statistic_items); superseded by stat sets (stat-upload, historical-stat-set, historical-stat). | 11 | 3 | stats, legacy |
| [form-reviewer](nodes/form-reviewer.md) | An external reviewer of a form who gets a signed 24h link to an HTML review page and submits per-item comments. | 10 | 2 | forms, review |
| [historical-stat](nodes/historical-stat.md) | One item version's historical statistics within a historical stat set - promoted columns (p_value, n_total, item_mean, ptbis, item_status, max_points) plus categorised JSONB data. | 10 | 3 | stats |
| [admin-user](nodes/admin-user.md) | A login (email + bcrypt password) for the internal AD admin UI; authenticating mints an admin-issuer JWT for /api/admin. | 9 | 1 | accounts, auth |
| [stat-upload](nodes/stat-upload.md) | Audit record of one stats CSV uploaded into a historical or scoring stat set (S3 copy, status, items found/updated, columns, error). | 9 | 4 | stats |
| [bank-ai-instruction](nodes/bank-ai-instruction.md) | A per-bank uploaded instruction file (style guide, item-writing rules) whose text is sent to Claude as extra context when generating interactions. | 8 | 2 | ai, content |
| [bank-ai-translation-override](nodes/bank-ai-translation-override.md) | A per-bank uploaded JSON glossary file ({"source term":"forced translation"}) applied to every AI translation result in that bank. | 8 | 2 | ai, content |
| [bank-print-formtype-config](nodes/bank-print-formtype-config.md) | Per-bank list of printable form types (value + display text, one default) that populate form_settings.print_settings.print_formtype and are sent to XPRT. | 6 | 2 | forms, print |
| [cat-session-state](nodes/cat-session-state.md) | Final CAT test-state snapshot for a CAT session — the per-item interim theta/CSEM list ad-cat returns with its ability estimate, stored as jsonb. | 5 | 3 | cat, delivery |
| [lookup-table](nodes/lookup-table.md) | Planned shared raw-to-scale lookup table (lookup_tables / lookup_entries); Go structs exist but the tables were never created — live lookups are inline objectives.lookups. | 5 | 0 | scoring |

## module (26)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [item-authoring](nodes/item-authoring.md) | Go services behind content authoring - banks, workflow states and custom fields, items (save/derive/version/clone/copy/bulk/lock/delete), shared stimuli, resources, media/files, standards, label bundles and item test cases. | 88 | 46 | content, core |
| [scoring-engine](nodes/scoring-engine.md) | Derived (test-level) scoring in adam_ad — form STM scoring (Stm.Score with 11 objective types), battery scoring across sessions, human trait scoring and the SID test map. | 78 | 38 | scoring, battery |
| [qti-engine](nodes/qti-engine.md) | QTI 3.0 parsing, response processing/scoring (incl. custom operators to MRE, pymathengine, PCI, graph scorers), IMS content-package import and export. | 73 | 25 | content, scoring, qti |
| [async-jobs](nodes/async-jobs.md) | In-process background workers started by adam_ad - the save-off SQS consumer that scores submitted sessions and fires host callbacks, the bulk SQS consumer for AI translations, the job-history cleanup cron, the CAT out-of-order and session/CAT out-of-sync alert crons - plus JobService. | 49 | 32 | platform, delivery, scoring |
| [cat-engine](nodes/cat-engine.md) | Computer-adaptive testing (CAT) orchestration inside adam_ad — HTTP client for the ad-cat service, the AdaptiveFormDriver that delivers adaptive sections, and persistence of CAT sessions, adaptive slots and final ability estimates. | 48 | 16 | cat, delivery |
| [form-assembly](nodes/form-assembly.md) | adam_ad form services — form CRUD/versioning/pub_state, sections and form_items, setting profiles (storage + merge), form history, reviewers, preview, test map, derived-scoring test, print/reviewer HTML, delivery-side form loading. | 47 | 41 | forms, core |
| [delivery-engine](nodes/delivery-engine.md) | Runtime test delivery in adam_ad - session registration and lifecycle, player launch tokens, the form driver (linear here, adaptive in cat-engine) that saves responses and navigates, section progress, response scoring, and the delivery HTTP handlers. | 45 | 29 | delivery, core |
| [adam-player](nodes/adam-player.md) | Vue 3 + Pinia test player compiled to one custom element (<ad-test-player>, ad-test-player.js) that delivers an AD form to a test taker in LIVE, PRACTICE or PREVIEW mode over the player-auth delivery API. | 40 | 11 | delivery, frontend |
| [accounts-auth](nodes/accounts-auth.md) | Tenancy and access control for adam_ad — accounts, credentials and their permission JSON, OAuth/JWT issuance and auth middleware, admin users, bank secrets, callback subscriptions/credentials, feature-flag CRUD, and the admin API. | 35 | 27 | accounts, auth, security |
| [ad-authoring](nodes/ad-authoring.md) | Embeddable Vue 3 authoring library (ad-authoring.js) shipping item, stimulus, resource, media, test-case and standards/media picker custom elements; edits QTI 3.0 entirely client-side and persists nothing itself — the host app supplies data and callbacks. | 34 | 4 | content, authoring, frontend, qti |
| [item-components](nodes/item-components.md) | Lit 3 web-component library that renders QTI 3.0 items (player wrappers, interactions, math, feedback, tools) as one self-registering bundle, qti-item-components-v1.0.0.js, loaded by the player, authoring and print pages. | 32 | 4 | delivery, authoring, frontend, qti |
| [oscar-scoring](nodes/oscar-scoring.md) | services/oscar - maps form items to OSCAR, sends constructed responses to OSCAR at saveoff, ingests OSCAR score callbacks into trait scores, and proxies OSCAR manifest/item/rubric reads. | 32 | 16 | scoring, integration |
| [api-explorer](nodes/api-explorer.md) | Vue 3 + PrimeVue "AD Explorer" internal web app (served at /explorer) that logs in with an account credential and browses/edits banks, items, passages, forms, media, resources, stat sets, sessions, QTI import/export and jobs through generated TypeScript clients of the AD APIs. | 29 | 31 | ui, tooling, internal |
| [ai-assist](nodes/ai-assist.md) | AI item generation (QTI interaction snippets from standards) and AI translation of items/stimuli into new cloned content, backed by Claude on AWS Bedrock. | 26 | 14 | ai, content |
| [adam-ad-scripts](nodes/adam-ad-scripts.md) | Offline operator scripts under adam_ad/src/scripts — a few reusable API-driven tools (bulk form load, STM clone, AW form build, AB standards CLI) plus ~100 one-off Go/SQL/Node content migrations and backfills, most of which no longer compile. | 25 | 33 | tooling |
| [admin-ui](nodes/admin-ui.md) | Internal Vue 3 + Vite admin SPA served at /admin — login, accounts, credentials and permission editor, banks and bank states, account-bank links, callbacks, callback credentials, feature flags. | 24 | 1 | ui, admin |
| [xprt-orchestration](nodes/xprt-orchestration.md) | A&D-owned paper/print PDF workflow — eligibility check, async job that QTI-exports an item/stimulus/form, stages the zip, submits it to XPRT, polls, and serves/invalidates the cached PDF. | 19 | 12 | print, integration |
| [adam-ad](nodes/adam-ad.md) | The adam_ad Go server process — main.go boot sequence, Gin engine and global middleware, static asset hosting, API registration, health check, options, DB/SQS/S3/New Relic wiring, shared utils/errors, Docker/Jenkins build. | 17 | 9 | platform |
| [item-statistics](nodes/item-statistics.md) | Item statistics - historical and scoring stat sets (CSV upload, bulk/v2 query, IRT overlay at scoring time), the legacy statistic-upload path, and the bank analytics overview. | 17 | 25 | stats, scoring |
| [ad-cat](nodes/ad-cat.md) | Standalone Java 21 / Spring Boot REST service ("CATService", deployed as coread-cat) that wraps Pearson's proprietary CAT engine jar (cat-pearson 3.24.26) to create CAT sections from psychometric input files and run adaptive sessions (next-item selection, ability estimation, force complete). | 16 | 6 | cat, java, service |
| [scoring-api](nodes/scoring-api.md) | Standalone stateless Go/Gin service (scoring-api/) that scores one QTI item response by importing adam_ad's QTI engine as a Go module. | 16 | 5 | scoring, service |
| [metametrics-scoring](nodes/metametrics-scoring.md) | services/metametrics - resolves METAMETRICS STM objectives by converting a scale score + SEM into a Lexile/Quantile measure via the MetaMetrics Scoring Service, with per-bank credentials and token caching. | 12 | 5 | scoring, integration |
| [pymathengine](nodes/pymathengine.md) | Python (Flask + SymPy) math-answer equivalence engine deployed as an AWS Lambda container; scores math-entry responses for the QTI mathEngine custom operator. | 12 | 1 | scoring, math, service |
| [e2e-tests](nodes/e2e-tests.md) | End-to-end test suites for AD. The active one is e2e-automation (Playwright BDD/Gherkin, run in GitHub Actions); ad-automation and ad-playwright-tests are older legacy suites. | 6 | 2 | tooling, testing |
| [ad-automation](nodes/ad-automation.md) | Original Playwright suite (API smoke + Explorer/player functional tests + qTest reporting). Hardcoded to coread-stg-dev and broken since its credential secret was removed; superseded by e2e-automation. | 3 | 10 | tooling, testing, legacy |
| [ad-playwright-tests](nodes/ad-playwright-tests.md) | Small Aug-2026 Playwright prototype (login, create form, create bar-chart item) against the Abigail authoring host. No CI; overlaps with e2e-automation, which replaced it. | 2 | 2 | tooling, testing, legacy |

## interface (26)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [delivery-api](nodes/delivery-api.md) | /api/delivery - host-facing session registration/reporting endpoints (OAuth + Delivery permission) and player-facing launch/state/response endpoints (player launch JWT). | 64 | 9 | delivery, api |
| [items-api](nodes/items-api.md) | /api/data item endpoints - list/query, save, versions and pub_state, clone/copy, bulk ops, metadata & standards CSV, history, locks, answer keys, generic scoring and item test cases. | 43 | 7 | content, api |
| [forms-api](nodes/forms-api.md) | /api/data form endpoints — form CRUD/list (v1, v2, light), preview, versions and pub_state, history, clone, delete, test map, derived-scoring test, setting profiles, reviewers, print pages, form metadata/standards CSV. | 42 | 8 | forms, api |
| [admin-api](nodes/admin-api.md) | /api/admin — internal operator API (admin-issuer JWT only) for accounts, credentials+permissions, banks/bank states, account-bank links, callback subscriptions, callback credentials and feature flags. | 37 | 8 | accounts, admin |
| [auth-api](nodes/auth-api.md) | Authentication endpoints on the base API — OAuth2 client-credentials token, claims echo, CloudFront signed cookies, JWKS — plus the auth middlewares every other API group mounts. | 30 | 2 | accounts, auth |
| [stimuli-api](nodes/stimuli-api.md) | /api/data shared-stimulus and resource endpoints - list/query, save, clone, delete, history, locks, metadata CSV, bulk styles/status/AI translation; resources CRUD and clone. | 29 | 5 | content, api |
| [human-scoring-api](nodes/human-scoring-api.md) | /api/scoring — list human-scorable items/responses, save human trait scores, enqueue session rescoring, and the unauthenticated OSCAR score callback. | 25 | 4 | scoring, human-scoring, api |
| [banks-api](nodes/banks-api.md) | /api/data bank endpoints - list/get/save/delete banks, workflow states, next item/stimulus identifiers (plus bank secrets, analytics and setting-profile routes owned by other modules). | 23 | 5 | content, api |
| [player-ui](nodes/player-ui.md) | Host contract and screens of the <ad-test-player> custom element — exposed methods (init/destroy/getState/setState/getADGlobalState/followAlongNavigationCommand), DOM events to the host, and the test-taker screens and toolbar tools. | 22 | 3 | delivery, frontend |
| [qti-packaging-api](nodes/qti-packaging-api.md) | /api/data/banks/:bankID/qti/* — async QTI content-package import (upload, start) and export jobs, plus job progress. | 20 | 5 | content, qti |
| [stats-api](nodes/stats-api.md) | /api/data item-statistics endpoints - historical and scoring stat sets (CRUD, CSV upload, bulk, v2/batch query, templates, generate-from-form), legacy /statistics routes, and the bank analytics overview. | 20 | 11 | stats |
| [ad-authoring-ui](nodes/ad-authoring-ui.md) | Host-embedding contract of ad-authoring.js — custom elements (ad-item-editor, ad-stimulus-editor, ad-resource-editor, ad-media-editor, ad-item-test-cases, ad-standards-picker, ad-media-picker, ad-form-editor), their init(config) shape, feature grants, host callbacks, methods and DOM events. | 18 | 13 | content, authoring, frontend, ui-contract |
| [media-api](nodes/media-api.md) | /api/data media endpoints (media rows + S3 upload, presigned get, tags, delete) and raw bank file upload/delete to the public S3 bucket. | 18 | 2 | content, api |
| [ad-cat-api](nodes/ad-cat-api.md) | REST API of the Java ad-cat service under /cat — create/get CAT sections from psychometric input files, create CAT sessions, submit scores for next items/ability estimate, force-complete, health. | 16 | 1 | cat, java, api |
| [ai-api](nodes/ai-api.md) | /api/data AI endpoints — generate QTI interaction snippets from standards, translate an item or stimulus into a new cloned translation, list translation languages. | 16 | 3 | ai |
| [jobs-api](nodes/jobs-api.md) | /api/jobs - list, get and "delete" (clean up) the caller account's async job-history records; jobs are created by the operations that start them, not here. | 15 | 1 | platform, api |
| [standards-api](nodes/standards-api.md) | /api/data/standards read endpoints - navigate the global standards tree, bank-assigned roots, item counts, peers (live Academic Benchmarks lookup) and search by number. | 15 | 1 | content, api |
| [test-maps-api](nodes/test-maps-api.md) | /api/data endpoints for battery STMs (CRUD + scoring preview) and the form SID test-map CSV export. | 13 | 5 | scoring, battery, api |
| [oscar-api](nodes/oscar-api.md) | /api/data external scoring-service config endpoints - OSCAR manifest/item/rubric proxies for authoring item-to-OSCAR mappings, plus the MetaMetrics credential test. | 12 | 2 | scoring, integration |
| [qti-item-components-ui](nodes/qti-item-components-ui.md) | Custom-element contract of qti-item-components-v1.0.0.js. It lists the tags, attributes, JS methods and DOM events that the player, authoring preview and print pages use to render QTI items and to save and restore their state. | 12 | 3 | delivery, authoring, frontend, qti |
| [xprt-api](nodes/xprt-api.md) | /api/data/xprt/* — start and track XPRT print-PDF jobs for items, stimuli and forms, fetch or invalidate the cached PDF, plus legacy UI-driven upload endpoints. | 11 | 1 | print |
| [pymathengine-api](nodes/pymathengine-api.md) | pymathengine HTTP endpoints (Flask, deployed as AWS Lambda) — POST / or /math with {given, options} returns whether a math answer matches; adam_ad calls it via MATH_SCORER_URL. | 10 | 1 | scoring, math, api |
| [explorer-ui](nodes/explorer-ui.md) | Screens of the internal AD Explorer SPA (/explorer/#/...), each with the AD API routes it calls. | 8 | 7 | ui, internal |
| [labels-api](nodes/labels-api.md) | Label bundle endpoints - Data API list/save/delete/validate per bank, and the player-facing delivery route that fetches a bundle by language. | 8 | 2 | delivery, content, api |
| [ab-cli](nodes/ab-cli.md) | Node CLI (ab-download) that lists Academic Benchmarks authorities and downloads one authority's standards hierarchy as a CSV ready to import into the AD standards table. | 7 | 2 | tooling, standards |
| [qti-scoring-api](nodes/qti-scoring-api.md) | scoring-api HTTP surface — POST /score_qti_item scores one QTI item response statelessly; GET /health. | 6 | 2 | scoring, api |

## integration (13)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [host-callback](nodes/host-callback.md) | Outbound JSON webhooks AD POSTs to host applications (session scored, battery attempt scored, content created/updated/deleted), resolved from the session's callback_url or the account's callback subscriptions, SSRF-guarded and optionally authenticated per URL. | 47 | 2 | delivery, integration |
| [mre](nodes/mre.md) | Pearson Math Response Engine — remote stateless math scoring service called for QTI custom operator class pearson.mre. | 19 | 0 | scoring, math, external |
| [new-relic](nodes/new-relic.md) | New Relic APM (Go agent v3 via nrgin, bun query hook, AWS SDK middleware, async-task helpers) plus browser-agent keys handed to the player. | 12 | 0 | platform, observability |
| [oscar](nodes/oscar.md) | OSCAR - Pearson's external constructed-response (human/AI) scoring platform; AD sends responses to it and receives scores on an unauthenticated callback. | 12 | 1 | scoring, integration |
| [academic-benchmarks](nodes/academic-benchmarks.md) | Academic Benchmarks (Certica ABConnect REST v4.1) standards API - source of the standards tree (offline loader) and live peer-standard lookups. | 11 | 0 | content, external |
| [rtpaas](nodes/rtpaas.md) | Pearson RTPaaS remote test proctoring - a JS bundle the player loads (URL from RTPAAS_JS_URL via GET /keys) that talks to proctors over Ably using a token signed by adam_ad. | 11 | 2 | delivery, integration, proctoring |
| [xprt](nodes/xprt.md) | Pearson XPRT print-rendering service that turns an AD QTI content package (item, stimulus or form) into a paper/print PDF written back to AD's internal S3 bucket. | 11 | 1 | integration, print |
| [metametrics](nodes/metametrics.md) | MetaMetrics Scoring Service - converts a partner scale score + SEM into a Lexile/Quantile ability measure. | 9 | 1 | scoring, integration |
| [texthelp-speechstream](nodes/texthelp-speechstream.md) | TextHelp SpeechStream toolbar (toolbar.speechstream.net, global window.speechstream) providing text-to-speech, dictionary and word prediction in the player and TTS in the authoring editors. | 9 | 0 | external, tts, accessibility |
| [desmos](nodes/desmos.md) | Desmos graphing/scientific calculator embedded by the player; AD only hands the player its Desmos API key via GET /api/delivery/keys. | 7 | 1 | delivery, integration |
| [ably](nodes/ably.md) | Ably realtime messaging used by RTPaaS remote proctoring; adam_ad signs short-lived Ably token requests for the player scoped to the candidate's RTPaaS channels. | 6 | 1 | delivery, integration, proctoring |
| [aws-bedrock-claude](nodes/aws-bedrock-claude.md) | Anthropic Claude Sonnet 4.6 invoked through AWS Bedrock Runtime (us-east-1) for AI interaction generation and translation. | 5 | 0 | ai, aws |
| [testnav](nodes/testnav.md) | Pearson TestNav secure-browser app API (window.TestNavApp.Api) used by the player for client context, volume and zoom when running inside TestNav. | 4 | 0 | delivery, frontend |

## datastore (5)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [postgres-main](nodes/postgres-main.md) | The adam_ad PostgreSQL database — writer pool database.DB, read-replica pool database.RO_DB and a migrate DSN — accessed through uptrace/bun, schema managed by golang-migrate. | 62 | 0 | platform, datastore |
| [s3-buckets](nodes/s3-buckets.md) | AD's three S3 buckets (internal, public content, student uploads) plus CloudFront distributions, accessed via the src/s3 helpers; content is served via CloudFront with signed cookies. | 30 | 0 | platform, datastore, aws |
| [sqs-queues](nodes/sqs-queues.md) | Two AWS SQS queues used by adam_ad - the save-off/scoring queue (COREAD_SQS_URL, bare session-id messages) and the batch queue (BATCH_SQS_URL, JSON actionType messages for bulk AI translation). | 17 | 0 | platform, delivery |
| [in-memory-cache](nodes/in-memory-cache.md) | Process-local caches in adam_ad (no Redis) - form-driver form cache, delivery item cache, feature-flag cache and save-off form caches - all cleared wholesale on a timer. | 14 | 0 | delivery, platform |
| [ad-cat-storage](nodes/ad-cat-storage.md) | ad-cat's own persistence — S3 objects for CAT sections and a pluggable key-value store (DynamoDB, ElastiCache Redis, S3 or none) for serialized CAT student/session state. | 6 | 0 | cat, java, storage |

## event (8)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [session-saveoff-requested](nodes/session-saveoff-requested.md) | SQS message on the save-off/scoring queue (COREAD_SQS_URL) whose body is a bare session UUID, asking the async save-off consumer to (re)score that session and notify the host. | 18 | 1 | delivery, scoring, async |
| [session-scored-callback](nodes/session-scored-callback.md) | Host webhook sent after every save-off of a submitted session - entity_type SESSION with entity_status SCORE_COMPLETE or SCORE_PENDING. | 9 | 1 | delivery, callback |
| [content-changed-callback](nodes/content-changed-callback.md) | Host webhook for authoring changes - entity_type ITEM, STIMULUS, FORM, MEDIA or BANK with entity_status CREATED, UPDATED or DELETED, sent to authoring subscribers of every account linked to the bank. | 8 | 5 | authoring, callback |
| [cat-session-out-of-sync-alert-job](nodes/cat-session-out-of-sync-alert-job.md) | Weekday cron (09:10-19:10 US Eastern, every 2 h) that counts adaptive sessions whose current_item no longer matches the current CAT slot's item and logs a warning for alerting, gated by a feature flag. | 7 | 3 | cat, cron, observability |
| [battery-attempt-scored-callback](nodes/battery-attempt-scored-callback.md) | Host webhook sent after a battery attempt is re-evaluated during save-off - entity_type BATTERY_ATTEMPT, strict mode only on SCORE_COMPLETE, non_strict on every evaluation. | 6 | 2 | scoring, callback, battery |
| [ai-translation-requested](nodes/ai-translation-requested.md) | JSON SQS message on the batch queue (BATCH_SQS_URL) asking the bulk consumer to AI-translate one item or stimulus into a language. | 5 | 2 | ai, async |
| [cat-out-of-order-alert-job](nodes/cat-out-of-order-alert-job.md) | Weekday cron (09-19 US Eastern, every 2 h) that counts CAT sessions whose adaptive slots were answered out of order and logs a warning for alerting, gated by a feature flag. | 5 | 1 | cat, cron, observability |
| [job-history-cleanup-job](nodes/job-history-cleanup-job.md) | gocron job every 10 minutes that removes leftover temp/S3 files of finished QTI import/export and Navvy report jobs and soft-deletes their job-history rows. | 3 | 1 | platform, cron |

## config (8)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [feature-flags](nodes/feature-flags.md) | Catalogue of every DB feature-flag key adam_ad reads via FeatureFlagService (key, bool/config, code default, where read, effect). | 24 | 0 | platform, config |
| [core-env-config](nodes/core-env-config.md) | Core adam_ad env vars (app/runtime, Postgres, JWT/auth, admin seed) read once at startup by options.EvalEnv, plus an index of every other env var and its owning config node. | 23 | 0 | platform, config |
| [callback-config](nodes/callback-config.md) | Env vars governing outbound host callbacks - optional destination host allowlist, http opt-in (internal-network guard always on), and the AES key that seals stored callback auth tokens. | 13 | 0 | delivery, config, security, callbacks |
| [aws-config](nodes/aws-config.md) | AWS-related env vars (region, S3 bucket names, CloudFront domains and cookie-signing key, SQS queue URLs, LocalStack switches) and the shared awsconfig.Load SDK loader. | 10 | 0 | platform, config, aws |
| [new-relic-config](nodes/new-relic-config.md) | NEW_RELIC_* env vars that enable the Go APM agent, DB/AWS segment instrumentation, log forwarding and the player's browser agent. | 6 | 0 | platform, config, observability |
| [ad-cat-config](nodes/ad-cat-config.md) | Environment variables of the Java ad-cat service (S3 bucket/folder, section cache, session-state storage backend) plus confd-rendered ops config. | 5 | 0 | cat, java, config |
| [math-scoring-config](nodes/math-scoring-config.md) | Env vars for remote math scoring used by QTI custom operators — MATH_SCORER_URL (pymathengine) and MRE_HOST/MRE_CLIENT_ID/MRE_SECRET. | 5 | 0 | config, scoring, math |
| [xprt-config](nodes/xprt-config.md) | Env vars XPRT_URL and XPRT_KEY — base URL of the XPRT print service and the HS256 secret AD signs XPRT job JWTs with. | 5 | 0 | config, print |

## flow (17)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [score-session](nodes/score-session.md) | Asynchronous save-off - rescoring every response of a submitted session, computing STM outcomes, and notifying the host; re-entered by every rescore path. | 11 | 8 | scoring, delivery |
| [take-test](nodes/take-test.md) | A host registers a session, the student takes the test in adam-player, submits, and AD scores it asynchronously and calls the host back. | 8 | 11 | delivery |
| [deliver-adaptive-section](nodes/deliver-adaptive-section.md) | Computer-adaptive delivery - ad-cat picks the next items from a CAT section's pool as responses arrive, AD persists slots and theta. | 5 | 6 | cat, delivery |
| [save-form](nodes/save-form.md) | Authoring a form - PUT /forms validates and writes form, sections, items, STM, OSCAR mappings and CAT sections in one transaction, then versions/publishes it. | 5 | 9 | forms |
| [evaluate-battery](nodes/evaluate-battery.md) | When a session in a battery is scored, AD re-evaluates the battery attempt across its units and sends a BATTERY_ATTEMPT callback. | 4 | 6 | scoring |
| [score-with-oscar](nodes/score-with-oscar.md) | Constructed responses mapped to OSCAR are sent out during save-off; OSCAR posts scores back to /api/scoring/oscar/callback and the session is rescored. | 3 | 7 | scoring |
| [authenticate-api-client](nodes/authenticate-api-client.md) | A host exchanges its credential for an AD JWT and every API call re-checks the credential's permissions per route. | 2 | 4 | accounts |
| [author-item](nodes/author-item.md) | Authoring an item in the embedded ad-item-editor - host inits the editor, author edits QTI client-side, host saves via items-api, preview scores via generic_score. | 2 | 7 | content |
| [export-qti-package](nodes/export-qti-package.md) | Exporting items, stimuli or forms as a QTI zip - async job writes the package to the public bucket and records its URL on the job. | 2 | 5 | content |
| [human-score-response](nodes/human-score-response.md) | A scorer (host app) lists human-scorable responses, saves trait scores, and the session is re-queued for save-off. | 2 | 5 | scoring |
| [import-qti-package](nodes/import-qti-package.md) | Uploading an IMS/QTI content package - dry-run upload creates a job, then an async import writes media, stimuli, items (+test cases) and forms. | 2 | 5 | content |
| [notify-host-of-content-change](nodes/notify-host-of-content-change.md) | When items, stimuli or forms are created/updated, AD posts a content-changed callback to the authoring subscriptions of every account linked to the bank. | 2 | 4 | delivery, content |
| [onboard-tenant](nodes/onboard-tenant.md) | An AD operator sets up a host app in the admin UI - account, API credential with per-bank permissions, bank links, callback subscriptions and callback credentials. | 2 | 6 | accounts |
| [print-with-xprt](nodes/print-with-xprt.md) | Generating a print PDF of an item, passage or form through the external XPRT renderer, with the PDF cached until the content changes. | 2 | 6 | forms, integration |
| [translate-item-with-ai](nodes/translate-item-with-ai.md) | AI translation of an item and its stimuli via Claude on Bedrock, applying the bank glossary and saving a linked translated clone. | 2 | 6 | ai |
| [upload-stat-set](nodes/upload-stat-set.md) | Loading psychometric item statistics - create a historical or scoring stat set, upload a CSV (or bulk JSON), then use it for blueprinting or IRT scoring. | 2 | 6 | stats |
| [score-qti-item-stateless](nodes/score-qti-item-stateless.md) | The standalone scoring-api scores one QTI item response without a database, reusing adam_ad's QTI engine. | 0 | 3 | scoring |

## concept (26)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [bank-workflow-state](nodes/bank-workflow-state.md) | Authoring workflow status (bank-defined states with allowed transitions) is separate from the D/P/R publication state. | 1 | 3 | glossary |
| [bank-scope](nodes/bank-scope.md) | A bank is both the content container (items, stimuli, forms) and the unit of API permission. | 0 | 2 | glossary |
| [battery](nodes/battery.md) | A battery scores several forms (units) together; a battery attempt is the caller-supplied virtual session that aggregates them. | 0 | 2 | glossary |
| [custom-operator](nodes/custom-operator.md) | A qti-custom-operator whose class selects an AD/Pearson scorer (MRE, math engine, PCI, mapPerGap, scoreByValue). | 0 | 3 | glossary |
| [explorer](nodes/explorer.md) | The internal /explorer SPA used by the AD team - not a customer UI. | 0 | 1 | glossary |
| [feature-grant](nodes/feature-grant.md) | Embedded-editor features are granted off/read/write by the host per user; these are not the DB feature flags. | 0 | 2 | glossary |
| [follow-along-navigation](nodes/follow-along-navigation.md) | A mode where the proctor drives which item every student sees; candidate navigation is removed. | 0 | 2 | glossary |
| [form-driver](nodes/form-driver.md) | The server-side navigator that applies each response and decides the next item - linear or adaptive. | 0 | 2 | glossary |
| [form-family](nodes/form-family.md) | All version rows of an item, stimulus or form that share (bank_id, identifier); flags mark the head and the live version. | 0 | 3 | glossary |
| [label-override](nodes/label-override.md) | Bank-level label bundles localise player strings per language; form-level label_override overrides individual strings. | 0 | 2 | glossary |
| [markoff](nodes/markoff.md) | Oral-reading fluency scoring - words marked wrong by the scorer, giving words correct per minute. | 0 | 2 | glossary |
| [objective-outcome](nodes/objective-outcome.md) | An objective is a scoring rule in an STM; an outcome is the score row it produces for a session. | 0 | 2 | glossary |
| [passage](nodes/passage.md) | A passage and a stimulus are the same thing (shared-stimulus); an exhibit is that stimulus seen from inside an item. | 0 | 1 | glossary |
| [pci](nodes/pci.md) | A JS-module interaction (used for simulations) run in a sandboxed iframe and scored by the PCI scorer. | 0 | 2 | glossary |
| [pnp](nodes/pnp.md) | Per-session accessibility/accommodation settings passed by the host at registration. | 0 | 2 | glossary |
| [resource-term](nodes/resource-term.md) | A resource (resources table) is section-intro/instructions content; an item with is_resource=true is a non-scorable item - different things. | 0 | 3 | glossary |
| [review-range](nodes/review-range.md) | In adaptive sections, a span of slots within which the student may navigate back. | 0 | 2 | glossary |
| [rubric-trait](nodes/rubric-trait.md) | A rubric dimension on a human-scored item; scores per trait are stored per response. | 0 | 2 | glossary |
| [save-off](nodes/save-off.md) | The asynchronous rescoring of a submitted session triggered by an SQS message; every score change goes through it. | 0 | 2 | glossary |
| [scoring-status](nodes/scoring-status.md) | Per-item flag saying whether an item counts toward the score; only OP items are scored. | 0 | 2 | glossary |
| [scoring-test-map](nodes/scoring-test-map.md) | The per-form scoring definition - objectives that turn item scores into outcomes; distinct from the "SID test map" CSV export. | 0 | 3 | glossary |
| [session-state](nodes/session-state.md) | The lifecycle state of a session - NOT_STARTED, IN_PROGRESS, PAUSED, PAUSED_SECTION, BREACHED, RESEAT, SUBMITTED - separate from score_status and from the player UI globalState. | 0 | 2 | glossary |
| [stat-set](nodes/stat-set.md) | Historical stat sets hold item statistics for blueprinting; scoring stat sets hold IRT parameters used to score. | 0 | 2 | glossary |
| [tenant-account](nodes/tenant-account.md) | In AD an "account" is a host application tenant (Navvy, Abigail...), never a person. | 0 | 2 | glossary |
| [theta](nodes/theta.md) | The IRT ability estimate and its standard error, produced by ad-cat in adaptive sections and by the IRT objective in scoring. | 0 | 2 | glossary |
| [token-issuer](nodes/token-issuer.md) | AD issues several HS256 JWT kinds distinguished by issuer, all signed with JWT_SECRET. | 0 | 3 | glossary |

## capability (30)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [computer-adaptive-testing](nodes/computer-adaptive-testing.md) | Adaptive sections whose next items are chosen by the ad-cat engine from an item pool based on the student's estimated ability. | 1 | 7 | capability |
| [oscar-response-scoring](nodes/oscar-response-scoring.md) | Sending constructed responses to Pearson OSCAR for AI/human scoring and ingesting the scores by callback. | 1 | 3 | capability |
| [proctor-controls](nodes/proctor-controls.md) | Hosts and proctors pause, breach, reseat, jump sections, release sections, follow-along navigate and force-complete sessions. | 1 | 3 | capability |
| [psychometric-item-stats](nodes/psychometric-item-stats.md) | Uploading psychometric statistics per item for blueprinting and IRT-based scoring. | 1 | 3 | capability |
| [accessibility-accommodations](nodes/accessibility-accommodations.md) | Per-student accommodations (PNP) and test tools: text-to-speech, magnifier, line reader, contrast, calculators, extra time, ASL and more. | 0 | 4 | capability |
| [ad-explorer](nodes/ad-explorer.md) | Internal web app for browsing content, launching test sessions, importing/exporting and managing stat sets. | 0 | 3 | capability |
| [ai-question-generation](nodes/ai-question-generation.md) | Generating draft interactions from standards, passages and bank style guides with Claude on Bedrock. | 0 | 3 | capability |
| [ai-translation](nodes/ai-translation.md) | Translating items and passages into other languages with Claude, applying a per-bank glossary. | 0 | 4 | capability |
| [automatic-scoring](nodes/automatic-scoring.md) | Machine scoring of every response from the item's QTI response processing, including math equivalence (MRE, math engine) and simulation scorers. | 0 | 6 | capability |
| [battery-scoring](nodes/battery-scoring.md) | Combining several tests (units) into one composite battery score with its own callback. | 0 | 3 | capability |
| [check-answer-feedback](nodes/check-answer-feedback.md) | Students check an answer during the test and get immediate right/wrong feedback, with limited attempts. | 0 | 4 | capability |
| [derived-scoring](nodes/derived-scoring.md) | Turning item scores into test results: percent correct, scale scores, IRT theta, reporting categories and standards mastery. | 0 | 4 | capability |
| [embedded-item-authoring](nodes/embedded-item-authoring.md) | Host apps embed AD editors to write QTI 3.0 questions with 30+ interaction types, scoring rules, metadata and standards. | 0 | 7 | capability |
| [host-webhooks](nodes/host-webhooks.md) | AD notifies host apps by callback when sessions are scored, batteries evaluated, or content changes. | 0 | 6 | capability |
| [human-scoring](nodes/human-scoring.md) | Teachers or scorers score open responses by rubric trait, and the session is rescored. | 0 | 3 | capability |
| [interaction-library](nodes/interaction-library.md) | The set of QTI 3.0 question types AD can render and score, shared by the player and the authoring preview. | 0 | 5 | capability |
| [lexile-quantile-measures](nodes/lexile-quantile-measures.md) | Computing MetaMetrics Lexile/Quantile measures as STM objectives. | 0 | 3 | capability |
| [online-test-delivery](nodes/online-test-delivery.md) | Students take tests in an embeddable web player while AD tracks sessions, responses, timing and navigation. | 0 | 7 | capability |
| [passage-and-resource-authoring](nodes/passage-and-resource-authoring.md) | Authoring shared passages (stimuli) used by several items, and section-instruction resources. | 0 | 4 | capability |
| [practice-and-preview](nodes/practice-and-preview.md) | Unscored practice runs with a score screen and author previews of a form, without creating real sessions. | 0 | 4 | capability |
| [print-pdfs](nodes/print-pdfs.md) | Generating printable PDFs of items, passages and forms through XPRT, plus print pages for review. | 0 | 6 | capability |
| [qti-import-export](nodes/qti-import-export.md) | Moving items, passages, media and forms in and out of AD as QTI 3.0 content packages. | 0 | 4 | capability |
| [remote-proctoring](nodes/remote-proctoring.md) | Online proctoring through Pearson RTPaaS, loaded by the player with Ably realtime tokens. | 0 | 5 | capability |
| [runtime-feature-flags](nodes/runtime-feature-flags.md) | Database-backed flags that switch server behaviour on or off without a deploy. | 0 | 5 | capability |
| [scoring-regression-tests](nodes/scoring-regression-tests.md) | Stored responses with expected scores that check an item's scoring still works. | 0 | 4 | capability |
| [shared-delivery-settings](nodes/shared-delivery-settings.md) | Reusable bundles of player settings (tools, navigation, labels, timers) shared by many forms. | 0 | 3 | capability |
| [standards-alignment](nodes/standards-alignment.md) | Aligning items and rubric traits to academic standards sourced from Academic Benchmarks. | 0 | 3 | capability |
| [tenant-management](nodes/tenant-management.md) | Operators manage host-app accounts, API credentials, per-bank permissions and callback setup in the admin console. | 0 | 5 | capability |
| [test-assembly-and-publishing](nodes/test-assembly-and-publishing.md) | Building test forms from sections and items, versioning them and publishing them for delivery. | 0 | 4 | capability |
| [version-history](nodes/version-history.md) | Item, passage and form history with diff and revert. | 0 | 6 | capability |