38 KiB
38 KiB
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
Pipelinereferences eliminated from codebase (code, comments, docs) - All
Stagereferences eliminated from codebase (code, comments, docs) - All
Trackreferences eliminated from codebase (code, comments, docs) Competitionmodel fully implemented with typed configsRoundmodel fully implemented with 7 RoundType configsJuryGroupmodel 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