Platform Architecture

QTI Inputs Promoted

QTI is the empirical input for this platform pass. The approved QTI artifacts are not copied wholesale; the cross-module patterns that held up under review are promoted, while QTI-specific standards content remains in qti.*.

Shared Model

The platform substrate is small on purpose. Module-specific standards data stays in each module schema. Cross-module tenant identity, idempotency, and audit move into platform.*.

Producer Surface Registry

Producer surfaces preserve upstream provenance and generation history while routing customer-facing answers through the normal Platform3 module model. They do not create a third consumer API surface and they do not replace Content, Results, Events, or Analytics.

HTTP Contract

The HTTP contract is intentionally conventional: typed success bodies, one Problem error shape, tenant-scoped auth, route-scoped CORS preflight, shared idempotency behavior, and optimistic concurrency for updates that can lose work.

{
  "type": "https://platform3-andymontgomery-9773s-projects.vercel.app/problems/validation-error",
  "title": "Validation failed",
  "status": 400,
  "code": "validation_error",
  "detail": "Safe caller-facing detail",
  "requestId": "req_...",
  "traceId": "trace_...",
  "fieldErrors": [
    {"field": "studentRef", "message": "Use an opaque UUID"}
  ]
}

{
  "iss": "timeback",
  "sub": "timeback:student:person_student_001",
  "tenant_id": "tenant uuid for tenant routes",
  "role": "student",
  "roles": ["student"],
  "scopes": ["people_orgs:read", "content:read", "qti:attempt", "events:write"],
  "personId": "person_student_001",
  "studentId": "person_student_001",
  "exp": 1780000000
}

API Decision Axis Ledger

The loop requires every API surface architecture to pin these standard axes before downstream deliverables build on it. Each row is a SHIP or DEFER decision with alternatives, tradeoffs, downstream obligations, and a concrete re-open trigger for rejected or deferred options.

ITD Index

Every later platform data dictionary entry, customer website section, implementation helper, and module architecture may link directly to these anchors.

Important Technical Decisions

Each ITD includes visible provenance metadata, the decision, the QTI evidence that motivated it, alternatives and tradeoffs, downstream rules, and trace links.

Module Conformance Checklist

Future modules use this list to prove they inherit platform-wide truth before their own surface QC can pass.

1. Use platform.tenant for tenant scope and never create a new per-module tenant table unless a rollback-approved compatibility bridge requires it.
2. Keep module-specific standards data in the module schema and shared operational facts in platform.*.
3. Register producer schemas such as incept as governed producer surfaces before any consumer app treats their rows as a product contract.
4. Include top-level Authentication and Errors sections in every customer website.
5. Use Problem errors and redact learner PII, secrets, raw package bytes, headers, IP addresses, and user agents.
6. Require Idempotency-Key for documented retryable create/import/upload/async operations.
7. Require If-Match or equivalent validators for lost-update-sensitive writes.
8. Compute Access-Control-Allow-Methods from the matched route and advertise only the served methods plus OPTIONS.
9. Pin the 12 API decision axes in architecture before downstream data dictionaries, customer websites, implementations, or surface QC claim conformance.
10. Write platform.audit_log rows for writes, privileged reads, service-role operations, learner-runtime deletion, conformance/trust mutations, and authz denials.
11. For deployed consumer handoffs, provide the stable <MODULE>_BASE_URL, matching <MODULE>_REVIEWER_JWT or consumer JWT, and <MODULE>_REVIEWER_TENANT when a module requires X-Timeback-Tenant; verify from the consumer side before closing cutover issues.
12. Emit structured logs and metrics using platform field names and SLO dimensions.
13. Run customer eval and rubric before advancing; roll back to the earliest flawed deliverable when a later artifact exposes a real contradiction.
14. Build static hosted docs under OUT_DIR/site and let the driver deploy and patch canonical_url.

Design Intent And Constraints