504 lines
38 KiB
Markdown
504 lines
38 KiB
Markdown
# 08. Platform Integration Matrix
|
|
|
|
## 1. Overview
|
|
|
|
This document maps the **blast radius** of the Competition/Round redesign across every page, router, and service in the MOPC platform. It serves as a reference for developers to understand:
|
|
|
|
- **Which pages** need UI updates to reflect new terminology and data models
|
|
- **Which routers** require refactoring vs. minor updates vs. no changes
|
|
- **Which services** must be renamed, rewritten, or extended
|
|
- **Integration acceptance criteria** to verify completeness
|
|
|
|
Use this document alongside the data model ([02-data-model.md]) and competition flow ([03-competition-flow.md]) to plan implementation work.
|
|
|
|
### Terminology Translation
|
|
|
|
The redesign replaces Pipeline/Track/Stage terminology with Competition/Round:
|
|
|
|
| Old Term | New Term | Notes |
|
|
|----------|----------|-------|
|
|
| Pipeline | Competition | Top-level container for a complete program round |
|
|
| Stage | Round | Individual phases within a competition (Intake, Jury 1, Jury 2, etc.) |
|
|
| Track | *Eliminated* | Replaced by SpecialAward routing modes and JuryGroup memberships |
|
|
| StageType | RoundType | 7 typed round kinds (Intake, Eligibility Filter, Jury Evaluation 1/2/3, Live Finals, Results) |
|
|
| configJson | Typed configs | Each RoundType has its own Zod-validated config schema |
|
|
|
|
### Reading This Document
|
|
|
|
- **Priority levels**: Critical (blocks launch), High (required for full feature parity), Medium (enhances UX), Low (nice-to-have)
|
|
- **Classifications**: Directly Governed (major refactor), Context-Dependent (moderate updates), Utility (minimal/no changes)
|
|
- **File paths**: All paths relative to `G:\Repos\MOPC\`
|
|
|
|
---
|
|
|
|
## 2. Admin Pages Impact Matrix
|
|
|
|
Admin pages require the most extensive changes due to terminology shifts and new JuryGroup management.
|
|
|
|
| Page/Route | Current State | Required Changes | Priority | Related Docs |
|
|
|------------|---------------|------------------|----------|--------------|
|
|
| **Dashboard & Overview** |
|
|
| `src/app/(admin)/admin/page.tsx` | Program overview, pipeline status | Update "Pipelines" → "Competitions", show Competition status tiles | High | [03-competition-flow.md] |
|
|
| **Competition Management** (was Pipeline) |
|
|
| `src/app/(admin)/admin/rounds/pipelines/page.tsx` | Pipeline list view | Rename to "Competitions", update filters/columns | Critical | [02-data-model.md] |
|
|
| `src/app/(admin)/admin/rounds/pipeline/[id]/page.tsx` | Pipeline detail view | Rename to Competition detail, show Round timeline | Critical | [03-competition-flow.md] |
|
|
| `src/app/(admin)/admin/rounds/new-pipeline/page.tsx` | Pipeline creation wizard | Rename to "New Competition", use wizard-template.ts | Critical | [05-competition-wizard.md] |
|
|
| `src/app/(admin)/admin/rounds/pipeline/[id]/wizard/page.tsx` | Stage setup wizard | Rename to "Round Setup", enforce RoundType requirements, validate skeleton completeness | Critical | [05-competition-wizard.md] |
|
|
| `src/app/(admin)/admin/rounds/pipeline/[id]/edit/page.tsx` | Basic pipeline editing | Rename to Competition editing, prevent invalid Round sequences | High | [05-competition-wizard.md] |
|
|
| `src/app/(admin)/admin/rounds/pipeline/[id]/advanced/page.tsx` | Advanced config editing | Add policy editors for JuryGroup binding, assignment policies, submission windows, deliberation config | High | [04-jury-groups.md] |
|
|
| **Round Configuration** (was Stage) |
|
|
| `src/components/admin/pipeline/stage-config-editor.tsx` | Generic stage config | Render RoundType-aware controls only, use typed configs (IntakeConfig, FilterConfig, etc.) | Critical | [06-round-configs.md] |
|
|
| `src/components/admin/pipeline/sections/assignment-section.tsx` | min/max load + overflow | Replace with hard/soft cap + buffer + category bias controls (labeled as suggestive, not deterministic) | High | [04-jury-groups.md] |
|
|
| `src/components/admin/pipeline/sections/filtering-section.tsx` | Rules + AI criteria | Bind to Eligibility Filter RoundType, standardized outcomes | High | [07-deliberation.md] |
|
|
| `src/components/admin/pipeline/sections/awards-section.tsx` | Award routing/scoring | Add participation mode (separate_pool/dual_track), pull-out behavior, single-judge config | High | [04-jury-groups.md] |
|
|
| `src/components/admin/pipeline/sections/live-finals-section.tsx` | Live/audience settings | Add Jury 3 deliberation window, final deliberation linkage, cursor control config | High | [07-deliberation.md] |
|
|
| **Juries Management (NEW)** |
|
|
| *(NEW)* `src/app/(admin)/admin/juries/page.tsx` | None (create new) | List all JuryGroups (Jury 1, 2, 3, award juries), show member counts, caps, overlaps | Critical | [04-jury-groups.md] |
|
|
| *(NEW)* `src/app/(admin)/admin/juries/[id]/page.tsx` | None (create new) | JuryGroup detail: members, cap config, category ratios, bias settings | Critical | [04-jury-groups.md] |
|
|
| *(NEW)* `src/app/(admin)/admin/juries/[id]/members/page.tsx` | None (create new) | Add/remove jury members, configure individual caps/biases, track overlaps | Critical | [04-jury-groups.md] |
|
|
| **Assignment Management** |
|
|
| `src/app/(admin)/admin/projects/pool/page.tsx` | Project pool operations | Use AssignmentIntent for manual queuing, show reason tracking, policy compliance status | High | [04-jury-groups.md] |
|
|
| `src/components/admin/assignment/*` | Stage-based assignment | Update to Round-based, show JuryGroup context, cap violations, buffer status | High | [04-jury-groups.md] |
|
|
| **Filtering Configuration** |
|
|
| `src/app/(admin)/admin/projects/page.tsx` | Project list by filters | Add Round-aware views, show submission bundle health, Round 1/2 document status | Medium | [06-round-configs.md] |
|
|
| **Submission Window Management** |
|
|
| *(Enhanced)* Round config pages | Embedded in stage config | Extract submission window config to dedicated UI: slots, grace periods, late policy, resubmit rules | High | [06-round-configs.md] |
|
|
| **Special Awards Configuration** |
|
|
| `src/app/(admin)/admin/awards/page.tsx` | Award list | Expose Mode A/B semantics, admin-confirmed pull-out workflow | High | [04-jury-groups.md] |
|
|
| `src/app/(admin)/admin/awards/[id]/page.tsx` | Award detail | Show participation mode, JuryGroup bindings, single-judge config | High | [04-jury-groups.md] |
|
|
| `src/app/(admin)/admin/awards/[id]/edit/page.tsx` | Award editing | Add strict validation for mode, Round bindings, jury requirements | High | [04-jury-groups.md] |
|
|
| `src/app/(admin)/admin/awards/new/page.tsx` | Award creation | Wizard for Mode A/B selection, JuryGroup assignment | High | [04-jury-groups.md] |
|
|
| **Live Finals Management** |
|
|
| *(NEW)* `src/app/(admin)/admin/rounds/[id]/live/page.tsx` | None (create new) | Stage manager controls: cursor position, project advance, deliberation timer, audience vote toggle | Critical | [07-deliberation.md] |
|
|
| **Deliberation Management (NEW)** |
|
|
| *(NEW)* `src/app/(admin)/admin/rounds/[id]/deliberation/page.tsx` | None (create new) | Session management, lock controls, quorum status, admin override panel | Critical | [07-deliberation.md] |
|
|
| **Results / Result Lock Management** |
|
|
| `src/app/(admin)/admin/reports/stages/page.tsx` | Stage reporting | Include deliberation session status, result lock state, compliance metrics (cap violations, override counts) | High | [07-deliberation.md] |
|
|
| *(NEW)* `src/app/(admin)/admin/rounds/[id]/results/lock/page.tsx` | None (create new) | Final result lock interface with snapshot preview, mandatory reason, audit trail | Critical | [07-deliberation.md] |
|
|
| *(NEW)* `src/app/(admin)/admin/rounds/[id]/results/unlock/page.tsx` | None (super admin only) | Result unlock workflow with mandatory justification, relock capability | Critical | [07-deliberation.md] |
|
|
| **User/Invite Management** |
|
|
| `src/app/(admin)/admin/members/page.tsx` | User list | Add JuryGroup membership column, show pending AssignmentIntents | Medium | [04-jury-groups.md] |
|
|
| `src/app/(admin)/admin/members/invite/page.tsx` | User invitation | Bind to JuryGroup selection, support AssignmentIntent mode vs. direct assignment | Critical | [04-jury-groups.md] |
|
|
| `src/app/(admin)/admin/members/[id]/page.tsx` | User detail | Show all JuryGroup memberships, assignment history, cap status | Medium | [04-jury-groups.md] |
|
|
| **Reports / Analytics** |
|
|
| `src/app/(admin)/admin/reports/page.tsx` | Generic reports | Add Competition-aware KPIs: assignment saturation, override rate, policy compliance | Medium | [03-competition-flow.md] |
|
|
| `src/app/(admin)/admin/audit/page.tsx` | Audit log search | Add filter facets: RoundType, JuryGroup ID, deliberation session | Medium | [07-deliberation.md] |
|
|
| **Settings** |
|
|
| `src/app/(admin)/admin/settings/page.tsx` | Platform settings | No terminology changes needed | Low | - |
|
|
| `src/app/(admin)/admin/settings/tags/page.tsx` | Tag management | No changes | Low | - |
|
|
| `src/app/(admin)/admin/settings/webhooks/page.tsx` | Webhook config | Update event names: pipeline.* → competition.*, stage.* → round.* | Medium | - |
|
|
|
|
---
|
|
|
|
## 3. Jury Pages Impact Matrix
|
|
|
|
Jury pages must reflect Round-based navigation and JuryGroup membership.
|
|
|
|
| Page/Route | Current State | Required Changes | Priority | Related Docs |
|
|
|------------|---------------|------------------|----------|--------------|
|
|
| **Jury Dashboard** |
|
|
| `src/app/(jury)/jury/page.tsx` | Stage countdown, assigned projects | Show Round countdown, multi-JuryGroup memberships, completion obligations per group | High | [04-jury-groups.md] |
|
|
| **Round Navigation** (was Stage) |
|
|
| `src/app/(jury)/jury/stages/page.tsx` | Active stages list | Rename to "Rounds", show only Rounds bound to user's JuryGroups | Critical | [03-competition-flow.md] |
|
|
| `src/app/(jury)/jury/stages/[stageId]/assignments/page.tsx` | Assignment list | Update to Round context, show cap status, category ratio compliance, buffer usage | High | [04-jury-groups.md] |
|
|
| **Project Review** |
|
|
| `src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/page.tsx` | Project details | Separate Round 1 vs. Round 2 documents clearly, show submission window provenance | High | [06-round-configs.md] |
|
|
| `src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/evaluate/page.tsx` | Evaluation form | Enforce Round/JuryGroup policy, show graceful lock behavior, CoI declaration | Critical | [04-jury-groups.md] |
|
|
| `src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/evaluation/page.tsx` | View evaluation | Show evaluation history, AI summary integration | Medium | [06-round-configs.md] |
|
|
| `src/app/(jury)/jury/stages/[stageId]/compare/page.tsx` | Compare projects | Update to Round context, show Round 1/2 docs side-by-side | Medium | - |
|
|
| **Live Finals Voting** |
|
|
| `src/app/(jury)/jury/stages/[stageId]/live/page.tsx` | Live finals interaction | Require Jury 3 membership, show current cursor position, enable voting only for current project | Critical | [07-deliberation.md] |
|
|
| **Deliberation Voting (NEW)** |
|
|
| *(NEW)* `src/app/(jury)/jury/stages/[stageId]/deliberation/page.tsx` | None (create new) | Deliberation interface: category scope, project shortlist, vote casting, quorum status | Critical | [07-deliberation.md] |
|
|
| **Awards** |
|
|
| `src/app/(jury)/jury/awards/page.tsx` | Award assignments | Bind to award JuryGroup memberships, hide single-judge awards | High | [04-jury-groups.md] |
|
|
| `src/app/(jury)/jury/awards/[id]/page.tsx` | Award voting | Show participation mode, suppress jury voting for single-judge awards | High | [04-jury-groups.md] |
|
|
| **Learning Resources** |
|
|
| `src/app/(jury)/jury/learning/page.tsx` | Learning materials | No terminology changes | Low | - |
|
|
|
|
---
|
|
|
|
## 4. Applicant Pages Impact Matrix
|
|
|
|
Applicant pages must reflect Round-based journey and submission windows.
|
|
|
|
| Page/Route | Current State | Required Changes | Priority | Related Docs |
|
|
|------------|---------------|------------------|----------|--------------|
|
|
| **Applicant Dashboard** |
|
|
| `src/app/(applicant)/applicant/page.tsx` | Generic dashboard | Show Round-based journey (R1 Intake → Eligibility → Jury 1 Result → R2 Submission → Jury 2 → Live Finals → Results) | High | [03-competition-flow.md] |
|
|
| **Pipeline/Journey View** |
|
|
| `src/app/(applicant)/applicant/pipeline/page.tsx` | Pipeline visibility | Rename to "Competition Journey", show RoundType-based progress, submission window status | Critical | [03-competition-flow.md] |
|
|
| `src/app/(applicant)/applicant/pipeline/[stageId]/status/page.tsx` | Stage status | Update to Round status, show jury assignment count, evaluation progress | Medium | [06-round-configs.md] |
|
|
| **Document Upload** |
|
|
| `src/app/(applicant)/applicant/pipeline/[stageId]/documents/page.tsx` | Stage docs | Enforce Round-based submission windows, show slot state (write/read-only), late submission warnings | Critical | [06-round-configs.md] |
|
|
| `src/app/(applicant)/applicant/documents/page.tsx` | Docs overview | Show Round 1 vs. Round 2 bundles, official slot timeline, promotion provenance | High | [06-round-configs.md] |
|
|
| **Team Management** |
|
|
| `src/app/(applicant)/applicant/team/page.tsx` | Team invites/members | Gate permissions via context resolver, ensure invite acceptance routes correctly | Medium | [02-data-model.md] |
|
|
| **Mentoring Workspace** |
|
|
| `src/app/(applicant)/applicant/mentor/page.tsx` | Mentor interaction | Show mentor messages, workspace files, promotion candidates, official slot mapping | High | [06-round-configs.md] |
|
|
| **Public Submission Forms** |
|
|
| `src/app/(public)/apply/[slug]/page.tsx` | Stage/public form | Enforce SubmissionWindow contract (slots, grace period, late policy) | Critical | [06-round-configs.md] |
|
|
| `src/app/(public)/apply/edition/[programSlug]/page.tsx` | Edition mode intake | Map to Intake RoundType, enforce Round 1 submission policies | Critical | [06-round-configs.md] |
|
|
| `src/app/(public)/my-submission/[id]/page.tsx` | Submission detail | Show Round context, submission window status, document bundle health | Medium | [06-round-configs.md] |
|
|
| `src/app/(public)/my-submission/[id]/team/page.tsx` | Team management | Mirror applicant team flow, no divergent logic | Medium | [02-data-model.md] |
|
|
|
|
---
|
|
|
|
## 5. Mentor Pages Impact Matrix
|
|
|
|
Mentor pages need workspace enhancements and file promotion logic.
|
|
|
|
| Page/Route | Current State | Required Changes | Priority | Related Docs |
|
|
|------------|---------------|------------------|----------|--------------|
|
|
| **Mentor Dashboard** |
|
|
| `src/app/(mentor)/mentor/page.tsx` | Assigned teams overview | Show Round progression, submission window deadlines, file promotion status | High | [06-round-configs.md] |
|
|
| `src/app/(mentor)/mentor/projects/page.tsx` | Team list | Add Round context, show document bundle completeness | Medium | [06-round-configs.md] |
|
|
| **Mentor Workspace** |
|
|
| `src/app/(mentor)/mentor/projects/[id]/page.tsx` | Project detail | Add workspace file uploads, threaded comments, file promotion actions (team-lead/admin only) | Critical | [06-round-configs.md] |
|
|
| *(NEW)* `src/app/(mentor)/mentor/projects/[id]/workspace/page.tsx` | None (create new) | Dedicated workspace tab: private files, comments, promotion queue, official slot preview | Critical | [06-round-configs.md] |
|
|
| *(NEW)* `src/app/(mentor)/mentor/projects/[id]/milestones/page.tsx` | None (create new or enhance) | Milestone tracking, deadline alerts, progress reporting | Medium | - |
|
|
| **Learning Resources** |
|
|
| `src/app/(mentor)/mentor/resources/page.tsx` | Mentor materials | No terminology changes | Low | - |
|
|
|
|
---
|
|
|
|
## 6. Observer & Audience Pages Impact Matrix
|
|
|
|
Observer and audience pages have minimal changes but need consistent terminology.
|
|
|
|
| Page/Route | Current State | Required Changes | Priority | Related Docs |
|
|
|------------|---------------|------------------|----------|--------------|
|
|
| **Observer Dashboard** |
|
|
| `src/app/(observer)/observer/page.tsx` | Read-only overview | Update "Pipelines" → "Competitions" | Low | - |
|
|
| `src/app/(observer)/observer/reports/page.tsx` | Observer reports | Update terminology, no functional changes | Low | - |
|
|
| **Audience Voting** |
|
|
| `src/app/(public)/vote/[sessionId]/page.tsx` | Audience vote form | Enforce category/session mode, anti-duplicate policy | Medium | [07-deliberation.md] |
|
|
| `src/app/(public)/vote/stage/[sessionId]/page.tsx` | Stage-specific voting | Update to Round context | Medium | [07-deliberation.md] |
|
|
| **Live Scores** |
|
|
| `src/app/(public)/live-scores/[sessionId]/page.tsx` | Live score display | Update terminology, no functional changes | Low | - |
|
|
| `src/app/(public)/live-scores/stage/[sessionId]/page.tsx` | Stage-specific scores | Update to Round context | Low | - |
|
|
|
|
---
|
|
|
|
## 7. tRPC Router Classification
|
|
|
|
Every router is classified by its relationship to Competition/Round context.
|
|
|
|
| Router | Classification | Required Changes | Priority | Related Docs |
|
|
|--------|----------------|------------------|----------|--------------|
|
|
| **Directly Governed** (core competition logic, major refactoring required) |
|
|
| `pipeline.ts` | Directly Governed | **Rename to `competition.ts`**. Replace Pipeline model with Competition, update all CRUD operations, wizard templates, context resolution | Critical | [02-data-model.md], [05-competition-wizard.md] |
|
|
| `stage.ts` | Directly Governed | **Rename to `round.ts`**. Replace Stage model with Round, implement RoundType-based config validation, update transition logic | Critical | [02-data-model.md], [06-round-configs.md] |
|
|
| `stageFiltering.ts` | Directly Governed | **Rename to `roundFiltering.ts`**. Update to use Round context, standardized eligibility outcomes | High | [06-round-configs.md] |
|
|
| `stageAssignment.ts` | Directly Governed | **Rename to `roundAssignment.ts`**. Update to Round + JuryGroup context, implement new assignment preview/run logic | Critical | [04-jury-groups.md] |
|
|
| *(NEW)* `juryGroup.ts` | Directly Governed | **Create new router**. CRUD for JuryGroups, member management, cap config, overlap validation | Critical | [04-jury-groups.md] |
|
|
| *(NEW)* `deliberation.ts` | Directly Governed | **Create new router**. Session management, voting, quorum calculation, result locking, admin overrides | Critical | [07-deliberation.md] |
|
|
| `live.ts` | Directly Governed | Update to require Jury 3 context, bind cursor to Live Finals RoundType, add deliberation handoff | High | [07-deliberation.md] |
|
|
| `live-voting.ts` | Directly Governed | Tie session lifecycle to RoundType, add deliberation session support | High | [07-deliberation.md] |
|
|
| `cohort.ts` | Directly Governed | Align with Live Finals and Selection policies, category boundaries | Medium | [03-competition-flow.md] |
|
|
| `decision.ts` | Directly Governed | Extend to deliberation decisions, result lock events, admin override audit | High | [07-deliberation.md] |
|
|
| `specialAward.ts` | Directly Governed | Add strict validation for participation mode, Round bindings, admin-confirmed pull-out, single-judge config | High | [04-jury-groups.md] |
|
|
| `award.ts` | Directly Governed | Expose Mode A/B semantics, JuryGroup bindings | High | [04-jury-groups.md] |
|
|
| **Context-Dependent** (consume competition context but have own logic, moderate updates) |
|
|
| `assignment.ts` | Context-Dependent | Update to Round + JuryGroup context, centralize policy engine usage for all assignment paths | Critical | [04-jury-groups.md] |
|
|
| `evaluation.ts` | Context-Dependent | Incorporate JuryGroup binding checks, deliberation contribution rights, Round-based evaluation windows | High | [04-jury-groups.md] |
|
|
| `applicant.ts` | Context-Dependent | Add SubmissionBundleState, enforce slot state/round lock/promotion provenance/late policy | Critical | [06-round-configs.md] |
|
|
| `application.ts` | Context-Dependent | Create SubmissionBundleState on submission, normalize category key mapping, enforce Round policies | Critical | [06-round-configs.md] |
|
|
| `file.ts` | Context-Dependent | Use submission round + RoundType-aware visibility, enforce slot/promotion rules | High | [06-round-configs.md] |
|
|
| `project.ts` | Context-Dependent | Add Round-aware views, submission bundle health, Round 1/2 document separation | High | [06-round-configs.md] |
|
|
| `project-pool.ts` | Context-Dependent | Use AssignmentIntent for manual queue, reason tracking | High | [04-jury-groups.md] |
|
|
| `mentor.ts` | Context-Dependent | Add workspace file/comment/promotion endpoints, enforce team-lead/admin promotion permissions | Critical | [06-round-configs.md] |
|
|
| `user.ts` | Context-Dependent | Support dual invite behavior (AssignmentIntent vs. direct assignment), track JuryGroup memberships | High | [04-jury-groups.md] |
|
|
| `notification.ts` | Context-Dependent | Expand event taxonomy: jury membership, promotion, deliberation lock, Round transitions | High | [03-competition-flow.md] |
|
|
| `message.ts` | Context-Dependent | Ensure context tags reference Round/JuryGroup/project where applicable | Medium | - |
|
|
| `dashboard.ts` | Context-Dependent | Update to show Competition status, Round progress, JuryGroup obligations | Medium | [03-competition-flow.md] |
|
|
| `analytics.ts` | Context-Dependent | Add Competition KPIs: assignment saturation, override rate, policy compliance | Medium | [03-competition-flow.md] |
|
|
| `export.ts` | Context-Dependent | Include result lock version, policy compliance evidence, Round context | Medium | [07-deliberation.md] |
|
|
| `audit.ts` | Context-Dependent | Add filter facets: RoundType, JuryGroup ID, deliberation session | Medium | [07-deliberation.md] |
|
|
| `filtering.ts` | Context-Dependent | Update to Round context, standardized eligibility outcomes | High | [06-round-configs.md] |
|
|
| `gracePeriod.ts` | Context-Dependent | Integrate with SubmissionWindow grace period logic | Medium | [06-round-configs.md] |
|
|
| **Utility** (minimal or no changes, context-independent) |
|
|
| `avatar.ts` | Utility | No changes | None | - |
|
|
| `logo.ts` | Utility | No changes | None | - |
|
|
| `tag.ts` | Utility | No changes | None | - |
|
|
| `partner.ts` | Utility | No changes | None | - |
|
|
| `learningResource.ts` | Utility | No changes | None | - |
|
|
| `settings.ts` | Utility | No changes | None | - |
|
|
| `webhook.ts` | Utility | Update event names: pipeline.* → competition.*, stage.* → round.* | Low | - |
|
|
| `typeform-import.ts` | Utility | No changes (legacy import) | None | - |
|
|
| `notion-import.ts` | Utility | No changes (legacy import) | None | - |
|
|
| `wizard-template.ts` | Utility | Update template structure: Pipeline → Competition, Stage → Round | High | [05-competition-wizard.md] |
|
|
| `program.ts` | Utility | No changes (Program model unchanged) | None | - |
|
|
| `_app.ts` | Utility | Update router exports (pipeline → competition, stage → round, add juryGroup, deliberation) | Critical | - |
|
|
|
|
---
|
|
|
|
## 8. Service Layer Classification
|
|
|
|
Services are the backend orchestration layer. Many require renaming and logic updates.
|
|
|
|
| Service | Required Changes | Depends On | Priority | Related Docs |
|
|
|---------|------------------|------------|----------|--------------|
|
|
| **Core Orchestration Services** (rename + refactor) |
|
|
| `stage-engine.ts` | **Rename to `round-engine.ts`**. Implement RoundType-aware transition guards, validate Round sequence requirements | Round model, typed configs | Critical | [03-competition-flow.md], [06-round-configs.md] |
|
|
| `stage-filtering.ts` | **Rename to `round-filtering.ts`**. Standardized eligibility outcomes with reason schema, AI filtering integration | Round model, AI services | High | [06-round-configs.md] |
|
|
| `stage-assignment.ts` | **Rename to `round-assignment.ts`**. Full hard/soft cap policy engine, category bias scoring, JuryGroup binding | Round model, JuryGroup model, assignment policies | Critical | [04-jury-groups.md] |
|
|
| `stage-notifications.ts` | **Rename to `round-notifications.ts`**. Expand event taxonomy: jury membership, Round transitions, deliberation, promotion, result lock | Round model, notification router | High | [03-competition-flow.md] |
|
|
| **Live & Deliberation Services** |
|
|
| `live-control.ts` | Update to bind cursor to Live Finals RoundType, require Jury 3 membership, add deliberation handoff logic | Round model, JuryGroup model | High | [07-deliberation.md] |
|
|
| *(NEW)* `deliberation.ts` | **Create new service**. Session orchestration, quorum calculation, unanimous-with-fallback voting, result locking, admin override handling | Round model, JuryGroup model, decision router | Critical | [07-deliberation.md] |
|
|
| *(NEW)* `result-lock.ts` | **Create new service**. Final result snapshot creation, lock/unlock workflow, audit trail, super-admin-only unlock | Round model, deliberation service | Critical | [07-deliberation.md] |
|
|
| **AI Services** |
|
|
| `ai-filtering.ts` | Update to use Round context, standardized eligibility schema | Round model, anonymization | High | [06-round-configs.md] |
|
|
| `ai-assignment.ts` | Update to use JuryGroup context, Round-based project pool | Round model, JuryGroup model | High | [04-jury-groups.md] |
|
|
| `ai-evaluation-summary.ts` | **Add AI shortlist generation**. Generate deliberation shortlists from evaluation scores, handle ties | Round model, evaluation router | Critical | [07-deliberation.md] |
|
|
| `ai-tagging.ts` | No changes (project-level tagging, context-independent) | None | None | - |
|
|
| `ai-award-eligibility.ts` | Update to use Round context, participation mode awareness | Round model, specialAward router | Medium | [04-jury-groups.md] |
|
|
| `ai-errors.ts` | No changes (utility error handling) | None | None | - |
|
|
| **Assignment & Matching Services** |
|
|
| `smart-assignment.ts` | **Partial refactor**. Convert soft heuristics into policy-compliant scoring, treat category bias as transparent scoring (not strict quota), integrate with round-assignment.ts | Round model, JuryGroup model | High | [04-jury-groups.md] |
|
|
| `mentor-matching.ts` | Update to gate matching by finalist status, mentorship request, Round policy | Round model, mentor router | Medium | [06-round-configs.md] |
|
|
| **Background Jobs** |
|
|
| `award-eligibility-job.ts` | Update to use Round context, persist decision reasoning under unified audit taxonomy | Round model, audit router | Medium | [04-jury-groups.md] |
|
|
| `evaluation-reminders.ts` | Update to RoundType-aware reminder templates, JuryGroup-specific obligations, deliberation reminders | Round model, JuryGroup model | High | [04-jury-groups.md] |
|
|
| `email-digest.ts` | Update terminology in email templates (Pipeline → Competition, Stage → Round) | Round model | Medium | - |
|
|
| **Utility Services** |
|
|
| `anonymization.ts` | No changes (AI privacy utility) | None | None | - |
|
|
| `notification.ts` | Update event templates to use Competition/Round terminology | Round model | Medium | - |
|
|
| `in-app-notification.ts` | Update notification rendering to use new terminology | Round model | Medium | - |
|
|
| `webhook-dispatcher.ts` | Update event names: pipeline.* → competition.*, stage.* → round.* | Round model | Low | - |
|
|
| **Workspace Services** (new or enhanced) |
|
|
| *(NEW)* `mentor-workspace.ts` | **Create new or enhance mentor.ts service**. File upload, threaded comments, promotion queue, official slot mapping, team-lead/admin-only promotion | Round model, file router, mentor router | Critical | [06-round-configs.md] |
|
|
|
|
---
|
|
|
|
## 9. Integration Acceptance Criteria
|
|
|
|
The integration is considered complete when ALL of the following are verified:
|
|
|
|
### 9.1 Terminology & Data Model
|
|
- [ ] All `Pipeline` references eliminated from codebase (code, comments, docs)
|
|
- [ ] All `Stage` references eliminated from codebase (code, comments, docs)
|
|
- [ ] All `Track` references eliminated from codebase (code, comments, docs)
|
|
- [ ] `Competition` model fully implemented with typed configs
|
|
- [ ] `Round` model fully implemented with 7 RoundType configs
|
|
- [ ] `JuryGroup` model fully implemented with member management
|
|
- [ ] All database migrations applied successfully
|
|
- [ ] Prisma schema validated and generated
|
|
|
|
### 9.2 Core Functionality
|
|
- [ ] Competition CRUD fully functional (create, read, update, delete)
|
|
- [ ] Round CRUD fully functional (create, read, update, delete, reorder)
|
|
- [ ] JuryGroup CRUD fully functional (create, assign members, configure caps/biases)
|
|
- [ ] All 7 typed RoundType configs validated by Zod on save
|
|
- [ ] Round transition engine working (intake → eligibility → jury 1 → jury 2 → jury 3 → live finals → results)
|
|
- [ ] Assignment engine respects hard/soft caps, buffer, category bias
|
|
- [ ] Filtering engine produces standardized eligibility outcomes
|
|
- [ ] AI services integration working (filtering, assignment, evaluation summary, shortlist generation)
|
|
|
|
### 9.3 Deliberation & Results
|
|
- [ ] Deliberation session management working (create, vote, quorum, lock)
|
|
- [ ] Unanimous-with-quorum-fallback voting logic functional
|
|
- [ ] AI shortlist generation from evaluation scores working
|
|
- [ ] Admin override panel functional with audit trail
|
|
- [ ] Result lock/unlock workflow functional (super-admin only)
|
|
- [ ] Result lock snapshots persisted with version history
|
|
- [ ] DecisionAuditLog captures all deliberation events
|
|
|
|
### 9.4 Admin UX
|
|
- [ ] Admin dashboard shows Competition status (not Pipeline)
|
|
- [ ] Competition wizard uses new Competition/Round terminology
|
|
- [ ] Round configuration editor uses RoundType-specific controls
|
|
- [ ] JuryGroup management pages functional (list, detail, members)
|
|
- [ ] Assignment management shows JuryGroup context, cap violations
|
|
- [ ] Live finals stage manager working (cursor, deliberation timer)
|
|
- [ ] Deliberation admin panel working (session controls, overrides)
|
|
- [ ] Result lock UI functional with preview and audit trail
|
|
|
|
### 9.5 Jury UX
|
|
- [ ] Jury dashboard shows Round countdown (not Stage)
|
|
- [ ] Jury sees only Rounds bound to their JuryGroups
|
|
- [ ] Project review shows Round 1 vs. Round 2 documents separately
|
|
- [ ] Evaluation form enforces Round/JuryGroup policy
|
|
- [ ] Live finals voting requires Jury 3 membership
|
|
- [ ] Deliberation voting interface functional (shortlist, vote, quorum)
|
|
- [ ] Award voting respects JuryGroup bindings, hides single-judge awards
|
|
|
|
### 9.6 Applicant UX
|
|
- [ ] Applicant pipeline renamed to "Competition Journey"
|
|
- [ ] Journey shows RoundType-based progress (Intake → Eligibility → Jury 1 → ...)
|
|
- [ ] Document upload enforces submission window slots
|
|
- [ ] Round 1 vs. Round 2 bundles clearly separated
|
|
- [ ] Late submission warnings displayed per policy
|
|
- [ ] Mentor workspace shows file promotion candidates
|
|
- [ ] Team management gates permissions correctly
|
|
|
|
### 9.7 Mentor UX
|
|
- [ ] Mentor dashboard shows Round progression
|
|
- [ ] Mentor workspace file upload working
|
|
- [ ] Threaded comments functional
|
|
- [ ] File promotion actions restricted to team-lead/admin
|
|
- [ ] Official slot preview shows promoted files correctly
|
|
|
|
### 9.8 Audience & Observer UX
|
|
- [ ] Audience voting enforces category/session mode
|
|
- [ ] Anti-duplicate voting policy working
|
|
- [ ] Observer pages use Competition/Round terminology
|
|
- [ ] Live scores display updated terminology
|
|
|
|
### 9.9 Technical Requirements
|
|
- [ ] All tRPC routers updated (pipeline → competition, stage → round, etc.)
|
|
- [ ] All services renamed (stage-engine → round-engine, etc.)
|
|
- [ ] All page routes updated (pipeline → competition terminology in UI)
|
|
- [ ] TypeScript strict mode passing with no errors
|
|
- [ ] All unit tests passing (update test factories for Competition/Round)
|
|
- [ ] Integration tests covering Competition/Round/JuryGroup workflows
|
|
- [ ] Database seed script updated to use new models
|
|
- [ ] Docker entrypoint working with new migrations
|
|
|
|
### 9.10 Audit & Compliance
|
|
- [ ] All admin actions audited via DecisionAuditLog
|
|
- [ ] Deliberation decisions recorded with session context
|
|
- [ ] Result lock/unlock events captured
|
|
- [ ] Assignment policy compliance tracked
|
|
- [ ] Override counts reportable per Competition
|
|
- [ ] Cap violation metrics available in reports
|
|
|
|
### 9.11 Documentation & Training
|
|
- [ ] All architecture docs updated (this document, [02], [03], [04], [05], [06], [07])
|
|
- [ ] API documentation regenerated (tRPC router docs)
|
|
- [ ] User guide updated (admin, jury, applicant, mentor)
|
|
- [ ] Migration guide written (old → new terminology mapping)
|
|
- [ ] Training materials prepared for admins
|
|
|
|
---
|
|
|
|
## 10. Procedure-Level Migration Tables
|
|
|
|
These tables detail the exact tRPC procedure renames and signature changes required for each portal.
|
|
|
|
### 10.1 Jury Portal Procedures
|
|
|
|
| Current Procedure | New Procedure | Signature Change | Notes |
|
|
|-------------------|---------------|-----------------|-------|
|
|
| `stageAssignment.myAssignments` | `roundAssignment.myAssignments` | `{ stageId }` → `{ roundId, juryGroupId? }` | Filter by JuryGroup membership |
|
|
| `stageAssignment.getAssignmentDetail` | `roundAssignment.getAssignmentDetail` | `{ assignmentId }` → `{ assignmentId }` | Add JuryGroup context to response |
|
|
| `evaluation.getStageForm` | `evaluation.getRoundForm` | `{ stageId }` → `{ roundId }` | Return round-type-aware form |
|
|
| `evaluation.submitScore` | `evaluation.submitScore` | `{ stageId, projectId, ... }` → `{ roundId, projectId, ... }` | Add JuryGroup validation |
|
|
| `evaluation.checkStageWindow` | `evaluation.checkRoundWindow` | `{ stageId }` → `{ roundId }` | Return SubmissionWindow status |
|
|
| `evaluation.listStageEvaluations` | `evaluation.listRoundEvaluations` | `{ stageId }` → `{ roundId, juryGroupId? }` | Multi-jury filtering |
|
|
| `evaluation.declareCOI` | `evaluation.declareCOI` | `{ assignmentId }` → `{ assignmentId }` | No change (COI is on Assignment) |
|
|
| `file.listByProjectForStage` | `file.listByProjectForRound` | `{ projectId, stageId }` → `{ projectId, roundId }` | Return multi-window grouped files with labels |
|
|
| `live.getCurrentProject` | `live.getCurrentProject` | `{ stageId }` → `{ roundId }` | Require Jury 3 JuryGroup membership |
|
|
| `live.submitVote` | `live.submitVote` | `{ stageId, ... }` → `{ roundId, ... }` | Require Jury 3 membership |
|
|
| `live.getVotingStatus` | `live.getVotingStatus` | `{ stageId }` → `{ roundId }` | Add deliberation session linkage |
|
|
|
|
### 10.2 Applicant Portal Procedures
|
|
|
|
| Current Procedure | New Procedure | Signature Change | Notes |
|
|
|-------------------|---------------|-----------------|-------|
|
|
| `pipeline.getApplicantView` | `competition.getApplicantView` | `{ pipelineId }` → `{ competitionId }` | Return rounds with status, progress % |
|
|
| `stage.getApplicantTimeline` | `round.getApplicantTimeline` | `{ stageId }` → `{ roundId }` | Include SubmissionWindow deadlines |
|
|
| `stage.getRequirements` | `submissionWindow.getRequirements` | `{ stageId }` → `{ submissionWindowId }` | Window-based, not round-based |
|
|
| `applicant.getMyDashboard` | `applicant.getMyDashboard` | returns `openStages[]` → returns `openRounds[]` | Include SubmissionWindow status per round |
|
|
| `application.submit` | `application.submit` | `{ stageId, ... }` → `{ roundId, submissionWindowId, ... }` | Window-scoped submission |
|
|
| `file.uploadForStage` | `file.uploadForWindow` | `{ stageId, slotKey }` → `{ submissionWindowId, requirementId }` | Requirement-based validation |
|
|
| `file.getMyFiles` | `file.getMyFiles` | `{ stageId? }` → `{ submissionWindowId? }` | Multi-window grouping |
|
|
|
|
### 10.3 Component Renames
|
|
|
|
| Current Component | New Component | Used By |
|
|
|-------------------|---------------|---------|
|
|
| `StageTimeline` | `RoundTimeline` | Applicant journey, jury overview |
|
|
| `StageWindowBadge` | `RoundStatusBadge` | All portals — status indicators |
|
|
| `RequirementUploadSlot` | `SubmissionSlot` | Applicant document upload |
|
|
| `PipelineBreadcrumb` | `CompetitionBreadcrumb` | All portals — navigation |
|
|
| `StageConfigEditor` | `RoundConfigEditor` | Admin round configuration |
|
|
| `PipelineWizard` | `CompetitionWizard` | Admin competition creation |
|
|
|
|
### 10.4 Route Migrations
|
|
|
|
| Current Route | New Route | Portal |
|
|
|---------------|-----------|--------|
|
|
| `/admin/rounds/pipelines/*` | `/admin/competitions/*` | Admin |
|
|
| `/admin/rounds/pipeline/[id]/*` | `/admin/competitions/[id]/*` | Admin |
|
|
| `/jury/stages/[stageId]/*` | `/jury/rounds/[roundId]/*` | Jury |
|
|
| `/jury/stages/[stageId]/live/*` | `/jury/rounds/[roundId]/live/*` | Jury |
|
|
| `/jury/stages/[stageId]/deliberation/*` | `/jury/rounds/[roundId]/deliberation/*` | Jury (NEW) |
|
|
| `/applicant/pipeline/*` | `/applicant/competition/*` | Applicant |
|
|
| `/applicant/pipeline/[stageId]/documents/*` | `/applicant/competition/[roundId]/documents/*` | Applicant |
|
|
| `/vote/stage/[sessionId]/*` | `/vote/round/[sessionId]/*` | Public |
|
|
| `/live-scores/stage/[sessionId]/*` | `/live-scores/round/[sessionId]/*` | Public |
|
|
|
|
### 10.5 Background Job & Event Migrations
|
|
|
|
| Current Job/Event | New Job/Event | Changes |
|
|
|-------------------|---------------|---------|
|
|
| `evaluationReminder` cron | `evaluationReminder` cron | `stageId` → `roundId` in query and templates |
|
|
| `stage.transitioned` event | `round.transitioned` event | Event name + payload rename |
|
|
| `pipeline.created` event | `competition.created` event | Event name + payload rename |
|
|
| `pipeline.statusChanged` event | `competition.statusChanged` event | Event name + payload rename |
|
|
| `stage.assignment.completed` event | `round.assignment.completed` event | Event name + JuryGroup context in payload |
|
|
| `stage.filtering.completed` event | `round.filtering.completed` event | Event name rename |
|
|
| `stage-notifications` digest events | `round-notifications` digest events | All event keys rename |
|
|
| `award-eligibility-job` background | `award-eligibility-job` background | `stageId` → `roundId` in context |
|
|
|
|
---
|
|
|
|
## 11. Phased Rollout Recommendation
|
|
|
|
Given the scope, recommend phased implementation:
|
|
|
|
### Phase 1: Data Model & Core Routers (Weeks 1-2)
|
|
- Create Competition, Round, JuryGroup models
|
|
- Rename pipeline.ts → competition.ts, stage.ts → round.ts
|
|
- Create juryGroup.ts router
|
|
- Update database schema and migrations
|
|
- Update test factories
|
|
|
|
### Phase 2: Admin UX & Wizards (Weeks 3-4)
|
|
- Update Competition wizard
|
|
- Implement RoundType config editors
|
|
- Create JuryGroup management pages
|
|
- Update assignment management UI
|
|
|
|
### Phase 3: Services & Assignment Engine (Weeks 5-6)
|
|
- Rename stage-engine.ts → round-engine.ts
|
|
- Rename stage-assignment.ts → round-assignment.ts
|
|
- Implement new assignment policy engine
|
|
- Update AI services
|
|
|
|
### Phase 4: Deliberation & Results (Weeks 7-8)
|
|
- Create deliberation.ts service and router
|
|
- Implement result-lock.ts service
|
|
- Build deliberation admin panel
|
|
- Build deliberation jury interface
|
|
|
|
### Phase 5: Jury & Applicant UX (Weeks 9-10)
|
|
- Update jury pages (Round navigation, deliberation voting)
|
|
- Update applicant pages (Competition Journey, submission windows)
|
|
- Update mentor workspace
|
|
|
|
### Phase 6: Testing & Validation (Weeks 11-12)
|
|
- Integration testing
|
|
- UAT with admin/jury/applicant test users
|
|
- Performance testing
|
|
- Documentation finalization
|
|
|
|
---
|
|
|
|
## 11. Cross-Reference Map
|
|
|
|
This document integrates concepts from:
|
|
|
|
- **[02-data-model.md]** — Competition, Round, JuryGroup schemas
|
|
- **[03-competition-flow.md]** — 7-round flow, state transitions
|
|
- **[04-jury-groups-and-assignment-policy.md]** — JuryGroup management, caps, biases, assignment rules
|
|
- **[05-competition-wizard.md]** — Wizard UI for Competition setup
|
|
- **[06-round-configs.md]** — 7 typed RoundType configs, submission windows
|
|
- **[07-deliberation-and-result-lock.md]** — Deliberation sessions, quorum voting, result locking
|
|
|
|
---
|
|
|
|
**End of Platform Integration Matrix**
|