{ "surface": "alpha", "deliverable": "architecture", "title": "TimeBack Platform QTI Alpha Architecture", "generatedAt": "2026-05-20T22:50:54Z", "upstream": { "oneEdTechArchitectureUrl": "https://platform3-avjryotuw-andymontgomery-9773s-projects.vercel.app", "oneEdTechDataDictionaryUrl": "https://platform3-198nmblg3-andymontgomery-9773s-projects.vercel.app", "oneEdTechCustomerWebsiteUrl": "https://platform3-fscem3woq-andymontgomery-9773s-projects.vercel.app", "oneEdTechImplementationPath": "/Users/andymontgomery/projects/platform3/loop/qti/artifacts/1edtech/implementation", "oneEdTechSurfaceQcUrl": "https://platform3-a3ocfthbe-andymontgomery-9773s-projects.vercel.app" }, "architectureRule": "Alpha is a teacher, student, parent, and LLM-facing API and documentation layer over the approved 1EdTech qti.* persistence truth. It may cut, restrict, rename, or extend the surface, but it must not fork the database, weaken QTI validation, alter canonical XML, or hide provenance.", "alphaItIds": [ "alpha-itd-001-shared-qti-persistence", "alpha-itd-002-school-vocabulary-layer", "alpha-itd-003-cut-raw-qti-internals", "alpha-itd-004-restricted-package-import", "alpha-itd-005-content-catalog-read-model", "alpha-itd-006-lossless-authoring-commands", "alpha-itd-007-activity-delivery-language", "alpha-itd-008-declaration-checked-answers", "alpha-itd-009-results-and-grading-explanations", "alpha-itd-010-student-ref-privacy-language", "alpha-itd-011-cut-public-conformance-runner", "alpha-itd-012-read-only-trust-status", "alpha-itd-013-plain-language-problems", "alpha-itd-014-alpha-provenance-requirements" ], "alphaItDs": [ { "id": "alpha-itd-001-shared-qti-persistence", "title": "Shared QTI Persistence, Alpha Facade", "changeType": "restrict", "audienceConstraint": "Students, parents, teachers, and app-builder LLMs need plain objects, but administrators and support staff still need one durable source of truth when results or content are disputed.", "decision": "Restrict Alpha to the approved shared qti.* persistence model. Alpha may expose friendlier resource names and derived read models, but writes ultimately create or read the approved 1EdTech tables and fields.", "upstreamItDs": [ "itd-003-shared-supabase-postgresql", "itd-004-xml-authority", "itd-007-provenance-labels", "itd-023-hosted-docs" ], "affectedTables": [ "qti.tenant", "qti.content_package", "qti.package_resource", "qti.package_file", "qti.artifact", "qti.artifact_version", "qti.component", "qti.variable_declaration", "qti.processing_rule", "qti.delivery_session", "qti.attempt", "qti.conformance_run", "qti.conformance_assertion" ], "downstreamRules": [ "The Alpha data dictionary must map every Alpha object or field to an approved 1EdTech table.field or to a declared derived field with this ITD as provenance.", "No alpha.qti_* persistence tables are introduced by this architecture attempt.", "Alpha implementation must call the approved 1EdTech repository or preserve an equivalent contract over the same qti.* tables." ] }, { "id": "alpha-itd-002-school-vocabulary-layer", "title": "School Vocabulary Layer", "changeType": "rename", "audienceConstraint": "The Alpha audience thinks in questions, tests, passages, answers, scores, feedback, activities, and results, not artifacts, candidates, response declarations, outcome variables, or processing traces.", "decision": "Rename external Alpha resources and documentation labels into familiar school terms while keeping canonical 1EdTech field names visible in provenance, advanced details, and implementation mappings.", "upstreamItDs": [ "itd-006-json-projections", "itd-011-artifact-versioning", "itd-013-variable-projection", "itd-014-processing-projection", "itd-015-delivery-session", "itd-016-attempt-trace" ], "affectedTables": [ "qti.artifact", "qti.artifact_version", "qti.variable_declaration", "qti.processing_rule", "qti.delivery_session", "qti.attempt" ], "renameMap": { "tenant": "school or workspace", "content_package": "assessment package", "artifact": "content item", "artifact_kind:item": "question", "artifact_kind:test": "test", "artifact_kind:section": "test section", "artifact_kind:stimulus": "passage or shared material", "artifact_version": "content version", "delivery_json": "student view", "authoring_json": "editing draft", "delivery_session": "activity", "candidate_ref": "studentRef", "attempt": "answer submission", "response_state": "answers", "outcome_state": "results", "processing_trace": "grading explanation" }, "downstreamRules": [ "Alpha docs must lead with school terms and show canonical QTI names in a provenance drawer, table column, or advanced note.", "Alpha API operation names may use school vocabulary, but response schemas must carry stable upstream links.", "A rename must not change canonical XML, QTI identifiers, or qti.* column names." ] }, { "id": "alpha-itd-003-cut-raw-qti-internals", "title": "Cut Raw QTI Internals From Public Alpha", "changeType": "cut", "audienceConstraint": "Learners, families, and teachers cannot safely work from package bytes, component rows, processing-rule trees, object graphs, or raw conformance assertions as their normal entry point.", "decision": "Cut raw package-file, component-tree, variable-declaration, processing-rule, object-graph, and assertion-row endpoints from the public Alpha surface. These remain documented as upstream provenance and are still available to internal 1EdTech tooling.", "upstreamItDs": [ "itd-005-relational-projection", "itd-009-package-ingest", "itd-013-variable-projection", "itd-014-processing-projection", "itd-017-conformance-evidence", "itd-018-api-boundary" ], "cutPublicObjects": [ "qti.package_file.content_bytes", "qti.artifact_version.object_graph", "qti.component", "qti.variable_declaration as a standalone public resource", "qti.processing_rule as a standalone public resource", "qti.conformance_assertion as a standalone public resource" ], "downstreamRules": [ "Alpha data dictionary must label these objects as backstage 1EdTech-backed internals, not missing data.", "Alpha customer website must link advanced users back to the 1EdTech data dictionary for raw internals.", "Implementation must not expose a generic row browser over these tables through Alpha." ] }, { "id": "alpha-itd-004-restricted-package-import", "title": "Restricted Assessment Package Import", "changeType": "restrict", "audienceConstraint": "Teachers and app-builder LLMs need a dependable import command, not a standards workbench with every possible XML entry path and profile switch exposed first.", "decision": "Restrict Alpha import to assessment-package upload with tenant authorization, idempotency, QTI 3.0 validation, package closure checks, and friendly import status. Alpha does not accept arbitrary database writes or unvalidated raw XML as content.", "upstreamItDs": [ "itd-001-source-bundle", "itd-004-xml-authority", "itd-009-package-ingest", "itd-010-idempotency", "itd-020-validation-policy" ], "mappedOneEdTechOperations": [ "ingestContentPackage" ], "alphaOperations": [ "importAssessmentPackage" ], "downstreamRules": [ "Alpha import responses must summarize package status, content created, and validation problems without requiring users to understand IMS manifest internals.", "Package bytes, hashes, resource identifiers, and validation diagnostics remain stored in qti.content_package, qti.package_resource, and qti.package_file.", "Unsupported or invalid QTI content fails with a plain-language problem that still links to the underlying validation source." ] }, { "id": "alpha-itd-005-content-catalog-read-model", "title": "Content Catalog Read Model", "changeType": "extend", "audienceConstraint": "Teachers, families, and app-builder LLMs need to find a question, test, passage, or version before they can deliver, inspect, edit, or explain it. The 1EdTech surface starts from exact artifact-version IDs.", "decision": "Extend Alpha with a content catalog read model over qti.artifact, qti.artifact_version, and selected qti.component values. The catalog lists content by school-friendly kind, title, language, latest version, package source, and safe summary metadata.", "upstreamItDs": [ "itd-005-relational-projection", "itd-006-json-projections", "itd-011-artifact-versioning", "itd-012-artifact-kind" ], "affectedTables": [ "qti.artifact", "qti.artifact_version", "qti.component", "qti.content_package" ], "alphaOperations": [ "listContent", "getContent" ], "downstreamRules": [ "Catalog fields are derived from approved 1EdTech data dictionary fields and must carry upstream qti.* source paths.", "Catalog summaries may not expose raw learner data, package bytes, auth metadata, or processing trace.", "Search/filter behavior must be deterministic from stored fields; relevance tuning may be added later only as a documented extension." ] }, { "id": "alpha-itd-006-lossless-authoring-commands", "title": "Lossless Authoring Commands", "changeType": "restrict", "audienceConstraint": "Teachers and LLMs can author with friendly draft language, but the platform cannot let friendly editing silently drop QTI fields needed for export, scoring, accessibility, or compliance.", "decision": "Restrict Alpha authoring to lossless editing-draft saves that create immutable content versions. Alpha may rename the workflow to drafts and versions, but it must preserve authoring_json lossiness none and If-Match concurrency.", "upstreamItDs": [ "itd-006-json-projections", "itd-011-artifact-versioning", "itd-020-validation-policy" ], "mappedOneEdTechOperations": [ "saveAuthoringJson", "exportXml" ], "alphaOperations": [ "saveContentDraft", "downloadQtiXml" ], "downstreamRules": [ "Alpha editing payloads must be marked as lossless before they can create qti.artifact_version rows.", "Alpha save commands must reject stale versions and missing preconditions instead of overwriting content in place.", "XML export remains available as an advanced portability command, but the ordinary authoring path uses draft/version language." ] }, { "id": "alpha-itd-007-activity-delivery-language", "title": "Activity Delivery Language", "changeType": "rename", "audienceConstraint": "Students and parents experience a learning activity or test session, not a delivery-session row with a delivery-json snapshot.", "decision": "Rename delivery-session workflows to activities and student views. Alpha activity creation still pins immutable content versions and snapshots the generated delivery projection exactly as the 1EdTech surface requires.", "upstreamItDs": [ "itd-006-json-projections", "itd-015-delivery-session", "itd-024-candidate-learner-data-privacy" ], "mappedOneEdTechOperations": [ "getDeliveryJson", "startDeliverySession" ], "alphaOperations": [ "getStudentView", "startActivity" ], "downstreamRules": [ "Activity responses must include the content version being delivered so families can understand why later edits do not change past sessions.", "The student view is generated from qti.artifact_version.delivery_json and must keep declared lossiness visible to app-builder LLMs.", "Activity status values may be displayed as classroom words, but stored lifecycle values remain qti.delivery_session.status." ] }, { "id": "alpha-itd-008-declaration-checked-answers", "title": "Declaration-Checked Answers", "changeType": "restrict", "audienceConstraint": "A student or teacher can provide answers, but cannot be expected to know QTI cardinality, base-type, response declaration identifiers, or variable shape errors.", "decision": "Restrict Alpha answer submission to declared answer slots generated from qti.variable_declaration. The implementation translates friendly answer payloads into QTI response variables only after cardinality and base-type validation.", "upstreamItDs": [ "itd-013-variable-projection", "itd-016-attempt-trace", "itd-020-validation-policy", "itd-021-runtime-profile" ], "mappedOneEdTechOperations": [ "submitAttempt" ], "alphaOperations": [ "submitAnswers" ], "affectedTables": [ "qti.variable_declaration", "qti.attempt" ], "downstreamRules": [ "Alpha answer schemas must be generated from the stored QTI declarations for the delivered content version.", "Invalid answer shape fails before processing and returns a plain-language problem with the canonical variable identifier available for support.", "Alpha must not silently coerce answers into a different QTI base type or cardinality." ] }, { "id": "alpha-itd-009-results-and-grading-explanations", "title": "Results And Grading Explanations", "changeType": "extend", "audienceConstraint": "Students and parents need to understand the score, feedback, and what happened in grading; raw outcome_state and processing_trace are too technical and can expose unnecessary implementation detail.", "decision": "Extend Alpha with result and grading-explanation read models derived from qti.attempt response_state, outcome_state, status, timestamps, and privacy-redacted processing_trace.", "upstreamItDs": [ "itd-016-attempt-trace", "itd-021-runtime-profile", "itd-024-candidate-learner-data-privacy" ], "alphaOperations": [ "getActivityResult" ], "affectedTables": [ "qti.attempt", "qti.delivery_session", "qti.artifact_version" ], "downstreamRules": [ "Result summaries must state the content version, submitted time, outcome variables used for scores, and whether scoring completed, failed, or was voided.", "Grading explanations are derived views, not a replacement for processing_trace; support and audit links must keep the upstream trace path.", "Explanations must redact learner PII, tokens, headers, IP addresses, raw PNP records, and direct identity fields." ] }, { "id": "alpha-itd-010-student-ref-privacy-language", "title": "StudentRef Privacy Language", "changeType": "rename", "audienceConstraint": "Parents and teachers understand student data, not candidate runtime data. At the same time, the platform must avoid direct student PII in QTI runtime records.", "decision": "Rename candidate_ref to studentRef on Alpha while preserving the 1EdTech privacy rule: the value is an opaque tenant-scoped pseudonymous UUID, not a name, email, SIS ID, JWT subject, or contact detail.", "upstreamItDs": [ "itd-008-tenant-boundary", "itd-019-security-boundary", "itd-024-candidate-learner-data-privacy" ], "mappedOneEdTechOperations": [ "startDeliverySession", "deleteCandidateRuntimeData" ], "alphaOperations": [ "startActivity", "deleteStudentTestData" ], "affectedFields": [ "qti.delivery_session.candidate_ref", "qti.attempt.response_state", "qti.attempt.template_state", "qti.attempt.outcome_state", "qti.attempt.processing_trace" ], "downstreamRules": [ "Alpha docs must say studentRef is not the student's legal identity.", "Alpha validation must reject direct PII in studentRef and sanitize Problem details.", "Deleting student test data deletes learner-runtime rows for the scoped pseudonymous reference and does not delete reusable content." ] }, { "id": "alpha-itd-011-cut-public-conformance-runner", "title": "Cut Public Conformance Runner", "changeType": "cut", "audienceConstraint": "Teachers, students, parents, and normal app-builder LLMs should not trigger standards conformance jobs while trying to teach, learn, or inspect results.", "decision": "Cut POST /qti/conformance-runs from the public Alpha API. The runner remains part of the approved 1EdTech implementation and release process.", "upstreamItDs": [ "itd-017-conformance-evidence", "itd-018-api-boundary", "itd-019-security-boundary" ], "cutOperations": [ "runConformance" ], "downstreamRules": [ "Alpha customer website must not present conformance execution as a normal user action.", "Operational or compliance agents that need to run conformance must use the 1EdTech surface or internal release tooling.", "Alpha implementation must not route public Alpha tokens to the conformance runner." ] }, { "id": "alpha-itd-012-read-only-trust-status", "title": "Read-Only QTI Trust Status", "changeType": "extend", "audienceConstraint": "Schools and app-builder LLMs still need to know whether the QTI engine is backed by current evidence, but they need an answer, not raw assertion tables.", "decision": "Extend Alpha with a read-only trust status derived from qti.conformance_run, qti.conformance_assertion, approved upstream URLs, and surface QC. It reports last run status, bundle hash, runner version, and documentation links without exposing mutable runner controls.", "upstreamItDs": [ "itd-017-conformance-evidence", "itd-023-hosted-docs" ], "alphaOperations": [ "getQtiTrustStatus" ], "affectedTables": [ "qti.conformance_run", "qti.conformance_assertion" ], "downstreamRules": [ "Trust status is read-only in Alpha and must link to the approved 1EdTech surface QC URL.", "A failed or stale conformance run must be visible; Alpha must not convert failure evidence into green copy.", "Raw assertion details remain an advanced 1EdTech/internal view unless a later Alpha ITD justifies a friendlier drilldown." ] }, { "id": "alpha-itd-013-plain-language-problems", "title": "Plain-Language Problems", "changeType": "rename", "audienceConstraint": "A teacher or parent can act on 'this answer has the wrong shape' or 'this package is missing a file' faster than on QTI schema, processing, or package-closure jargon.", "decision": "Rename externally visible Alpha validation and error messages into plain-language Problem responses while preserving HTTP status, stable problem type, invalid parameter paths, and upstream QTI/source trace links.", "upstreamItDs": [ "itd-018-api-boundary", "itd-019-security-boundary", "itd-020-validation-policy", "itd-024-candidate-learner-data-privacy" ], "downstreamRules": [ "Problem.detail must be safe for users and must not contain package bytes, tokens, headers, IP addresses, raw PNP records, or direct learner identity fields.", "Advanced problem metadata may include QTI identifiers, variable names, schema file names, and architecture/data-dictionary links.", "Alpha must not weaken rejection behavior by translating errors into warnings." ] }, { "id": "alpha-itd-014-alpha-provenance-requirements", "title": "Alpha Provenance Requirements", "changeType": "extend", "audienceConstraint": "LLMs and humans need the friendly Alpha layer to be trustworthy enough to build from without guessing where the underlying 1EdTech truth lives.", "decision": "Extend the data-dictionary and customer-website contract so every Alpha object, field, endpoint, status, enum, and behavior links to its Alpha ITD and to the approved 1EdTech table, field, operation, or ITD it depends on.", "upstreamItDs": [ "itd-007-provenance-labels", "itd-018-api-boundary", "itd-023-hosted-docs" ], "downstreamRules": [ "Alpha data dictionary entries must carry one of: 1EdTech pass-through, Alpha rename, Alpha restriction, Alpha cut, or Alpha extension.", "Alpha customer website examples must link back to the architecture ITD and data dictionary entry for every field or behavior they promise.", "If an Alpha value cannot be traced to approved 1EdTech truth or one of these Alpha ITDs, implementation must stop and recommend rollback to architecture." ] } ], "alphaOperations": { "importAssessmentPackage": { "kind": "restricted rename", "mapsTo": [ "ingestContentPackage" ], "itds": [ "alpha-itd-004-restricted-package-import", "alpha-itd-013-plain-language-problems" ] }, "listContent": { "kind": "extension", "mapsTo": [ "qti.artifact", "qti.artifact_version", "qti.component" ], "itds": [ "alpha-itd-005-content-catalog-read-model" ] }, "getContent": { "kind": "extension", "mapsTo": [ "qti.artifact", "qti.artifact_version" ], "itds": [ "alpha-itd-005-content-catalog-read-model" ] }, "getStudentView": { "kind": "rename", "mapsTo": [ "getDeliveryJson" ], "itds": [ "alpha-itd-007-activity-delivery-language" ] }, "saveContentDraft": { "kind": "restricted rename", "mapsTo": [ "saveAuthoringJson" ], "itds": [ "alpha-itd-006-lossless-authoring-commands" ] }, "downloadQtiXml": { "kind": "restricted rename", "mapsTo": [ "exportXml" ], "itds": [ "alpha-itd-006-lossless-authoring-commands" ] }, "startActivity": { "kind": "rename", "mapsTo": [ "startDeliverySession" ], "itds": [ "alpha-itd-007-activity-delivery-language", "alpha-itd-010-student-ref-privacy-language" ] }, "submitAnswers": { "kind": "restriction", "mapsTo": [ "submitAttempt" ], "itds": [ "alpha-itd-008-declaration-checked-answers" ] }, "getActivityResult": { "kind": "extension", "mapsTo": [ "qti.attempt", "qti.delivery_session", "qti.artifact_version" ], "itds": [ "alpha-itd-009-results-and-grading-explanations" ] }, "deleteStudentTestData": { "kind": "rename", "mapsTo": [ "deleteCandidateRuntimeData" ], "itds": [ "alpha-itd-010-student-ref-privacy-language" ] }, "getQtiTrustStatus": { "kind": "extension", "mapsTo": [ "qti.conformance_run", "qti.conformance_assertion", "1edtech/surface_qc" ], "itds": [ "alpha-itd-011-cut-public-conformance-runner", "alpha-itd-012-read-only-trust-status" ] } }, "cutFromPublicAlpha": [ "runConformance as a public mutation", "raw qti.package_file.content_bytes reads", "generic qti.component row reads", "generic qti.variable_declaration row reads", "generic qti.processing_rule row reads", "qti.artifact_version.object_graph reads", "generic qti.conformance_assertion row browsing" ], "alphaDataDictionaryLabels": [ "1EdTech pass-through", "Alpha rename", "Alpha restriction", "Alpha cut", "Alpha extension" ], "nonGoals": [ "No OneRoster identity, class roster, assignment, or gradebook model is invented in the QTI Alpha architecture.", "No Caliper event stream is invented in the QTI Alpha architecture.", "No new QTI XML semantics, root elements, response-processing behavior, or conformance profile is invented by Alpha.", "No direct learner PII is stored in qti.delivery_session.candidate_ref." ] }