Developer guide
Safe extension points
Add question types, reports, providers, jobs, files, or UI without weakening tenant isolation or historical assessment state.
MaintainerIntegratorReviewer
Responsibility
An extension is complete only when the server contract, authorization, persistence, user interface, imports/exports, audit behavior, failure recovery, and tests agree.
Components and data flow
- Question types: typed authoring schema, preview, player rendering, answer persistence, grading, imports/exports.
- Reports: finalized source state, institute scope, privacy-safe aggregation, filters, export rules.
- Providers: adapter contract, guarded endpoint, secret storage, timeout/retry, audit and fallback.
- Jobs: explicit tenant/actor context, idempotency, bounded batches, observable failure.
- Files: validated type/size, generated safe name, private storage, authorized access, retention.
Rules that must remain true
- No new path bypasses the common tenant and permission boundary.
- Historical exams and attempts remain interpretable after an extension changes.
- Unavailable optional services degrade explicitly and recoverably.
- User-facing validation matches authoritative server validation.
Failure modes
- Adding only a UI control creates unsupported stored state.
- A new report queries mutable drafts and disagrees with published results.
- A provider call inside the main transaction extends locks and creates partial failure.
- An uploaded filename becomes a path or response-header injection.
Safe extension guidance
- Begin with the domain contract and failure states, then implement adapters and UI.
- Reuse existing services and policy patterns before introducing parallel abstractions.
- Add migrations with forward-safe defaults and update compatibility notes.
- Add developer and operator documentation in the same change.
Required tests
- Happy path plus validation boundary for every supported type/state.
- Authorization and tenant isolation for UI, endpoint, job, export, and download.
- Upgrade from the previous supported schema with existing assessment history.
- Provider/file/job failures and retry behavior.
- Documentation search, links, examples, and screenshots remain current.
Release gate: Do not ship a partially integrated extension; every storage and consumer path must understand the new state.