Skip to main content

Onboarding and first setup

This page explains the real first-run flow for a new department in Academia. It is based on the current frontend and backend repositories, not a placeholder workflow.

:::tip Use this page when You need the practical first-run order for a brand new department, especially from the department head perspective. :::

Who should read this first​

  • Department heads setting up a new department
  • Contributors documenting first access and invitation flow
  • Coordinators who need to understand what is already configured before they enter

The important operating model is this:

  1. A department head account is created as part of institution registration.
  2. The department head verifies email and logs in.
  3. The department head is prompted to submit institution verification.
  4. The department head completes the department setup surfaces.
  5. The department head invites coordinators, advisors, and students.
  6. Invitees accept the invitation, log in, and complete their own first access steps.

Fastest route through onboarding​

If you only need the essential path, use this order:

  1. Register institution and department head.
  2. Verify email and log in.
  3. Complete institution verification.
  4. Review settings, templates, and department basics.
  5. Invite coordinators and advisors.
  6. Invite students.
  7. Let invitees accept, log in, and change password.

What the repos confirm​

The current platform behavior is split across both repositories:

  • The backend creates the tenant, department, default milestone template, and department head user during institution registration.
  • The frontend verification flow routes a department head to upload a verification document after OTP verification and login.
  • The department head dashboard exposes setup actions such as Invitations, Settings, and department management surfaces.
  • The invitation flow supports single invite, bulk student invite, preview email, resend, revoke, and public invitation acceptance.

Step 1: Register the institution and department head​

The first setup starts before anyone reaches a dashboard.

From the backend integration flow, institution registration already creates the core department context:

  • tenant or institution record
  • department record
  • department head user
  • default department milestone template

This means the first real owner of the workspace is the department head. They are the role that starts the operational setup for everyone else.

Step 2: Verify the department head email​

After registration, the department head verifies their email with OTP.

The frontend auth flow already describes this as a guided verification step. After OTP verification succeeds, the user is not finished yet. They still need to log in and complete onboarding.

Step 3: Log in and complete institution verification​

After login, the frontend calls the current session endpoint and checks the department head verification state.

The verification status can be:

  • NOT SUBMITTED
  • PENDING
  • APPROVED
  • REJECTED

The current product behavior is:

  • if the status is null or rejected, the department head is redirected to the verification surface
  • the user uploads a PDF, JPG, or PNG document
  • verification does not fully block tenant access, but it is treated as an onboarding requirement for the department head

This is the first action a new department head should complete after login.

Step 4: Open the department head workspace​

Once inside the dashboard, the department head becomes the setup owner for the department.

The frontend already exposes department-head surfaces for:

  • department overview
  • invitations
  • settings and configuration
  • templates and academic phase controls
  • faculty and user management
  • reports, announcements, and review operations

At this stage, the practical onboarding goal is to make the department usable by other roles.

Step 5: Configure the department basics​

Before inviting large numbers of users, the department head should review the department setup.

Based on the current frontend and backend, the most important early setup items are:

  1. Confirm the department identity and ownership context.
  2. Review academic phases and milestone timing.
  3. Review or prepare milestone templates.
  4. Review document templates and policy defaults where needed.

This matters because the backend already attaches department-scoped workflow rules and the frontend settings surfaces are built around those controls.

Step 6: Invite the first working roles​

After the department basics are in place, the department head invites the rest of the department.

This is the clearest first operational sequence supported by the product today:

  1. Invite coordinators to help run department-wide operations.
  2. Invite advisors to supervise projects.
  3. Invite students individually or in bulk.

The current invitation flow supports these role values:

  • Coordinator
  • Advisor
  • Student

The department head invitation screen currently supports:

  • single invitation form
  • bulk invite for students
  • invitation email preview
  • queued or immediate sending
  • invitation list with pending, accepted, expired, and revoked states
  • resend and revoke actions

Why this order makes sense​

This order matches how the platform is structured:

  • coordinators help with operational readiness
  • advisors need to exist before project supervision becomes active
  • students can then enter a department that already has governance and review capacity

Step 7: Invitees accept and activate their accounts​

The invitation flow is not just an email send. It has a real acceptance process.

The supported acceptance sequence is:

  1. Invitee opens the public acceptance link.
  2. The frontend previews the invitation details from the token.
  3. The invitee confirms acceptance.
  4. The backend creates the user and returns a temporary password once.
  5. The invitee logs in.
  6. The product forces a password change on first login.

This is why the onboarding docs should treat invitations as a full access workflow, not a simple email notification.

Step 8: Start the academic workflow​

After the department head has verified the institution, configured the department, and invited the working roles, the platform is ready for normal operations.

From there, the working flow moves into the main lifecycle:

  • students submit proposals and documents
  • advisors review and guide
  • coordinators monitor readiness and schedules
  • evaluators review assigned work
  • department heads keep oversight on approvals, settings, reporting, and policy surfaces

If you are documenting the platform for a brand new department, present the steps in this order:

  1. Register institution and department head
  2. Verify email
  3. Log in
  4. Submit institution verification document
  5. Review department settings, milestones, and templates
  6. Invite coordinators and advisors
  7. Invite students
  8. Let invitees accept, log in, and change password
  9. Begin proposal, milestone, and evaluation workflows

Best next reads​

  • Open Roles and dashboards if you want to see what each invited role does after first access.
  • Open Project lifecycle if you want to continue from onboarding into the actual academic workflow.