Skip to main content

🗺️ Evalium – Assignments Backend Roadmap

Owner: Product Engineering
Status: Approved
Related: architecture, FOUNDATION.md, roles-and-access-control.md

Assignments are the bridge between an Evaluation Version and a Candidate.
Evalium follows a backend-first approach where Assignments must be correct, secure, and auditable before UI layers are added.

This roadmap governs the actual behaviour of the platform.

Phase 0 — Backend Foundation (NOW)

0.1 Schema: assignments​

Supports simple SMB invites now and enterprise scheduling later — without schema changes.

CREATE TABLE assignments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,     -- RLS Enforced
    org_unit_id UUID NOT NULL,   -- RLS Enforced

    -- Who?
    target_type TEXT NOT NULL,   -- 'email' | 'user_id' | 'group_id' | 'public_link'
    target_ref TEXT,             -- NULL for public_link, else ID or email

    -- What?
    evaluation_version_id UUID NOT NULL,  -- Immutable pointer

    -- When
    valid_from TIMESTAMPTZ,
    valid_until TIMESTAMPTZ,

    -- Overrides / Config
    allowed_attempts INT DEFAULT 1,
    time_limit_override INT,
    feedback_mode_override TEXT,

    -- Cohort
    run_label TEXT,

    -- Operational
    status TEXT DEFAULT 'active',
    created_by UUID,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

0.2 RLS & Invariants​

  • tenant_id + org_unit_id must match the caller (via TxManager + RLS).

  • When a delivery_session is created:

    • Copy time_limit_override, allowed_attempts, and feedback_mode_override into the session row.
    • Future changes to the assignment do not affect existing sessions.

Phase 1 — Lifecycle (Invite → Session)

1.1 Invitation Tokens​

A secure JWT that grants permission to start a session.

Payload:

  • assignment_id
  • tenant_id
  • org_unit_id
  • email (if targeted)
  • jti (single-use)
  • exp

Security:

  • Single-use enforced by storing/burning JTI.
  • Short TTL default.
  • Fully compatible with magic-link identity.

1.2 Redeem Endpoint​

POST /api/v1/assignments/redeem

Validates the token and:

  1. Checks deadline (valid_from / valid_until)
  2. Checks attempts
  3. Creates delivery_session
  4. Freezes assignment overrides into the session
  5. Issues a session JWT

Phase 2 — SMB MVP (Backend part)

These features enable the UX team to build a simple “Assign to Email” workflow.

2.1 Basic Assignment Creation​

  • Create an assignment for a single email.
  • Use internal mailer (future) to send an invitation token.
  • Store run_label if supplied.

2.2 Assignment Monitoring API (“Command Center” backend)​

Capability: assignments.monitor GET /api/v1/assignments/\{id\}/monitor

Returns:

  • invited → from assignment targets
  • in_progress → from sessions
  • completed → from submissions
  • expired → past deadline

Public-link assignments can only show active sessions, not missing invitees.

Phase 3 — Enterprise Power Layer

3.1 Dynamic Groups​

target_type = 'group_id'

Resolution happens at redeem time, not creation time.

3.2 Strict Windows & Timezones​

Backend rejects redemption outside UTC windows.

3.3 Assignment Templates (backend definition)​

CRUD storage of reusable assignment configurations.

Phase 4 — Differentiators (Backend Enablers)

4.1 Accommodations (DEI)​

Frozen into sessions:

  • 1.25x time
  • custom overrides

4.2 Ghost Proctoring Hooks​

Session event ingestion: focus_lost, tab_switch, paste_detected.

4.3 Cohort Analytics​

Assignments + submissions enable run_label-based reporting rollups.

Assignment Data Flow (Canonical)

invitation_token
      ↓ redeem
assignment → delivery_session → submission → snapshot → reporting

Summary

This document is the backend authority for Assignments. The UX roadmap is separate and optional; backend correctness defined here always takes precedence.