use case diagram

Use Case Diagram — Final Milestone (MyMentorNet)

This diagram reflects the deployed state of the backend as of the Final Milestone tag, verified one-by-one against the controllers under backend/src/main/java/com/group7/backend/controller/ and the scheduled jobs under backend/src/main/java/com/group7/backend/scheduler/. Earlier wiki diagrams document only the MVP surface — this file is the authoritative use case view for the Final Milestone Report.

Actor summary

Guest — unauthenticated visitor; can only perform sign-up, email verification, login, and the password-reset flow.
Mentee — authenticated user with role MENTEE. Owns mentee profile, mentee availability, mentorship-request sending, ratings.
Mentor — authenticated user with role MENTOR. Owns mentor profile, mentor availability, mentorship acceptance / extension / end, milestone authoring, task assignment, peer-mentor messaging.
Admin — authenticated user with role ADMIN. Owns moderation queue, bans, direct messaging to any user, broadcast to admins, user/report drill-down, suspected-bot flag.
System / Scheduler — non-human actor representing the Spring @Scheduled jobs. Triggers periodic sweeps (auto-cancel meetings, auto-complete expired mentorships, send reminders, prune orphans, refresh trending hashtags, fire match-changed notifications, expire bans, purge soft-deleted feed posts).

Mentees and Mentors are both Users; the diagram pulls the shared use cases (auth, own-profile, follow graph, feed, notifications, messaging, reports, taxonomy) into a Mentee / Mentor / Admin generalisation by drawing them from a common User super-actor as well as from the role-specific actor where the use case is role-gated by @PreAuthorize.

UML notation reference

Standard UML use-case notation has:

Actors drawn as stick figures (human) or labelled boxes (system actors)
Use cases drawn as ovals inside a system-boundary rectangle
Associations as plain lines between an actor and its use cases
<<include>> relationships as dashed open-arrow edges from a base use case to an included use case — the included case must run as part of the base
<<extend>> relationships as dashed open-arrow edges from an extending use case to a base use case — the extending case runs only when a condition is met
Generalization of actors (and of use cases) drawn with a hollow-triangle arrow toward the parent

Mermaid does not ship a native UML use-case diagram. The convention used below maps the standard notation onto the available primitives:

UML element	Rendered as Mermaid…	Visual cue
Actor	A stadium-shaped node (`ID(["Name"]):::actor`) outside any subgraph	Orange fill
Use case (interactive)	A rounded rectangle (`ID["Verb phrase"]:::usecase`) inside an actor's subgraph	Blue fill
Use case (System / Scheduler)	Same shape, distinct style (`:::sysuse`)	Green fill
Subgraph per actor	Groups every use case that actor triggers	One subgraph per actor block
Actor–use case association	A plain edge `ACTOR --- UC_X` from the actor stub to each use case	No arrowhead
`<<include>>`	A dotted edge `UC_A -.->\|"<<include>>"\| UC_B` from base to included	Labelled
`<<extend>>`	A dotted edge `UC_X -.->\|"<<extend>>"\| UC_BASE` from extension to base	Labelled
Actor generalization	A solid edge with the label `:specializes` from child to parent actor	Used here to link Mentee / Mentor / Admin to the abstract `User` actor

Every actor–use case edge corresponds to at least one controller endpoint or scheduled job verified against backend/src/main/java/com/group7/backend/. The catalogue below the diagram lists each use case with the concrete Controller#method (and HTTP path) that implements it.

Diagram (Mermaid)

%%{init: {'flowchart': {'htmlLabels': true, 'curve': 'basis'}, 'theme': 'neutral'}}%%
flowchart LR
  classDef actor fill:#fde2c4,stroke:#b65c00,stroke-width:2px,color:#3b2400,font-weight:bold;
  classDef usecase fill:#e7f0ff,stroke:#1f3d7a,color:#0b1f4a,rx:18,ry:18;
  classDef sysuse fill:#eafbe7,stroke:#1f7a3a,color:#0b3f1f,rx:18,ry:18;

  %% ───────────── ACTORS (stubs) ─────────────
  GUEST(["Guest"]):::actor
  USER(["User<br/>(Mentor ∪ Mentee ∪ Admin)"]):::actor
  MENTEE(["Mentee"]):::actor
  MENTOR(["Mentor"]):::actor
  ADMIN(["Admin"]):::actor
  SYS(["System / Scheduler"]):::actor

  %% ───────────── GUEST USE CASES ─────────────
  subgraph SG_GUEST [" "]
    direction TB
    UC_REG["Register account"]:::usecase
    UC_VERIFY["Verify email"]:::usecase
    UC_RESEND["Resend verification email"]:::usecase
    UC_LOGIN["Log in"]:::usecase
    UC_FORGOT["Request password reset"]:::usecase
    UC_VALID_TOK["Validate reset token"]:::usecase
    UC_RESET["Reset password"]:::usecase
    UC_FORMTOK["Fetch signup form token"]:::usecase
  end

  GUEST --- UC_REG
  GUEST --- UC_VERIFY
  GUEST --- UC_RESEND
  GUEST --- UC_LOGIN
  GUEST --- UC_FORGOT
  GUEST --- UC_VALID_TOK
  GUEST --- UC_RESET
  GUEST --- UC_FORMTOK

  %% ───────────── COMMON USER USE CASES ─────────────
  subgraph SG_USER [" "]
    direction TB
    UC_OWN_PROFILE["View own profile"]:::usecase
    UC_VIEW_PROFILE["View another user's profile"]:::usecase
    UC_LIST_USERS["Browse user directory"]:::usecase
    UC_SEARCH_USERS["Search users by keyword + filters"]:::usecase
    UC_UPLOAD_PHOTO["Upload / replace profile photo"]:::usecase
    UC_DELETE_PHOTO["Delete profile photo"]:::usecase
    UC_DELETE_ACCT["Delete own account"]:::usecase

    UC_FOLLOW["Follow a user"]:::usecase
    UC_UNFOLLOW["Unfollow a user"]:::usecase
    UC_LIST_FOLLOWERS["View followers of a user"]:::usecase
    UC_LIST_FOLLOWING["View following list"]:::usecase
    UC_FOLLOW_RECS["Get follow recommendations"]:::usecase

    UC_NOTIF_LIST["List notifications"]:::usecase
    UC_NOTIF_READ_ONE["Mark notification read"]:::usecase
    UC_NOTIF_READ_ALL["Mark all notifications read"]:::usecase
    UC_NOTIF_PREFS_GET["View notification preferences"]:::usecase
    UC_NOTIF_PREFS_SET["Update notification preferences"]:::usecase
    UC_DEVICE_REG["Register push-device token"]:::usecase
    UC_DEVICE_UNREG["Unregister push-device token"]:::usecase

    UC_KMUTE_LIST["List own muted keywords"]:::usecase
    UC_KMUTE_ADD["Add keyword mute"]:::usecase
    UC_KMUTE_DEL["Remove keyword mute"]:::usecase

    UC_REPORT_SUBMIT["Report user / post / mentorship"]:::usecase
    UC_REPORT_MINE["View own submitted reports"]:::usecase

    UC_TAX_SKILLS["Search ESCO skills taxonomy"]:::usecase
    UC_TAX_FIELDS["Search ISCED-F fields taxonomy"]:::usecase
    UC_TAX_HOBBIES["Search Wikidata hobbies"]:::usecase
  end

  USER --- UC_OWN_PROFILE
  USER --- UC_VIEW_PROFILE
  USER --- UC_LIST_USERS
  USER --- UC_SEARCH_USERS
  USER --- UC_UPLOAD_PHOTO
  USER --- UC_DELETE_PHOTO
  USER --- UC_DELETE_ACCT
  USER --- UC_FOLLOW
  USER --- UC_UNFOLLOW
  USER --- UC_LIST_FOLLOWERS
  USER --- UC_LIST_FOLLOWING
  USER --- UC_FOLLOW_RECS
  USER --- UC_NOTIF_LIST
  USER --- UC_NOTIF_READ_ONE
  USER --- UC_NOTIF_READ_ALL
  USER --- UC_NOTIF_PREFS_GET
  USER --- UC_NOTIF_PREFS_SET
  USER --- UC_DEVICE_REG
  USER --- UC_DEVICE_UNREG
  USER --- UC_KMUTE_LIST
  USER --- UC_KMUTE_ADD
  USER --- UC_KMUTE_DEL
  USER --- UC_REPORT_SUBMIT
  USER --- UC_REPORT_MINE
  USER --- UC_TAX_SKILLS
  USER --- UC_TAX_FIELDS
  USER --- UC_TAX_HOBBIES

  %% ───────────── SOCIAL FEED (Mentor + Mentee, admins blocked from authoring) ─────────────
  subgraph SG_FEED [" "]
    direction TB
    UC_POST_CREATE["Create feed post (text + hashtags + attachments)"]:::usecase
    UC_POST_EDIT["Edit own feed post"]:::usecase
    UC_POST_DELETE["Soft-delete own feed post"]:::usecase
    UC_POST_RESTORE["Restore soft-deleted own post"]:::usecase
    UC_POST_HISTORY["View post edit history"]:::usecase
    UC_POST_GET["View single post"]:::usecase

    UC_FEED_FORYOU["Read For-You feed (ranker)"]:::usecase
    UC_FEED_FOLLOWING["Read Following feed"]:::usecase
    UC_FEED_AUTHOR["Read author posts feed"]:::usecase
    UC_FEED_SEARCH["Search feed posts"]:::usecase
    UC_FEED_TRENDING["View trending hashtags"]:::usecase
    UC_FEED_MARK_READ["Mark feed read"]:::usecase
    UC_FEED_UNREAD["Get unread feed count"]:::usecase
    UC_FEED_MEDIA["Download feed-post image"]:::usecase

    UC_LIKE_POST["Like / unlike a post"]:::usecase
    UC_INT_STATE["Read post interaction state"]:::usecase
    UC_COMMENT_ADD["Comment on a post"]:::usecase
    UC_COMMENT_LIST["List post comments"]:::usecase
    UC_COMMENT_GET["View single comment"]:::usecase
    UC_COMMENT_EDIT["Edit own comment"]:::usecase
    UC_COMMENT_DEL["Delete own comment"]:::usecase
    UC_COMMENT_LIKE["Like a comment"]:::usecase
    UC_SHARE["Record post share"]:::usecase
    UC_REPOST["Repost / quote-share"]:::usecase
    UC_BOOKMARK["Toggle bookmark"]:::usecase
    UC_BOOKMARKS_LIST["List own bookmarks"]:::usecase
  end

  MENTEE --- UC_POST_CREATE
  MENTOR --- UC_POST_CREATE
  MENTEE --- UC_POST_EDIT
  MENTOR --- UC_POST_EDIT
  MENTEE --- UC_POST_DELETE
  MENTOR --- UC_POST_DELETE
  MENTEE --- UC_POST_RESTORE
  MENTOR --- UC_POST_RESTORE
  USER --- UC_POST_GET
  USER --- UC_POST_HISTORY
  USER --- UC_FEED_FORYOU
  USER --- UC_FEED_FOLLOWING
  USER --- UC_FEED_AUTHOR
  USER --- UC_FEED_SEARCH
  USER --- UC_FEED_TRENDING
  USER --- UC_FEED_MARK_READ
  USER --- UC_FEED_UNREAD
  USER --- UC_FEED_MEDIA
  USER --- UC_LIKE_POST
  USER --- UC_INT_STATE
  USER --- UC_COMMENT_ADD
  USER --- UC_COMMENT_LIST
  USER --- UC_COMMENT_GET
  USER --- UC_COMMENT_EDIT
  USER --- UC_COMMENT_DEL
  USER --- UC_COMMENT_LIKE
  USER --- UC_SHARE
  USER --- UC_REPOST
  USER --- UC_BOOKMARK
  USER --- UC_BOOKMARKS_LIST

  %% «include»: creating a post may include attachment upload
  UC_POST_CREATE -. "&laquo;include&raquo;" .-> UC_UPLOAD_ATT

  %% ───────────── MENTEE-ONLY USE CASES ─────────────
  subgraph SG_MENTEE [" "]
    direction TB
    UC_EDIT_MENTEE["Edit mentee profile"]:::usecase
    UC_MENTEE_AVAIL_GET["View own weekly availability"]:::usecase
    UC_MENTEE_AVAIL_SET["Set / replace own weekly availability"]:::usecase
    UC_MENTEE_AVAIL_ADD["Add own availability slot"]:::usecase
    UC_MENTEE_AVAIL_DEL["Remove own availability slot"]:::usecase

    UC_BROWSE_MENTORS["Browse mentor matches (matching algorithm + filters)"]:::usecase
    UC_BROWSE_MENTORS_ALL["List all mentor matches unpaginated"]:::usecase
    UC_LIST_MENTORS["Browse mentor directory"]:::usecase
    UC_VIEW_MENTOR_AVAIL["View mentor weekly availability"]:::usecase
    UC_VIEW_MENTOR_OVR["View mentor availability overrides"]:::usecase
    UC_EXPORT_ICAL["Export mentor availability as iCalendar"]:::usecase
    UC_VIEW_MENTOR_RATINGS["View mentor ratings"]:::usecase

    UC_SEND_REQ["Send mentorship request"]:::usecase
    UC_CANCEL_REQ["Cancel own pending request"]:::usecase
    UC_LIST_SENT["List sent requests"]:::usecase
    UC_CANCEL_MS["Cancel active mentorship (mentee)"]:::usecase
    UC_RATE_MENTOR["Rate mentor after termination"]:::usecase

    UC_CONFIRM_MEETING["Confirm a pending meeting"]:::usecase
    UC_DECLINE_MEETING["Decline a pending meeting"]:::usecase
    UC_SUBMIT_TASK["Submit work for a task"]:::usecase

    UC_MENTEE_STATS["View own mentee dashboard stats"]:::usecase
  end

  MENTEE --- UC_EDIT_MENTEE
  MENTEE --- UC_MENTEE_AVAIL_GET
  MENTEE --- UC_MENTEE_AVAIL_SET
  MENTEE --- UC_MENTEE_AVAIL_ADD
  MENTEE --- UC_MENTEE_AVAIL_DEL
  MENTEE --- UC_BROWSE_MENTORS
  MENTEE --- UC_BROWSE_MENTORS_ALL
  MENTEE --- UC_LIST_MENTORS
  MENTEE --- UC_VIEW_MENTOR_AVAIL
  MENTEE --- UC_VIEW_MENTOR_OVR
  MENTEE --- UC_EXPORT_ICAL
  MENTEE --- UC_VIEW_MENTOR_RATINGS
  MENTEE --- UC_SEND_REQ
  MENTEE --- UC_CANCEL_REQ
  MENTEE --- UC_LIST_SENT
  MENTEE --- UC_CANCEL_MS
  MENTEE --- UC_RATE_MENTOR
  MENTEE --- UC_CONFIRM_MEETING
  MENTEE --- UC_DECLINE_MEETING
  MENTEE --- UC_SUBMIT_TASK
  MENTEE --- UC_MENTEE_STATS

  %% «extend»: cancelling counts toward auto-ban threshold
  UC_AUTOBAN_CANCEL -. "&laquo;extend&raquo;" .-> UC_CANCEL_REQ
  UC_AUTOBAN_CANCEL -. "&laquo;extend&raquo;" .-> UC_CANCEL_MS

  %% ───────────── MENTOR-ONLY USE CASES ─────────────
  subgraph SG_MENTOR [" "]
    direction TB
    UC_EDIT_MENTOR["Edit mentor profile"]:::usecase
    UC_AVAIL_BULK["Bulk update own weekly availability"]:::usecase
    UC_AVAIL_ADD["Add own availability slot"]:::usecase
    UC_AVAIL_DEL["Remove own availability slot"]:::usecase
    UC_AVAIL_OVR_ADD["Add one-off availability override"]:::usecase
    UC_AVAIL_OVR_DEL["Remove availability override"]:::usecase

    UC_BROWSE_MENTEES["Browse candidate mentees"]:::usecase
    UC_LIST_MENTEES["List mentees directory"]:::usecase

    UC_LIST_RECEIVED["List received mentorship requests"]:::usecase
    UC_ACCEPT_REQ["Accept mentorship request"]:::usecase
    UC_REJECT_REQ["Reject mentorship request"]:::usecase
    UC_END_MS["End active mentorship gracefully"]:::usecase
    UC_EXTEND_MS["Extend active mentorship"]:::usecase

    UC_MS_CREATE_MEETING["Schedule meeting (one-off / recurring)"]:::usecase
    UC_MS_CANCEL_MEETING["Cancel a scheduled meeting"]:::usecase

    UC_CREATE_MILESTONE["Create milestone"]:::usecase
    UC_UPDATE_MILESTONE["Update milestone"]:::usecase
    UC_DELETE_MILESTONE["Delete milestone"]:::usecase
    UC_MS_AI_ADD["Add milestone action item"]:::usecase
    UC_MS_AI_DEL["Delete milestone action item"]:::usecase

    UC_CREATE_TASK["Assign a task"]:::usecase
    UC_DELETE_TASK["Delete an unsubmitted task"]:::usecase
    UC_REVIEW_TASK["Review submitted task"]:::usecase

    UC_PAIR_SEND["Send peer-mentor message"]:::usecase
    UC_PAIR_LIST["List peer-mentor messages"]:::usecase
    UC_PAIR_READ["Mark peer-mentor thread read"]:::usecase
    UC_PAIR_INBOX["List peer-mentor inbox"]:::usecase

    UC_MENTOR_STATS["View own mentor dashboard stats"]:::usecase
  end

  MENTOR --- UC_EDIT_MENTOR
  MENTOR --- UC_AVAIL_BULK
  MENTOR --- UC_AVAIL_ADD
  MENTOR --- UC_AVAIL_DEL
  MENTOR --- UC_AVAIL_OVR_ADD
  MENTOR --- UC_AVAIL_OVR_DEL
  MENTOR --- UC_BROWSE_MENTEES
  MENTOR --- UC_LIST_MENTEES
  MENTOR --- UC_LIST_RECEIVED
  MENTOR --- UC_ACCEPT_REQ
  MENTOR --- UC_REJECT_REQ
  MENTOR --- UC_END_MS
  MENTOR --- UC_EXTEND_MS
  MENTOR --- UC_MS_CREATE_MEETING
  MENTOR --- UC_MS_CANCEL_MEETING
  MENTOR --- UC_CREATE_MILESTONE
  MENTOR --- UC_UPDATE_MILESTONE
  MENTOR --- UC_DELETE_MILESTONE
  MENTOR --- UC_MS_AI_ADD
  MENTOR --- UC_MS_AI_DEL
  MENTOR --- UC_CREATE_TASK
  MENTOR --- UC_DELETE_TASK
  MENTOR --- UC_REVIEW_TASK
  MENTOR --- UC_PAIR_SEND
  MENTOR --- UC_PAIR_LIST
  MENTOR --- UC_PAIR_READ
  MENTOR --- UC_PAIR_INBOX
  MENTOR --- UC_MENTOR_STATS

  %% ───────────── SHARED MENTORSHIP LIFECYCLE (mentor + mentee participants) ─────────────
  subgraph SG_MS [" "]
    direction TB
    UC_LIST_ACTIVE["List active mentorships"]:::usecase
    UC_LIST_HIST["List mentorships by status (history)"]:::usecase
    UC_GET_MS["Get mentorship detail"]:::usecase
    UC_MS_GOAL["Set / update shared goal"]:::usecase
    UC_MS_PROGRESS["View mentorship progress"]:::usecase
    UC_MS_TIMELINE["View mentorship timeline"]:::usecase
    UC_MS_AUDIT["View mentorship audit trail"]:::usecase
    UC_GET_RATING["View mentorship rating"]:::usecase
    UC_DELETE_MS_DATA["Delete past mentorship data"]:::usecase

    UC_LIST_MEETINGS["List mentorship meetings"]:::usecase
    UC_GET_MEETING["View meeting detail"]:::usecase
    UC_RESCHED_REQ["Request meeting reschedule"]:::usecase
    UC_RESCHED_APPROVE["Approve reschedule request"]:::usecase
    UC_RESCHED_REJECT["Reject reschedule request"]:::usecase
    UC_MEETING_NOTES["Update meeting notes"]:::usecase
    UC_MEETING_AI_ADD["Add meeting action item"]:::usecase
    UC_MEETING_AI_UPDATE["Update / toggle meeting action item"]:::usecase
    UC_MEETING_AI_DEL["Delete meeting action item"]:::usecase

    UC_LIST_TASKS["List mentorship tasks"]:::usecase
    UC_GET_TASK["View task detail"]:::usecase
    UC_LIST_MILESTONES["List milestones"]:::usecase
    UC_GET_MILESTONE["View milestone detail"]:::usecase
    UC_MS_AI_UPDATE["Update / toggle milestone action item"]:::usecase

    UC_DM_SEND["Send mentorship chat message"]:::usecase
    UC_DM_LIST["List mentorship messages"]:::usecase
    UC_DM_READ["Mark mentorship thread read"]:::usecase
    UC_DM_STOMP["Send chat over WebSocket (STOMP)"]:::usecase
    UC_UPLOAD_ATT["Upload chat attachment"]:::usecase
    UC_DOWNLOAD_ATT["Download chat attachment"]:::usecase
  end

  MENTEE --- UC_LIST_ACTIVE
  MENTOR --- UC_LIST_ACTIVE
  MENTEE --- UC_LIST_HIST
  MENTOR --- UC_LIST_HIST
  MENTEE --- UC_GET_MS
  MENTOR --- UC_GET_MS
  MENTEE --- UC_MS_GOAL
  MENTOR --- UC_MS_GOAL
  MENTEE --- UC_MS_PROGRESS
  MENTOR --- UC_MS_PROGRESS
  MENTEE --- UC_MS_TIMELINE
  MENTOR --- UC_MS_TIMELINE
  MENTEE --- UC_MS_AUDIT
  MENTOR --- UC_MS_AUDIT
  MENTEE --- UC_GET_RATING
  MENTOR --- UC_GET_RATING
  MENTEE --- UC_DELETE_MS_DATA
  MENTOR --- UC_DELETE_MS_DATA
  MENTEE --- UC_LIST_MEETINGS
  MENTOR --- UC_LIST_MEETINGS
  MENTEE --- UC_GET_MEETING
  MENTOR --- UC_GET_MEETING
  MENTEE --- UC_RESCHED_REQ
  MENTOR --- UC_RESCHED_REQ
  MENTEE --- UC_RESCHED_APPROVE
  MENTOR --- UC_RESCHED_APPROVE
  MENTEE --- UC_RESCHED_REJECT
  MENTOR --- UC_RESCHED_REJECT
  MENTEE --- UC_MEETING_NOTES
  MENTOR --- UC_MEETING_NOTES
  MENTEE --- UC_MEETING_AI_ADD
  MENTOR --- UC_MEETING_AI_ADD
  MENTEE --- UC_MEETING_AI_UPDATE
  MENTOR --- UC_MEETING_AI_UPDATE
  MENTEE --- UC_MEETING_AI_DEL
  MENTOR --- UC_MEETING_AI_DEL
  MENTEE --- UC_LIST_TASKS
  MENTOR --- UC_LIST_TASKS
  MENTEE --- UC_GET_TASK
  MENTOR --- UC_GET_TASK
  MENTEE --- UC_LIST_MILESTONES
  MENTOR --- UC_LIST_MILESTONES
  MENTEE --- UC_GET_MILESTONE
  MENTOR --- UC_GET_MILESTONE
  MENTEE --- UC_MS_AI_UPDATE
  MENTOR --- UC_MS_AI_UPDATE
  MENTEE --- UC_DM_SEND
  MENTOR --- UC_DM_SEND
  MENTEE --- UC_DM_LIST
  MENTOR --- UC_DM_LIST
  MENTEE --- UC_DM_READ
  MENTOR --- UC_DM_READ
  MENTEE --- UC_DM_STOMP
  MENTOR --- UC_DM_STOMP
  MENTEE --- UC_UPLOAD_ATT
  MENTOR --- UC_UPLOAD_ATT
  MENTEE --- UC_DOWNLOAD_ATT
  MENTOR --- UC_DOWNLOAD_ATT

  %% «include»: sending a chat message with a file includes UC_UPLOAD_ATT
  UC_DM_SEND -. "&laquo;include&raquo;" .-> UC_UPLOAD_ATT

  %% ───────────── ADMIN USE CASES ─────────────
  subgraph SG_ADMIN [" "]
    direction TB
    UC_ADMIN_ME["Get admin session context"]:::usecase
    UC_ADMIN_USERS_LIST["List users (admin panel)"]:::usecase
    UC_ADMIN_USER_DETAIL["View user detail + ban history"]:::usecase
    UC_ADMIN_BAN["Ban user"]:::usecase
    UC_ADMIN_UNBAN["Unban user"]:::usecase
    UC_ADMIN_BAN_LIST["List a user's bans"]:::usecase
    UC_ADMIN_BAN_LIFT["Lift a specific ban"]:::usecase
    UC_ADMIN_CLEAR_BOT["Clear suspected-bot flag"]:::usecase

    UC_ADMIN_REPORT_QUEUE["List report queue (filters)"]:::usecase
    UC_ADMIN_REPORT_DETAIL["View report detail"]:::usecase
    UC_ADMIN_REPORT_TRANSITION["Resolve / dismiss / review report"]:::usecase

    UC_ADMIN_DM["Send admin DM to user"]:::usecase
    UC_ADMIN_BROADCAST["Broadcast to all admins"]:::usecase
    UC_ADMIN_BROADCAST_READ["Read admin broadcast thread"]:::usecase
    UC_ADMIN_BROADCAST_MARK["Mark broadcast as read"]:::usecase
    UC_ADMIN_DM_INBOX["List admin-direct inbox"]:::usecase
    UC_ADMIN_DM_THREAD["Read admin-direct thread with user"]:::usecase
    UC_ADMIN_DM_MARK["Mark admin-direct thread read"]:::usecase
  end

  ADMIN --- UC_ADMIN_ME
  ADMIN --- UC_ADMIN_USERS_LIST
  ADMIN --- UC_ADMIN_USER_DETAIL
  ADMIN --- UC_ADMIN_BAN
  ADMIN --- UC_ADMIN_UNBAN
  ADMIN --- UC_ADMIN_BAN_LIST
  ADMIN --- UC_ADMIN_BAN_LIFT
  ADMIN --- UC_ADMIN_CLEAR_BOT
  ADMIN --- UC_ADMIN_REPORT_QUEUE
  ADMIN --- UC_ADMIN_REPORT_DETAIL
  ADMIN --- UC_ADMIN_REPORT_TRANSITION
  ADMIN --- UC_ADMIN_DM
  ADMIN --- UC_ADMIN_BROADCAST
  ADMIN --- UC_ADMIN_BROADCAST_READ
  ADMIN --- UC_ADMIN_BROADCAST_MARK
  USER  --- UC_ADMIN_DM_INBOX
  USER  --- UC_ADMIN_DM_THREAD
  USER  --- UC_ADMIN_DM_MARK

  %% ───────────── SYSTEM / SCHEDULER USE CASES ─────────────
  subgraph SG_SYS [" "]
    direction TB
    UC_S_MEETING_REMIND["Send meeting reminders (T-24h)"]:::sysuse
    UC_S_MEETING_EXPIRE["Auto-cancel unconfirmed meetings"]:::sysuse
    UC_S_MEETING_COMPLETE["Auto-complete past-end meetings"]:::sysuse
    UC_S_MS_AUTOCOMPLETE["Auto-complete expired mentorships at term"]:::sysuse
    UC_S_TASK_REMIND["Send task / milestone reminders"]:::sysuse
    UC_S_ATT_CLEANUP["Prune orphan attachments"]:::sysuse
    UC_S_FEED_PURGE["Hard-delete expired soft-deleted posts"]:::sysuse
    UC_S_TRENDING_REFRESH["Refresh trending hashtags view"]:::sysuse
    UC_S_MATCH_NOTIFY["Fire match-changed notifications"]:::sysuse
    UC_S_BAN_EXPIRE["Notify users when ban expires"]:::sysuse
    UC_S_TOKEN_CLEANUP["Purge expired auth tokens"]:::sysuse
    UC_S_BOT_CLEANUP["Purge old bot-signal rows"]:::sysuse
    UC_AUTOBAN_CANCEL["Impose auto-ban for excessive cancellations"]:::sysuse
    UC_AUTOBAN_BOT["Impose auto-ban on suspected bot signup"]:::sysuse
  end

  SYS --- UC_S_MEETING_REMIND
  SYS --- UC_S_MEETING_EXPIRE
  SYS --- UC_S_MEETING_COMPLETE
  SYS --- UC_S_MS_AUTOCOMPLETE
  SYS --- UC_S_TASK_REMIND
  SYS --- UC_S_ATT_CLEANUP
  SYS --- UC_S_FEED_PURGE
  SYS --- UC_S_TRENDING_REFRESH
  SYS --- UC_S_MATCH_NOTIFY
  SYS --- UC_S_BAN_EXPIRE
  SYS --- UC_S_TOKEN_CLEANUP
  SYS --- UC_S_BOT_CLEANUP
  SYS --- UC_AUTOBAN_CANCEL
  SYS --- UC_AUTOBAN_BOT

  %% «extend»: bot-signup auto-ban extends Register
  UC_AUTOBAN_BOT -. "&laquo;extend&raquo;" .-> UC_REG

  %% Generalisation: Mentor, Mentee, Admin are all Users
  USER -. "generalises" .- MENTEE
  USER -. "generalises" .- MENTOR
  USER -. "generalises" .- ADMIN

Use case catalogue (sentence each, grouped by feature area)

Format: Use Case → controller / endpoint(s) → one-line meaning.

Authentication & account lifecycle (Guest)

Fetch signup form token → AuthController#formToken GET /api/auth/form-token → Issues the short-lived HMAC token used by the spam-bot defence on registration.
Register account → AuthController#register POST /api/auth/register → Creates a new user (mentor or mentee), runs spam-bot evaluation, sends a verification email.
Verify email → AuthController#verifyEmail GET /api/auth/verify-email → Activates the account via the emailed token.
Resend verification email → AuthController#resendVerification POST /api/auth/resend-verification → Rate-limited resend of the verification email.
Log in → AuthController#login POST /api/auth/login → Exchanges credentials for a JWT, enforcing the email-verified + not-banned gates.
Request password reset → AuthController#forgotPassword POST /api/auth/forgot-password → Sends a reset link (always 200 to prevent enumeration).
Validate reset token → AuthController#validateResetToken GET /api/auth/validate-reset-token → Lets the UI verify a token before showing the reset form.
Reset password → AuthController#resetPassword POST /api/auth/reset-password → Sets a new password using the emailed token.

Auth surface — design notes and coverage gap:

Logout is intentionally client-side only. The JWT issued by POST /api/auth/login is self-contained and stateless; the server stores no session row to invalidate. AuthContext.jsx#logout clears localStorage (auth_token, auth_role, auth_userId) and resets in-memory auth state. Adding a /api/auth/logout endpoint would be no-op work for a stateless JWT design and is omitted from the diagram for that reason. Token revocation, if needed in a follow-up, would require a server-side denylist or short-lived access tokens + refresh tokens — neither is in the current architecture.

No change-password endpoint is shipped. Password mutation today goes through POST /api/auth/forgot-password → emailed reset token → POST /api/auth/reset-password. This is a real coverage gap relative to typical account-management expectations; flagged here so the Final Milestone Report can disclose it honestly rather than imply a feature that does not exist. The diagram intentionally omits a "Change own password" node so it stays faithful to the deployed code.

Profile (User)

View own profile → UserController#getOwnProfile GET /api/users/me → Returns role-specific own-profile payload.
View another user's profile → UserController#getUserById GET /api/users/{id} → Public profile with role-based visibility (mentees can't see other mentees).
Browse user directory → UserController#getAllUsers / getAllMentors / getAllMentorsUnpaginated / MatchingController browse endpoints.
Search users by keyword + filters → UserController#searchUsers GET /api/users/search → Composable search with role / interest / skill / availability / duration filters.
Edit mentor profile → UserController#updateMentorProfile PATCH /api/users/me/mentor.
Edit mentee profile → UserController#updateMenteeProfile PATCH /api/users/me/mentee.
Upload / replace profile photo → UserController#uploadPhoto POST /api/users/me/photo.
Delete profile photo → UserController#deletePhoto DELETE /api/users/me/photo.
Delete own account → UserController#deleteUser DELETE /api/users/{id} (self-only).

Discovery & matching

Browse mentor matches → MatchingController#getTopMentors / getTopMentorsUnpaginated GET /api/matching/mentors[/all] → Ranked by matching algorithm with maxDistanceKm, availabilityDays, mentorshipDuration, minMatchScore filters.
Browse candidate mentees → MatchingController#getCandidateMentees GET /api/matching/mentees → Mentor-side ranked mentee list.
Browse mentor directory → UserController#getAllMentors[/all] GET /api/users/mentors[/all].
List mentees directory → UserController#getAllMentees GET /api/users/mentees (mentor-only).
View mentor ratings → UserController#getMentorRatings GET /api/users/{id}/ratings.

Availability

View mentor weekly availability → AvailabilityController#getSlots GET /api/availability/{mentorId}.
Bulk update own weekly availability → AvailabilityController#bulkUpdate PUT /api/availability (mentor).
Add own availability slot → AvailabilityController#addSlot POST /api/availability (mentor).
Remove own availability slot → AvailabilityController#removeSlot DELETE /api/availability/{slotId} (mentor).
View mentor availability overrides → AvailabilityController#listOverrides GET /api/availability/{mentorId}/overrides.
Add one-off availability override → AvailabilityController#addOverride POST /api/availability/overrides (mentor).
Remove availability override → AvailabilityController#removeOverride DELETE /api/availability/overrides/{overrideId} (mentor).
Export mentor availability as iCalendar → AvailabilityController#exportIcal GET /api/availability/{mentorId}/ical.
View own / set / replace / add / remove own (mentee) availability → MenteeAvailabilityController GET|PUT|POST /api/mentee-availability, DELETE /api/mentee-availability/{slotId} (mentee).

Follow graph

Follow / Unfollow a user → FollowController#follow|unfollow POST|DELETE /api/users/{id}/follow.
View followers / following → FollowController#listFollowers|listFollowing GET /api/users/{id}/followers|following.
Get follow recommendations → FollowRecommendationController#recommend GET /api/users/me/follow-recommendations → Score-ranked suggestions with explanation factors.

Mentorship lifecycle

Send mentorship request → MentorshipRequestController#createRequest POST /api/mentorship-requests (mentee).
List sent / received requests → MentorshipRequestController#getSentRequests|getReceivedRequests.
Cancel own pending request → MentorshipRequestController#cancelOwnRequest DELETE /api/mentorship-requests/{id} (mentee; counts toward auto-ban).
Accept mentorship request → MentorshipRequestController#acceptRequest PUT /api/mentorship-requests/{id}/accept (mentor).
Reject mentorship request → MentorshipRequestController#rejectRequest PUT /api/mentorship-requests/{id}/reject (mentor).
List active mentorships → MentorshipController#getActiveMentorships GET /api/mentorships.
List mentorships by status (history) → MentorshipController#getMentorshipsByStatus GET /api/mentorships?status=….
Get mentorship detail → MentorshipController#getMentorship GET /api/mentorships/{id}.
Set / update shared goal → MentorshipController#setSharedGoal PUT /api/mentorships/{id}/goal.
View mentorship progress / timeline / audit trail → MentorshipController#getMentorshipProgress|getMentorshipTimeline|getAuditTrail.
Cancel active mentorship (mentee) → MentorshipController#cancelMentorship POST /api/mentorships/{id}/cancel (mentee; counts toward auto-ban).
End active mentorship gracefully (mentor) → MentorshipController#endMentorship PATCH /api/mentorships/{id}/end.
Extend active mentorship (mentor) → MentorshipController#extendMentorship PATCH /api/mentorships/{id}/extend (1, 3, or 6 months).
View mentorship rating → MentorshipController#getMentorshipRating GET /api/mentorships/{id}/rating.
Rate mentor after termination → MentorshipController#rateMentor POST /api/mentorships/{id}/rating (mentee).
Delete past mentorship data → MentorshipController#deleteMentorshipData DELETE /api/mentorships/{id}/data (participants, only after non-ACTIVE).

Goal, milestones, action items

Create / list / get / update / delete milestone → MilestoneController POST|GET|PATCH|DELETE /api/mentorships/{id}/milestones, /api/milestones/{id} (mentor authors; both view).
Add / update / delete milestone action item → MilestoneController POST /api/milestones/{id}/action-items, PATCH|DELETE /api/milestone-action-items/{id} (mentor adds/deletes; either toggles completion).

Meetings

Schedule meeting (one-off / recurring) → MeetingController#createMeetings POST /api/mentorships/{id}/meetings (mentor; requires shared goal set — GOAL_REQUIRED).
List mentorship meetings → MeetingController#listMeetings GET /api/mentorships/{id}/meetings.
View meeting detail → MeetingController#getMeeting GET /api/meetings/{id}.
Confirm / decline a pending meeting → MeetingController#confirmMeeting|declineMeeting (mentee).
Cancel a scheduled meeting → MeetingController#cancelMeeting DELETE /api/meetings/{id} (mentor).
Request / approve / reject reschedule → MeetingController#requestReschedule|approveReschedule|rejectReschedule.
Update meeting notes → MeetingController#updateNotes.
Add / update / toggle / delete meeting action item → MeetingController#addActionItem|updateActionItem|deleteActionItem.

Tasks

Assign a task → TaskController#createTask POST /api/mentorships/{id}/tasks (mentor; requires shared goal).
List mentorship tasks → TaskController#listTasks.
View task detail → TaskController#getTask.
Submit work for a task → TaskController#submitTask POST /api/tasks/{id}/submission (mentee).
Review submitted task → TaskController#reviewTask PATCH /api/tasks/{id}/feedback (mentor).
Delete an unsubmitted task → TaskController#deleteTask.

Social feed

Create feed post → FeedPostController#create POST /api/feed/posts (mentor / mentee; admins blocked; «include» upload attachment when images attached).
View single post / edit / soft-delete / restore / view edit history → FeedPostController#getById|update|delete|restore|history.
Read For-You / Following / author / search feed → FeedReadController#forYou|following|postsByAuthor|search.
View trending hashtags → FeedTrendingController#hashtags GET /api/feed/trending/hashtags.
Mark feed read → FeedReadStateController#markRead POST /api/feed/mark-read.
Get unread feed count → FeedReadStateController#unreadCount GET /api/feed/unread-count.
Download feed-post image → FeedMediaDownloadController#download GET /api/uploads/feed-media/{attachmentId}.
Read post interaction state → FeedInteractionController#getInteractions.
Like / unlike a post → FeedInteractionController#toggleLike.
Comment on a post / list / view single / edit own / delete own / like comment → FeedInteractionController#addComment|listComments|getComment|editComment|deleteComment|toggleCommentLike.
Record post share → FeedInteractionController#recordShare POST /api/feed/posts/{id}/share.
Repost / quote-share → FeedInteractionController#repost POST /api/feed/posts/{id}/reposts.
Toggle bookmark / list own bookmarks → FeedInteractionController#toggleBookmark|myBookmarks.

Notifications & preferences

List notifications (optionally unread-only) → NotificationController#getNotifications.
Mark notification read / mark all read → NotificationController#markAsRead|markAllAsRead.
View / update notification preferences → UserNotificationPreferencesController#get|update GET|PATCH /api/users/me/notification-preferences.
Register / unregister push-device token → UserDeviceController#register|unregister POST|DELETE /api/users/me/devices.

Note: there is no dedicated unread-count notification endpoint — the list endpoint supports ?unreadOnly=true. The feed has its own unread cursor (see Social Feed).

Messaging (mentor-mentee + mentor-mentor + admin DMs)

Send / list / mark read mentorship chat → MessageController POST|GET|PATCH /api/mentorships/{mentorshipId}/messages[/read] («include» upload attachment when an attachment is referenced).
Send chat over WebSocket (STOMP) → ChatStompController#onSend SEND /app/chat.send/{conversationId} → real-time message send; broadcast happens via /topic/mentorship/{id}.
Upload chat attachment → AttachmentController#upload POST /api/messages/attachments.
Download chat attachment → AttachmentDownloadController#download GET /api/uploads/attachments/{attachmentId}.
List peer-mentor inbox → MentorPairInboxController#listInbox (mentor).
Send / list / mark read peer-mentor thread → MentorPairMessageController POST|GET|PATCH /api/conversations/mentor-pair/{otherMentorId}/messages[/read].
List admin-direct inbox → AdminDirectInboxController#listInbox GET /api/conversations/admin-direct.
Read admin-direct thread with user / mark thread read → AdminDirectMessageController#list|markAllRead.

Moderation — user-facing

Report user / post / mentorship → ReportController#submit POST /api/reports.
View own submitted reports → ReportController#myReports.
List / add / remove keyword mute → KeywordMuteController#list|add|remove GET|POST|DELETE /api/users/me/keyword-mutes[/{id}].

Moderation — Admin

Get admin session context → AdminController#me GET /api/admin/me.
List users / view user detail + ban history → AdminController#listUsers|getUserDetail.
Ban / unban user → AdminController#banUser|unbanUser POST /api/admin/users/{userId}/ban|unban.
List a user's bans / lift a specific ban → BanAdminController#listForUser|liftBan GET /api/admin/bans/users/{userId}, DELETE /api/admin/bans/{banId}.
Clear suspected-bot flag → AdminController#clearBotFlag POST /api/admin/users/{userId}/clear-bot-flag.
List report queue / view report detail / transition status → AdminReportController#queue|detail|transition GET|PATCH /api/admin/reports[/{id}].
Send admin DM to user → AdminMessagingController#direct POST /api/admin/messages/direct/{userId}.
Broadcast / read broadcast / mark broadcast read → AdminMessagingController#broadcast|listBroadcast|markBroadcastRead.

Stats

View own mentor dashboard stats → StatsController#getMentorStats GET /api/stats/mentor/me.
View own mentee dashboard stats → StatsController#getMenteeStats GET /api/stats/mentee/me.

Taxonomy lookups (autocomplete inside profile dropdowns)

Search ESCO skills / ISCED-F fields / Wikidata hobbies → TaxonomyController#searchSkills|searchFields|searchHobbies GET /api/taxonomies/skills|fields|hobbies.

System / Scheduler

Send meeting reminders (T-24h) + Auto-cancel unconfirmed meetings + Auto-complete past-end meetings → MeetingScheduler#run (delegates to MeetingSchedulerProcessor).
Auto-complete expired mentorships at term → MentorshipAutoCompletionScheduler#sweep.
Send task / milestone reminders → ReminderNotificationScheduler#processReminders.
Prune orphan attachments → AttachmentOrphanCleanupScheduler#sweepOrphans (daily 03:15 UTC).
Hard-delete expired soft-deleted posts → FeedSoftDeleteCleanupScheduler#purgeExpiredSoftDeletes.
Refresh trending hashtags view → FeedTrendingRefreshScheduler#refresh (hourly).
Fire match-changed notifications → MatchNotificationScheduler#notifyChangedMatches (daily 09:00 UTC).
Notify users when ban expires → BanExpiryScheduler#sweepExpired.
Purge expired auth tokens → TokenCleanupScheduler#deleteExpiredTokens.
Purge old bot-signal rows → BotSignalCleanupScheduler#sweepExpiredSignals.
Impose auto-ban for excessive cancellations → enforced inline by MentorshipService.cancelMentorship and MentorshipRequestService.cancelOwnPendingRequest (modelled as a System use case «extend»-ing the cancellation use cases).
Impose auto-ban on suspected bot signup → enforced by SpamDetectionService.onRegistrationCommitted invoked from AuthController.register (modelled as a System use case «extend»-ing Register).

UML include / extend relationships (the only ones actually backed by code)

Create feed post «include» Upload chat attachment — the same Attachment row backs both chat and feed uploads; feed-post creation references previously uploaded attachmentIds.
Send mentorship chat message «include» Upload chat attachment — chat sends with attachments reuse the same upload pipeline.
Impose auto-ban for excessive cancellations «extend» both Cancel own pending request and Cancel active mentorship (mentee) — the ban only fires when the cancellation count crosses a threshold (conditional extension).
Impose auto-ban on suspected bot signup «extend» Register account — the ban only fires when spam-detection signals breach the threshold.

Uh oh!

use case diagram

Use Case Diagram — Final Milestone (MyMentorNet)

Actor summary

UML notation reference

Diagram (Mermaid)

Use case catalogue (sentence each, grouped by feature area)

Authentication & account lifecycle (Guest)

Profile (User)

Discovery & matching

Availability

Follow graph

Mentorship lifecycle

Goal, milestones, action items

Meetings

Tasks

Social feed

Notifications & preferences

Messaging (mentor-mentee + mentor-mentor + admin DMs)

Moderation — user-facing

Moderation — Admin

Stats

Taxonomy lookups (autocomplete inside profile dropdowns)

System / Scheduler

UML include / extend relationships (the only ones actually backed by code)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!