MOPC-Portal/.planning/ROADMAP.md

# Roadmap: MOPC — AI Ranking, Advancement & Mentoring

## Overview

This milestone extends the MOPC jury voting platform with four capabilities: an AI-powered ranking engine that interprets natural-language criteria and ranks projects per competition category, a drag-and-drop ranking dashboard for admin review and override, a bulk advancement flow with optional email notification, and cross-round mentor persistence that allows mentors to be assigned during any round type. Phases 1-3 are sequential and time-critical (Monday deadline for ranking and advancement). Phase 4 is independent and can run in parallel with Phases 2-3.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [ ] **Phase 1: AI Ranking Backend** - AI service, tRPC router, schema, and auto-trigger for ranking projects per category using natural-language criteria
- [ ] **Phase 2: Ranking Dashboard UI** - Drag-and-drop ranking tab on the round detail page with criteria input, preview-confirm dialog, and project detail side panel
- [ ] **Phase 3: Advancement + Email** - Bulk advancement flow with reject/advance in one operation, notify-vs-silent toggle, and admin-editable email templates
- [ ] **Phase 4: Mentor Persistence** - Mentor assignment during any round type with cross-round carryover and COI re-validation

## Phase Details

### Phase 1: AI Ranking Backend
**Goal**: Admin can call an AI ranking API that interprets natural-language criteria and returns per-category ranked project lists, persisted for audit
**Depends on**: Nothing (first phase)
**Requirements**: RANK-01, RANK-02, RANK-03, RANK-04, RANK-05, RANK-06, RANK-07, RANK-08, RANK-09, RANK-10
**Success Criteria** (what must be TRUE):
  1. Admin can submit natural-language ranking criteria and receive a structured preview of parsed rules before any ranking is applied
  2. AI ranking executes per CompetitionCategory (STARTUP and BUSINESS_CONCEPT ranked separately) using jury scores, pass/fail votes, and admin-defined criteria
  3. All project data is anonymized before leaving the server; OpenAI receives no PII
  4. Ranking results are stored as a RankingSnapshot with full audit trail (who ran it, when, with what criteria)
  5. Ranking auto-triggers when all jury assignments for a round are complete, including rounds where all assignments were already submitted before this feature shipped
**Plans**: TBD

### Phase 2: Ranking Dashboard UI
**Goal**: Admin has a working ranking interface on the round detail page where they can review, reorder, and prepare projects for advancement
**Depends on**: Phase 1
**Requirements**: DASH-01, DASH-02, DASH-03, DASH-04, DASH-05, DASH-06, DASH-07
**Success Criteria** (what must be TRUE):
  1. Admin sees a ranked project list per category on a new Ranking tab of the round detail page, showing AI-suggested order and any admin overrides as visually distinct states
  2. Admin can drag-and-drop projects to reorder within each category; local order is preserved while drag mutations are in-flight and does not snap back
  3. Admin can click any project row to see full evaluation detail in a side panel without leaving the ranking list
  4. Advance button is disabled while any reorder mutation is unsettled; once enabled, admin can select top N projects and advance them in one action
  5. Admin can batch-reject all non-advanced projects from the same interface
**Plans**: TBD

### Phase 3: Advancement + Email
**Goal**: Admin can advance and reject projects in one operation with full control over whether and what notification emails are sent to applicants
**Depends on**: Phase 2
**Requirements**: MAIL-01, MAIL-02, MAIL-03, MAIL-04, MAIL-05, MAIL-06
**Success Criteria** (what must be TRUE):
  1. Admin can choose per advancement batch whether to send an advancement email, a rejection email, both, or update statuses silently with no emails
  2. Admin can edit the text of advancement and rejection email templates directly in the platform, with supported variables shown inline
  3. Variable substitution uses a fixed whitelist ({{firstName}}, {{teamName}}, {{competitionName}}, {{roundName}}); no arbitrary template expressions are evaluated
  4. If the next round has no automated welcome emails configured, the system warns admin before they confirm advancement
  5. Email templates are stored in the database per competition/round and persist across sessions
**Plans**: TBD

### Phase 4: Mentor Persistence
**Goal**: Admin can assign mentors to projects from any round type, and those assignments carry forward to subsequent rounds unless the project is eliminated
**Depends on**: Nothing (independent track — can run in parallel with Phases 2-3)
**Requirements**: MENT-01, MENT-02, MENT-03, MENT-04, MENT-05, MENT-06
**Success Criteria** (what must be TRUE):
  1. Admin can open the mentor assignment UI from any round detail page, not only rounds of type MENTORING
  2. When a project advances to the next round, existing mentor assignments carry over automatically without admin action
  3. Before any mentor assignment carries over, the system re-validates that no conflict of interest exists between the mentor and the project in the new round; if one is found, the carryover is blocked and admin is notified
  4. Admin can override, change, or remove a mentor assignment at any point from any round
  5. AI suggests mentor-project matches based on expertise with admin confirmation required before the assignment is saved
  6. The ranking dashboard shows current mentor assignment status for each project in the ranked list
**Plans**: TBD

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 (Phase 4 can be parallelized with 2-3)

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. AI Ranking Backend | 2/4 | In Progress|  |
| 2. Ranking Dashboard UI | 0/TBD | Not started | - |
| 3. Advancement + Email | 0/TBD | Not started | - |
| 4. Mentor Persistence | 0/TBD | Not started | - |