Skip to main content

Implementation Spec — Offline Delivery (K/O/E)

Doc type: Implementation plan Scope: Delivery engine (Knowledge, Observation, Evidence) Status: Draft (aligned with current backend architecture) Anchors: Delivery Sessions, Submissions, Snapshots, Evidence Vault, Approval Workflow

1. Purpose & Non-Goals​

1.1 Purpose​

Offline delivery enables users to capture assessment data without network connectivity, then sync and submit later while preserving:

  • Assessment integrity
  • Audit defensibility
  • Immutable submission guarantees
  • Role-based approval workflows

Offline is a capability, not a requirement. It is selectively enabled based on risk profile and operational context.

1.2 Non-Goals​

Offline delivery is not intended to support:

  • Real-time invigilation
  • Collaborative live sessions
  • Mid-session policy changes
  • Offline grading or scoring

All authoritative outcomes remain server-side.

2. Core Principle​

Capture Offline. Submit Online.

Offline mode only affects data capture. The single source of truth remains the server.

No submission is valid until SubmitSession succeeds.

3. Delivery Model Overview​

PhaseModeAuthority
Session CreationOnline onlyServer
Data CaptureOnline or OfflineClient (temporary)
SyncOnline onlyServer
SubmissionOnline only (atomic)Server
ApprovalOnline onlyServer

4. Offline Capability Policy (Authoritative)​

Offline capability is resolved top-down, with stricter rules overriding permissive ones.

4.1 Policy Resolution Hierarchy​

Tenant → Org → Programme → Evaluation

If any level disallows offline, offline is disallowed.

4.2 Policy Field​

Each level supports:

offline_policy: "allowed" | "disallowed" | "inherit"

Defaults:

LevelDefault
Tenantallowed
Orginherit
Programmeinherit
Evaluationinherit

4.3 Resolution Algorithm​

At session creation:

  1. Start with Tenant
  2. Overlay Org (if not inherit)
  3. Overlay Programme
  4. Overlay Evaluation
  5. Final value is frozen into the session

4.4 Session Materialisation​

Resolved policy must be embedded into the delivery session:

{
  "offline": {
    "allowed": false,
    "resolved_from": "org",
    "resolved_policy": "disallowed"
  }
}

This guarantees:

  • No mid-session ambiguity
  • Forensic traceability
  • Predictable client behaviour

Offline capability is generic, but defaults enforce ideal behaviour.

Evaluation TypeDefault OfflineRationale
Knowledge (K)❌ DisabledExam integrity, timing enforcement
Observation (O)✅ EnabledField inspections, remote sites
Evidence (E)✅ EnabledArtefact capture, photos/video

Overrides are allowed at Programme/Evaluation level.

6. Client-Side Model (Offline Mirror)​

The client maintains a Local Session Mirror when offline.

6.1 Stored Locally​

  • Session ID
  • Questions / rubric structure
  • User responses
  • Evidence files (binary)
  • Client timestamps
  • Capture metadata (device, EXIF)

6.2 Never Stored Locally​

  • Scores
  • Outcomes
  • Approval status
  • Server timestamps
  • Other users’ data

7. Sync Mechanism (Required Gap Closure)​

7.1 The Problem​

Existing APIs are chatty (RecordAnswer per interaction).

Offline requires batched, idempotent sync.

7.2 New Endpoint (Required)​

POST /delivery/sessions/\{id\}/sync

Payload:

{
  "answers": [...],
  "events": [...],
  "client_started_at": "...",
  "client_completed_at": "..."
}

Behaviour:

  • Accepts batch
  • Idempotent (client IDs)
  • Validates session state
  • Writes server-side timestamps
  • Rejects partial failures atomically

8. Evidence & Asset Upload (Offline-Aware)​

Offline Evidence follows a state machine:

local_only → uploading → uploaded → attached

8.1 Upload Flow​

  1. Capture file offline
  2. Queue locally
  3. Request upload URL when online
  4. Upload via resumable protocol (TUS)
  5. Confirm upload
  6. Attach assetId to answer payload

8.2 Required Backend Work​

  • Asset upload API (request/confirm)
  • Upload state tracking
  • Asset ownership binding
  • Asset deletion hooks (already present)

9. Timestamp strategy (Forensic)​

TimestampSourceTrust Level
client_timestampClientInformational
received_atServerCanonical
submitted_atServerCanonical
approved_atServerCanonical

Client timestamps are stored but never authoritative.

Used for:

  • Pattern detection
  • Bulk upload analysis
  • Audit context

10. Submission & Approval (Unchanged)​

Offline does not alter submission semantics.

Submission remains:

  • Atomic
  • Immutable
  • Snapshot-based

Approval workflow applies identically:

StatusMeaning
pending_reviewWaiting for reviewer
approvedVisible to client
rejectedNew version required

11. Failure Modes & Safeguards​

11.1 Hard Blocks​

  • Offline session creation when disallowed
  • Submission without full sync
  • Submission with missing assets

11.2 Soft Signals​

  • Warning banners for offline Knowledge attempts
  • Reporting flags for offline usage
  • Client-side sync status indicators

12. Reporting & Audit Value​

Offline sessions should surface:

  • Offline usage indicator
  • Sync delay duration
  • Client vs server timestamp deltas
  • Policy source (org/programme/eval)

This strengthens:

  • Regulator confidence
  • Client trust
  • Legal defensibility

13. Implementation Checklist​

Backend​

  • Add offline_policy to Tenant / Org / Programme / Evaluation
  • Resolve offline policy at session creation
  • Persist resolved policy in session
  • Implement batch sync endpoint
  • Accept & persist client timestamps
  • Finalise asset upload lifecycle APIs

Client (Future)​

  • Local session mirror
  • Offline queue
  • Asset state tracking
  • Sync status UX

14. Summary​

Offline delivery is not a different engine. It is a controlled extension of your existing one.

You preserve:

  • Exam-board rigour
  • Inspection-grade ergonomics
  • Vault-level defensibility

And you gain:

  • Remote usability
  • Commercial flexibility
  • Zero schema rewrites
  • Strong policy enforcement

This spec fits your platform’s philosophy exactly.