epic: Long-Term Mentorship — Complete Registration and Application Lifecycle

[womencodingcommunity]

Overview

This epic tracks the full implementation of the Long-Term Mentorship registration and mentee application lifecycle — from a mentee signing up for a cycle, through the multi-priority application workflow, manual matching, and final outcome.

This ticket is the parent of all related sub-tasks. Move child tickets under this one.

---

Mentee Registration Process

A mentee can register for a mentorship cycle by submitting a MenteeRegistration containing:

• Their profile details (Mentee object — id is optional; backend resolves by email if not provided)
• The mentorship type (LONG_TERM)
• The cycle year
• Up to 5 prioritised mentor applications (MenteeApplicationDto list), each with:
  • mentorId — the chosen mentor
  • priorityOrder — 1 (highest) to 5 (lowest)
  • whyMentor — reason for selecting this mentor
  • applicationMessage — optional personal message

Registration guards

Before processing, the backend validates:

• Mentee ProfileStatus must be ACTIVE (blocks PENDING, REJECTED, BANNED, DISABLED)
• The mentorship cycle must exist and be OPEN
• All referenced mentors must exist
• Mentee has not already reached the 5-application limit for this cycle
• Duplicate mentor applications within the same cycle are silently ignored

---

Full Application Status Lifecycle

Each mentor application has an ApplicationStatus that progresses through the following states:

Status reference

Status	Terminal?	Forwards to next priority?	Who triggers
PENDING	No	—	System (on registration)
MENTOR_REVIEWING	No	—	Mentor
MENTOR_ACCEPTED	No	—	Mentor
MENTOR_DECLINED	No	Yes	Mentor
MENTOR_UNAVAILABLE	No	Yes	Mentor / Admin
ADMIN_FORWARDED	No	Yes	Admin
REJECTED	No	Yes	Admin (rejects specific pairing only)
MATCHED	Yes	—	Admin (confirms match)
DROPPED	Yes	—	Mentee (withdraws)
CYCLE_EXCLUDED	Yes	No	Admin (removes from entire cycle)
NOT_ELIGIBLE	Yes	No	Admin (membership not approved)
EXPIRED	Yes	—	System (timeout)
PENDING_MANUAL_MATCH	No	—	System (all priorities exhausted)
NO_MATCH_FOUND	Yes	No	System / Admin

Workflow diagram

┌─────────────────────────────────────────────────────────────┐
│  REGISTRATION GUARD                                         │
│  ProfileStatus = PENDING / REJECTED / BANNED / DISABLED     │
│  → blocked with descriptive error                           │
└──────────────────────────┬──────────────────────────────────┘
                           │ ProfileStatus = ACTIVE
                           ▼
                       PENDING
                           │
        ┌──────────────────┼─────────────────┐
        │                  │                  │
  mentor reviews     mentee withdraws    no response
        │                  │              (timeout)
 MENTOR_REVIEWING       DROPPED ✓        EXPIRED ✓
        │
  ┌─────┼────────────────────────────────────┐
  │     │              │             │        │
mentor mentor       mentor       no reply  admin acts
accepts declines  unavailable   (admin)   at any point
  │     │              │             │
MENTOR_ MENTOR_    MENTOR_      ADMIN_     ──── SEVERE ADMIN ACTIONS ────
ACCEPTED DECLINED UNAVAILABLE  FORWARDED  CYCLE_EXCLUDED ✓  (all apps closed)
  │     │              │             │     NOT_ELIGIBLE ✓   (all apps closed)
admin   └──────────────┴─────────────┘
reviews        all three: forward to next priority
  │                       │
  │          ┌────────────┴────────────────┐
  │          │  priorities remaining?      │
  │          ├─ YES → next PENDING app     │
  │          └─ NO  → PENDING_MANUAL_MATCH │
  │                       │
 admin            admin manually
reviews          attempts a match
  │                       │
 ┌┴──────┐       ┌────────┴──────────┐
 │       │    found                 not found
admin  admin  new app → PENDING   NO_MATCH_FOUND ✓
confirms rejects  (normal flow)
 │      pairing
MATCHED ✓  │
        REJECTED (non-terminal)
           │
        forward → next priority

---

APIs

Existing endpoints (already implemented)

Method	Path	Description
POST	/api/platform/v1/mentees	Submit mentee registration
GET	/api/platform/v1/mentees/{menteeId}/applications	Get mentee applications for a cycle
PATCH	/api/platform/v1/mentees/applications/{id}/withdraw	Mentee withdraws application
GET	/api/platform/v1/mentors/{mentorId}/applications	Get applications for a mentor
PATCH	/api/platform/v1/mentors/applications/{id}/accept	Mentor accepts application
PATCH	/api/platform/v1/mentors/applications/{id}/decline	Mentor declines application
GET	/api/platform/v1/applications	Get applications by status

New endpoints (to be implemented by child tickets)

Method	Path	Description
PATCH	/api/platform/v1/mentees/applications/{id}/reject-pairing	Admin rejects specific pairing → forwards
PATCH	/api/platform/v1/mentees/applications/{id}/forward	Admin forwards to next mentor (no-response)
PATCH	/api/platform/v1/mentors/applications/{id}/mark-unavailable	Mentor/admin marks mentor unavailable
POST	/api/platform/v1/mentees/{menteeId}/cycles/{cycleId}/exclude	Admin excludes mentee from cycle
POST	/api/platform/v1/mentees/{menteeId}/cycles/{cycleId}/not-eligible	Admin marks mentee not eligible
POST	/api/platform/v1/mentees/{menteeId}/ban	Admin bans mentee permanently
GET	/api/platform/v1/mentees/pending-manual-match	List mentees awaiting manual match
POST	/api/platform/v1/mentees/{menteeId}/cycles/{cycleId}/assign-mentor	Admin manually assigns a mentor
POST	/api/platform/v1/mentees/{menteeId}/cycles/{cycleId}/no-match	Admin confirms no match found
GET	/api/platform/v1/mentees/{menteeId}/cycles/{cycleId}/mentor-suggestions	Ranked auto-match suggestions (backlog)

---

Child Tickets

#	Title
#543	feat: Add new ApplicationStatus values and DB migration
#544	feat: Block mentorship registration for ineligible mentees
#545	feat: Admin API to reject mentor-mentee pairing and forward
#546	feat: Admin API to mark mentor unavailable and forward
#547	feat: Admin APIs to exclude from cycle, not eligible, and ban
#548	feat: Auto-detect exhausted priorities → PENDING_MANUAL_MATCH
#549	feat: Admin APIs for manual mentor assignment and no match found
#550	feat: Automatic mentor matching algorithm (backlog)

---

Implementation Order

#543 (enum + DB)
    │
    ├── #544 (registration guard)
    ├── #545 (reject pairing)
    ├── #546 (unavailable + forward)
    ├── #547 (exclusion + ban)
    └── #548 (PENDING_MANUAL_MATCH)
              │
              └── #549 (manual assign + no-match)
                        │
                        └── #550 (auto-match — backlog)