Skip to content

Actors

Roles

Console users carry one of three roles in users.role. Roles are hierarchical โ€” a higher role includes every permission of the lower ones (admin 3 > member 2 > viewer 1).

Role Description Main operations
admin System-wide administrator Everything member can do, plus future administrative operations
member Researcher. The default role Create / update / delete projects, candidates, interviewers and email templates; send emails; run imports; confirm schedules; cancel reservations
viewer Read-only Browse lists, details, histories and dashboards; read survey data

Authorization is enforced by the requireRole() middleware, applied per router to POST / PATCH / PUT / DELETE requiring member or above. Insufficient privileges return 403 FORBIDDEN.

The surveys router is an exception

/api/v1/surveys/* only requires authentication (protectedRoute()) with no role restriction. It is read-only, but a viewer can still read the answers of every survey.

External Actors

Actor Description What they can do
Candidate A person in the candidates table. Not a console user Open the issued tokenized URL (/scheduling/{token}) to view the request and submit preferred slots
Creative Survey / Ask One Survey platform. Answers are read through Databricks (Read-only from this system's perspective)
Google Workspace Provider of OAuth, Calendar and Gmail Login, interviewer availability, tentative / confirmed events, email delivery

Role Diagram

graph TD
  Admin[admin]
  Member[member]
  Viewer[viewer]
  Candidate[Candidate<br/>unauthenticated]
  Google[Google Workspace]
  DBX[Creative Survey / Ask One<br/>Databricks]

  Admin -->|includes| Member
  Member -->|includes| Viewer

  Member -->|operates projects| System[Interview Arrangement System]
  Viewer -->|reads| System
  Candidate -->|scheduling token| System
  System -->|OAuth / Calendar / Gmail| Google
  DBX -->|query| System

About Interviewers

"Interviewer" is not a separate role โ€” it is a users record linked to a project via project_interviewers. An interviewer is therefore always a console user as well.

  • Adding / removing interviewers requires member or above (POST / DELETE /api/v1/projects/{projectId}/interviewers)
  • Availability is computed from the interviewer's Google Calendar
  • reservations.interviewer_id references users with onDelete: restrict, so a user with outstanding reservations cannot be deleted