Skip to main content

Proposal review and approval

This page goes one level deeper into the proposal phase of Academia. It documents the current flow supported by the frontend and backend from the moment a student group leader prepares a proposal until the proposal becomes an approved project with an assigned advisor.

:::tip Use this page when You need the operational proposal flow from student draft through approval, rejection, project creation, and advisor assignment. :::

Fastest route through this guide​

  • Start with End-to-end sequence if you want the shortest proposal-phase summary.
  • Jump to Step 6 if you care most about approval behavior and project creation.
  • Jump to State model for proposal cards if you are designing or documenting reviewer UI states.

Why this phase matters​

Proposal review is the bridge between department setup and active project execution.

It is where the platform decides:

  • whether the project idea is academically acceptable
  • which candidate title becomes the final project title
  • whether the proposal needs revision
  • whether the proposal should become a real project now
  • whether an advisor is assigned immediately or later

Roles in this phase​

RoleResponsibility in proposal review
Student group leaderCreates the draft, uploads the PDF, submits for review, revises if rejected
Student group membersTrack proposal state and receive updates through the group view
CoordinatorMain reviewer for department proposal operations and approval workflow
Department headCan also review, reject, approve, and oversee proposal quality
AdvisorMay appear in pre-decision feedback or be assigned during or after approval

Best page after this one​

If you want to continue into...Open this page
the next student and advisor workflow after approvalMilestone delivery and advisor review
the full end-to-end stage mapProject lifecycle
staff assignment control after projects are createdStaff oversight and assignment

End-to-end sequence​

The current product flow is best understood as seven steps:

  1. Student creates a proposal draft.
  2. Student uploads the proposal PDF.
  3. Student submits the proposal for review.
  4. Coordinator or department head reviews the packet.
  5. Reviewer adds feedback, then approves or rejects.
  6. Approval creates a real project automatically.
  7. Advisor is assigned immediately or later.

Step 1: Student creates the proposal draft​

The proposal starts as a draft owned by an approved student group leader.

Current rules​

  • only an approved student group leader can start this flow
  • the draft must contain exactly three candidate titles
  • all three titles must be non-empty and unique
  • description is supported in the flow

Backend behavior​

  • proposal status starts as DRAFT
  • all candidate titles are stored for later reviewer selection
  • the first title is used as a temporary placeholder title before approval

Frontend entry points​

The frontend already supports two entry styles:

  • classic draft creation then PDF upload
  • upload-first flow where draft creation and PDF upload happen together

The current student dashboard emphasizes the upload-first version for proposal work.

Placeholder visual​

Proposal draft placeholder

Step 2: Student uploads the proposal PDF​

The proposal cannot move to review without a valid PDF.

Current rules​

  • file must be a PDF
  • max file size is 5MB
  • the backend stores the file as proposal.pdf inside proposal documents
  • upload is allowed only while the proposal is DRAFT or REJECTED

What the frontend does​

In the student upload page, proposal mode shows:

  • three title fields
  • description field
  • PDF picker
  • Upload Proposal action
  • Submit for Review action only after the draft and PDF are both present

Important behavior​

If the upload-first request fails, the backend rolls back the created draft rather than leaving a broken partial proposal.

Step 3: Student submits the proposal for review​

Once the PDF exists, the student group leader submits the proposal into the department review queue.

Current rules​

  • allowed from DRAFT or REJECTED
  • proposal must already include proposal.pdf
  • only one proposal per group can be in SUBMITTED state at a time

What happens on submit​

  • status changes to SUBMITTED
  • coordinator and department head are notified
  • the group can now track the proposal in a real review state instead of an editable draft state

What group members can see​

The group proposals response is the main source of truth for the student side. It can include:

  • proposal status
  • proposal documents
  • feedback
  • selected title information when approved
  • linked project information when the proposal becomes a project

Step 4: Reviewer opens the proposal packet​

After submission, the proposal enters a reviewer-owned phase.

Primary reviewer roles​

  • Coordinator
  • Department head

Reviewer responsibilities​

  • inspect the abstract, objectives, and supporting proposal file
  • compare the three candidate titles
  • decide whether the scope is ready
  • add actionable feedback when changes are needed
  • pick the final title when approving

Frontend reviewer surfaces​

The frontend already contains proposal-review oriented coordinator pages with:

  • filtered proposal lists
  • review sheet or detail view
  • coordinator note field
  • approve and reject actions
  • readiness and packet context

Placeholder visual​

Proposal review placeholder

Step 5: Reviewer feedback before the final decision​

Proposal review supports more than one final decision button. It also supports a feedback timeline.

Supported feedback behavior​

  • reviewers can add feedback comments before the final decision
  • feedback can be read back as a comment history
  • students can read feedback only for their own proposal
  • faculty and staff can read feedback if they have department access

Why this matters​

This turns proposal review into a guided academic process instead of a binary approve or reject step. It also gives the student group a clearer basis for revision when the proposal is not accepted immediately.

Step 6: Reviewer approves the proposal​

Approval is the most important state transition in this phase.

Required approval inputs​

  • status: APPROVED
  • approvedTitleIndex
  • optional advisorId

Approval rules​

  • proposal must be in SUBMITTED
  • reviewer must choose one of the three title indexes
  • advisor is optional at approval time

What approval does​

Approval now does all of the following:

  1. stores the selected final title
  2. marks the proposal as approved
  3. creates a real project automatically
  4. returns the created project.id
  5. optionally stores the advisor if one was chosen during approval

Important frontend implication​

The UI should treat approval as a proposal-to-project transition, not just a green status badge.

If the returned project has no advisor yet, the next action is Assign Advisor.

Step 7: Reviewer rejects the proposal​

Rejection is also structured, not freeform.

Required rejection inputs​

  • status: REJECTED
  • feedback

Rejection rules​

  • proposal must be in SUBMITTED
  • rejection feedback is required

What happens after rejection​

  • the student group sees the feedback
  • the proposal becomes eligible for revision and resubmission
  • the platform can also create a rejection reminder for the group with a countdown deadline

Practical outcome​

Rejected proposals do not end the workflow. They return the proposal to a guided revision loop with clearer next steps.

Step 8: Advisor assignment after approval​

Advisor assignment belongs to the same operational phase because it is the step that turns an approved idea into a supervised project.

Two valid flows​

Flow A: Approve with advisor selected​

  1. Reviewer chooses the winning title.
  2. Reviewer includes advisorId in the approval request.
  3. Proposal is approved.
  4. Project is created with advisor already assigned.

Flow B: Approve first, assign advisor later​

  1. Reviewer approves the proposal without advisorId.
  2. Backend creates the real project with advisorId = null.
  3. Frontend shows Assign Advisor.
  4. Reviewer or department staff loads advisor options.
  5. Frontend calls PUT /projects/:projectId/advisor.

Important ID rule​

When assigning an advisor, the request must use the advisor user id, not the advisor profile id.

Placeholder visual​

Advisor assignment placeholder

State model for proposal cards​

The proposal flow is easiest to understand if you think in states.

State A: Submitted proposal​

  • status: SUBMITTED
  • project: null
  • available actions: Approve, Reject, Add Feedback

State B: Approved proposal with created project and no advisor​

  • status: APPROVED
  • project exists
  • project advisor is null
  • available action: Assign Advisor

State C: Approved proposal with created project and advisor​

  • status: APPROVED
  • project exists
  • advisor exists
  • available action: Reassign Advisor if needed

State D: Rejected proposal​

  • status: REJECTED
  • feedback is visible
  • student can revise and resubmit

Notifications and communication in this phase​

The backend already documents notification events tied to proposal review, including:

  • PROPOSAL_SUBMITTED
  • PROPOSAL_APPROVED
  • PROPOSAL_REJECTED
  • rejection reminder events for resubmission countdowns

These notifications matter because proposal review is not only a reviewer action. It is a coordinated state change for the whole group and department workflow.

Role-by-role view of this phase​

Student group leader​

  • prepares the proposal
  • uploads the PDF
  • submits for review
  • reads feedback
  • resubmits if rejected

Coordinator​

  • reviews department submissions
  • adds feedback
  • approves or rejects
  • assigns advisor if needed

Department head​

  • can participate in the same review and approval decisions
  • keeps oversight on quality and department policy

Advisor​

  • may be selected at approval time
  • becomes visible to the student group once the proposal becomes a project
  • takes ownership of milestone supervision after assignment

Suggested reader journey​

If someone is learning the proposal phase of Academia for the first time, they should read it in this order:

  1. student draft and upload
  2. student submit for review
  3. reviewer feedback timeline
  4. approval or rejection
  5. automatic project creation
  6. advisor assignment

Placeholder visuals used here​

These screenshots are placeholders from the frontend repo and can be replaced later:

  • student proposal view: public/students.png
  • reviewer flow: public/coordinator.png
  • advisor assignment placeholder: public/advisor.png

Best next reads​