Candidate Interview Journey (verify → lobby → join → interview → completion)

Candidate uses the join link and password, enters the lobby, connects to the bot, and completes the interview.

Sequence

sequenceDiagram
  autonumber
  participant Cand as Candidate browser
  participant API as Hono API
  participant Verify as candidate-verify.service
  participant CandSvc as candidate-interview.service
  participant Bot as cleverhire-bot
  participant BotAPI as bot-interview.service
  participant Daily as Daily.co API
  participant Mongo as MongoDB

  Cand->>API: GET /v1/join/:token/peek
  API->>Verify: peekInterview
  Verify->>Mongo: find by joinTokenHash

  Cand->>API: POST /v1/join/:token/verify
  Verify->>Mongo: set candidateSessionHash
  Verify-->>Cand: sessionToken

  Cand->>API: GET /v1/candidate/interview (x-candidate-session)
  Cand->>API: POST /v1/candidate/consent
  Cand->>API: POST /v1/candidate/bot-session
  CandSvc-->>Cand: connectUrl + token

  Cand->>Bot: WebSocket / connect
  Bot->>API: GET /v1/bot/interviews/:id/context
  Bot->>API: POST /v1/bot/interviews/:id/start
  BotAPI->>Daily: POST /v1/rooms
  BotAPI->>Mongo: IN_PROGRESS + room fields
  BotAPI-->>Bot: room url

  loop During interview
    Bot->>API: PATCH runtime / proctoring
  end

  Bot->>API: POST /v1/bot/interviews/:id/complete

Steps

1. Candidate opens join link; peek shows branding and interview title.
2. Password verification mints a short-lived candidate session token.
3. Lobby APIs load interview details, record consent, and return bot connect URL.
4. Bot starts the interview, creates the Daily room, and sets status in progress.
5. Bot updates runtime during the session and calls complete when finished.