letsbe
/
MOPC-App
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
MOPC-App/docs/unified-architecture-redesign/10-migration-strategy.md

28 KiB
Raw Blame History

Migration Strategy

Overview

The migration from Pipeline/Track/Stage to Competition/Round follows a 4-phase approach designed to minimize risk. New tables are added alongside old ones, data is backfilled, code is migrated, and finally old tables are dropped. Feature flags allow granular control of the transition.

Migration Phases

Phase 1: Schema Additions (Non-Breaking)

Add all new tables and enums alongside existing tables. No existing tables are modified or dropped.

New tables added:

  • Competition (parallel to Pipeline)
  • Round (parallel to Stage)
  • JuryGroup, JuryGroupMember
  • SubmissionWindow, SubmissionFileRequirement
  • RoundSubmissionVisibility
  • ProjectRoundState (parallel to ProjectStageState)
  • DeliberationSession, DeliberationVote, DeliberationResult, DeliberationParticipant
  • ResultLock, ResultUnlockEvent
  • MentorMessage
  • AssignmentIntent, AssignmentException
  • SubmissionPromotionEvent
  • AwardWinner

New enums added:

  • CompetitionStatus: DRAFT, ACTIVE, COMPLETED, ARCHIVED
  • RoundType: INTAKE, FILTERING, EVALUATION, SUBMISSION, MENTORING, LIVE_FINAL, DELIBERATION
  • RoundStatus: DRAFT, READY, ACTIVE, COMPLETED, SKIPPED
  • CapMode: HARD, SOFT, NONE
  • DeadlinePolicy: HARD, FLAG, GRACE
  • DeliberationMode: SINGLE_WINNER_VOTE, FULL_RANKING
  • DeliberationStatus: OPEN, VOTING, TALLYING, RUNOFF, LOCKED
  • TieBreakMethod: RUNOFF, ADMIN_DECIDES, SCORE_FALLBACK
  • DeliberationParticipantStatus: REQUIRED, ABSENT_EXCUSED, REPLACED, REPLACEMENT_ACTIVE
  • AwardRoutingMode: STAY_IN_MAIN, SEPARATE_POOL
  • AwardEligibilityMode: AI_SUGGESTED, MANUAL, ALL_ELIGIBLE, ROUND_BASED
  • WinnerDecisionMode: JURY_VOTE, SINGLE_JUDGE
  • MentorMessageRole: MENTOR, APPLICANT, ADMIN
  • PromotionSourceType: MENTOR_FILE, ADMIN_REPLACEMENT
  • AssignmentIntentSource: INVITE, ADMIN, SYSTEM

Rollback: Drop new tables and enums. Zero impact on existing system.

Phase 2: Data Migration (Backfill)

Backfill new tables from existing data. Old tables remain populated and active.

Mapping table:

Old Model New Model Mapping Logic
Pipeline Competition 1:1. Copy id, programId, name, status, settings → typed config split
Track (MAIN) (eliminated) Main track's stages become Competition's rounds directly
Track (AWARD) SpecialAward One SpecialAward per AWARD track
Stage Round 1:1. Copy type mapping (see below), order, status
Stage.configJson Round.configJson Parse and validate against typed schema for the round type
ProjectStageState ProjectRoundState Map stageId → roundId, trackId dropped
Judge assignments JuryGroupMember + assignments Create JuryGroups from distinct jury configurations
SpecialAward SpecialAward (enhanced) Add routing mode, eligibility mode fields

Stage type to Round type mapping:

Old StageType New RoundType Notes
INTAKE INTAKE Direct mapping
FILTER FILTERING Renamed for clarity
EVALUATION EVALUATION Direct mapping (used for both Jury 1 and Jury 2)
SELECTION (absorbed) Selection logic moves into evaluation round config
LIVE_FINAL LIVE_FINAL Direct mapping
RESULTS (absorbed) Results are part of the deliberation round
(new) SUBMISSION New round type for multi-round document collection
(new) MENTORING New round type for mentor collaboration
(new) DELIBERATION New round type replacing confirmation

Backfill script: A TypeScript migration script reads all existing Pipelines/Tracks/Stages and creates corresponding Competition/Round records. The script is idempotent (can be run multiple times safely).

Rollback: Delete backfilled data from new tables. Old tables unchanged.

Phase 3: Code Migration

Update all services, routers, and UI to use new models. Feature flags control which code path is active.

Feature flag strategy:

const FEATURE_FLAGS = {
  USE_COMPETITION_MODEL: false,     // Phase 3: switch to Competition/Round queries
  USE_JURY_GROUPS: false,           // Phase 3: switch to JuryGroup-based assignment
  USE_DELIBERATION: false,          // Phase 6: switch to new deliberation model
  USE_MENTOR_WORKSPACE: false,      // Phase 4: enable enhanced mentor features
  USE_SUBMISSION_WINDOWS: false,    // Phase 4: enable multi-round submissions
  HIDE_LEGACY_PIPELINE_UI: false,   // Phase 7: hide old Pipeline/Stage UI
}

Dual-read pattern: During transition, services can read from both old and new tables:

async function getCompetitionContext(id: string) {
  if (FEATURE_FLAGS.USE_COMPETITION_MODEL) {
    return getFromCompetitionModel(id)
  }
  return getFromPipelineModel(id) // legacy path
}

Router migration order:

  1. pipeline.ts → competition.ts (create new router, keep old active behind flag)
  2. stage.ts → round.ts (same approach)
  3. Remove track.ts (logic absorbed into competition + specialAward routers)
  4. Update assignment.ts to use JuryGroup model
  5. Update evaluation.ts to use Round model
  6. Add deliberation.ts (new router)
  7. Update mentor.ts with workspace features
  8. Update all UI pages to use new routers

Rollback: Flip feature flags back to legacy. Both code paths exist during this phase.

Phase 4: Cleanup (Point of No Return)

Drop old tables and remove legacy code paths. This is irreversible.

Tables dropped:

  • Pipeline
  • Track
  • Stage
  • ProjectStageState
  • Legacy configJson schemas

Enums dropped:

  • StageType (replaced by RoundType)
  • TrackKind (MAIN/AWARD — eliminated)
  • RoutingMode (SHARED/EXCLUSIVE — replaced by AwardRoutingMode)
  • WinnerProposalStatus (replaced by DeliberationStatus)
  • WinnerApprovalRole (replaced by DeliberationParticipantStatus)

Models dropped:

  • WinnerProposal (replaced by DeliberationSession)
  • WinnerApproval (replaced by DeliberationVote)

Code removed:

  • All feature flag conditionals (only new path remains)
  • All dual-read logic
  • All legacy router files
  • All legacy service files

Rollback: Restore from database backup. This phase should only be executed after thorough testing in Phases 1–3 and the burn-in period in Phase 8 of the implementation roadmap.

Data Mapping Reference

Complete Field Mapping

Old Field New Field Notes
Pipeline.id Competition.id Preserve IDs for foreign key consistency
Pipeline.programId Competition.programId Direct
Pipeline.name Competition.name Direct
Pipeline.description Competition.description Direct
Pipeline.status Competition.status Map to CompetitionStatus enum
Pipeline.settingsJson Competition.settingsJson Carry forward, validate
Stage.id Round.id Preserve IDs
Stage.trackId (dropped) No more track reference
Stage.pipelineId Round.competitionId Rename
Stage.type Round.type Map StageType → RoundType
Stage.order Round.order Direct
Stage.status Round.status Map to RoundStatus
Stage.configJson Round.configJson Validate against typed schema
Stage.startsAt Round.startsAt Direct
Stage.endsAt Round.endsAt Direct
ProjectStageState.stageId ProjectRoundState.roundId Rename
ProjectStageState.trackId (dropped) No more track
ProjectStageState.projectId ProjectRoundState.projectId Direct
ProjectStageState.state ProjectRoundState.state Map values

Additional FK Migrations (stageId → roundId)

These existing models have stageId foreign keys that must be renamed to roundId. They are NOT being replaced by new models — just renamed:

Model Old FK New FK Notes
AudienceVote stageId roundId Live voting records
COIDeclaration stageId roundId Conflict of interest declarations
ProjectStatusHistory stageId roundId Project state change log
DigestLog stageId roundId Notification digest tracking
MentorNote stageId roundId Mentor notes (legacy model, still used)
MentorMilestone stageId roundId Mentor milestone definitions
PartnerStageAccess stageId roundId Rename model to PartnerRoundAccess
LearningResource stageId roundId Learning resources linked to rounds
TaggingJob stageId roundId AI tagging job references
FilteringResult stageId roundId Filtering results per project
FilteringJob stageId roundId Filtering batch job records
EvaluationReminder stageId roundId Cron-triggered reminder records
GracePeriod stageId roundId Grace period extensions
LiveProgressCursor stageId roundId Live ceremony cursor
LiveVotingSession stageId roundId Live voting session

Migration approach: These are simple column renames with FK constraint updates. Run as a single migration after the main table additions in Phase 1.

New Field Additions (Non-Breaking)

These fields are added to existing new models during Phase 1. All have defaults, so they are non-breaking:

Model Field Type Default Purpose
Round purposeKey String? null Optional analytics tag
JuryGroupMember role JuryGroupMemberRole MEMBER Replaces isLead: Boolean
SubmissionWindow isLocked Boolean false Manual lock independent of window close
AssignmentIntent status AssignmentIntentStatus PENDING Proper lifecycle enum

Data migration for isLead → role: For existing data where isLead = true, set role = CHAIR. For isLead = false, set role = MEMBER. Drop isLead column after backfill.

New Enums (Phase 1)

Enum Values Used By
JuryGroupMemberRole CHAIR, MEMBER, OBSERVER JuryGroupMember.role
AssignmentIntentStatus PENDING, HONORED, OVERRIDDEN, EXPIRED, CANCELLED AssignmentIntent.status

Pre-Migration Checklist

Before starting Phase 1:

  • All type definitions finalized (Phase 0 of roadmap)
  • Database backup taken
  • Migration script written and tested on staging
  • Feature flags infrastructure in place
  • Rollback procedures documented and tested
  • All team members briefed on migration plan

Before starting Phase 4 (cleanup):

  • All feature flags pointing to new code paths
  • 72-hour burn-in period completed with zero critical errors
  • All release gates A–F passed (see 12-observability-and-release-gates.md)
  • Database backup taken (point-of-no-return backup)
  • Rollback from backup tested on staging

Timeline Alignment

Migration Phase Roadmap Phase When
Phase 1: Schema additions Implementation Phase 1 Weeks 2–3
Phase 2: Data backfill Implementation Phase 1 Weeks 3–4
Phase 3: Code migration Implementation Phases 3–6 Weeks 4–12
Phase 4: Cleanup Implementation Phase 7 Week 12–13

See 09-implementation-roadmap.md for the full implementation timeline.

System Inventory Appendix

Complete file-by-file migration effort estimate. Risk: L = Low (rename only), M = Medium (logic changes), H = High (rewrite).

Database & Schema (3 files, ~28 hours)

File Changes Risk
prisma/schema.prisma 40+ model/enum updates, 17+ FK renames H
prisma/seed.ts 300+ lines referencing Pipeline/Stage M
prisma/migrations/* New migration files for all schema changes M

tRPC Routers (24 files, ~104 hours)

File Changes Risk
src/server/routers/pipeline.ts Rename to competition.ts, update all queries H
src/server/routers/stage.ts Rename to round.ts, update all queries H
src/server/routers/track.ts Remove entirely, absorb into competition + specialAward H
src/server/routers/evaluation.ts stageId→roundId, add JuryGroup awareness M
src/server/routers/assignment.ts JuryGroup model, intent lifecycle H
src/server/routers/file.ts submissionWindowId, multi-round grouping M
src/server/routers/mentor.ts Workspace features, file promotion M
src/server/routers/award.ts competitionId, evaluationRoundId M
src/server/routers/audience-vote.ts stageId→roundId L
src/server/routers/coi.ts roundId awareness L
src/server/routers/notification.ts Stage event→round event mapping M
src/server/routers/cron.ts stageId→roundId in all scheduled jobs M
src/server/routers/deliberation.ts NEW — full deliberation router H
src/server/routers/result-lock.ts NEW — result lock/unlock procedures M
src/server/routers/jury-group.ts NEW — jury management procedures H
src/server/routers/submission-window.ts NEW — submission window CRUD M
Other 8 routers Indirect references (imports, type refs) L

Services (11 files, ~50 hours)

File Changes Risk
src/server/services/stage-engine.ts Rename to round-engine.ts, full rewrite H
src/server/services/stage-filtering.ts Rename to round-filtering.ts, roundId refs M
src/server/services/stage-assignment.ts Rename to round-assignment.ts, JuryGroup model H
src/server/services/stage-notifications.ts Rename to round-notifications.ts, event types M
src/server/services/live-control.ts stageId→roundId M
src/server/services/ai-filtering.ts stageId→roundId in AI context L
src/server/services/ai-assignment.ts JuryGroup awareness M
src/server/services/ai-evaluation-summary.ts roundId refs L
src/server/services/ai-tagging.ts stageId→roundId L
src/server/services/ai-award-eligibility.ts competitionId awareness L
src/server/services/anonymization.ts No changes expected L

Types & Libraries (6 files, ~32 hours)

File Changes Risk
src/types/pipeline-wizard.ts Complete rewrite → competition-wizard.ts H
src/types/wizard-config.ts Complete rewrite for round-based wizard H
src/lib/pipeline-defaults.ts Rename to competition-defaults.ts M
src/lib/pipeline-validation.ts Rename to competition-validation.ts M
src/lib/pipeline-conversions.ts Rename to competition-conversions.ts M
src/lib/stage-config-schema.ts Rename to round-config-schema.ts, Zod schemas M

Admin Pages (35+ files, ~52 hours)

File Pattern Count Changes Risk
src/app/(admin)/admin/pipelines/* 8 pages Rename to competitions/* H
src/app/(admin)/admin/stages/* 5 pages Rename to rounds/* H
Pipeline wizard components 6 Full rewrite for competition model H
Stage config components 8 Update to round-type configs M
Other admin components 10 Indirect references L

Jury Pages (16 files, ~18 hours)

File Pattern Count Changes Risk
src/app/(jury)/jury/stages/[stageId]/* 6 pages Rename to rounds/[roundId]/* M
Jury evaluation components 4 roundId, JuryGroup filtering M
Jury shared components 6 Breadcrumbs, timeline, badges L

Applicant Pages (8 files, ~12 hours)

File Pattern Count Changes Risk
src/app/(applicant)/applicant/pipeline/* 4 pages Rename to competition/* H
Applicant components 4 StageTimeline→RoundTimeline M

Tests (13+ files, ~45 hours)

File Changes Risk
tests/helpers.ts Update all factories M
tests/unit/stage-engine.test.ts Rename + update references M
tests/unit/stage-filtering.test.ts Rename + update M
tests/unit/stage-assignment.test.ts Rename + add JuryGroup tests M
tests/integration/pipeline-crud.test.ts Rename to competition-crud M
tests/integration/evaluation-flow.test.ts Round model, multi-round docs M
New test files (8 files) See 11-testing-and-qa.md H

Infrastructure (4 files, ~11 hours)

File Changes Risk
docker/docker-entrypoint.sh Migration flow update L
Cron job configs stageId→roundId in scheduled tasks M
Webhook event definitions Stage→Round event names M
Email templates Stage references in copy L

Totals

Category Files Est. Hours
Database & Schema 3 28
tRPC Routers 24 104
Services 11 50
Types & Libraries 6 32
Admin UI 35+ 52
Jury UI 16 18
Applicant UI 8 12
Tests 13+ 45
Infrastructure 4 11
Total 120+ ~352

Note: Conservative estimates for one developer. Parallel frontend/backend work reduces calendar time. Critical path: Schema → Services → Routers → UI.

Appendix: System Inventory — File-by-File Migration Map

Complete inventory of all files requiring changes, grouped by category with effort estimates.

Prisma & Database (1 file, HIGH effort)

File Changes Required Effort
prisma/schema.prisma 40+ model/enum updates, 17+ FK renames (stageId→roundId), add new enums, add new fields HIGH

tRPC Routers (24 files)

File Change Type Effort
src/server/routers/pipeline.ts Rename → competition.ts + all procedures HIGH
src/server/routers/stage.ts Rename → round.ts + all procedures HIGH
src/server/routers/track.ts Remove — logic absorbed into competition + specialAward HIGH
src/server/routers/evaluation.ts Update to use Round model, roundId params, JuryGroup queries HIGH
src/server/routers/assignment.ts Update to use JuryGroup model, roundId params HIGH
src/server/routers/file.ts Update listByProjectForStage → listByProjectForRound, multi-round grouping MEDIUM
src/server/routers/mentor.ts Add workspace features, file promotion procedures MEDIUM
src/server/routers/applicant.ts Update getMyDashboard (openStages→openRounds), pipeline view MEDIUM
src/server/routers/application.ts Update stage mode config → round-type-aware config MEDIUM
src/server/routers/live-control.ts Update stageId → roundId in cursor management MEDIUM
src/server/routers/award.ts Update to use competitionId, enhanced routing modes MEDIUM
src/server/routers/notification.ts Update event keys from stageId → roundId LOW
src/server/routers/analytics.ts Update stage references → round references LOW
src/server/routers/digest.ts Update stageId references LOW
src/server/routers/coi.ts Update stageId → roundId in COI declarations LOW
src/server/routers/audit.ts Update event type names (stage.* → round.*) LOW
New: src/server/routers/deliberation.ts New router for deliberation lifecycle HIGH
New: src/server/routers/result-lock.ts New router for result locking/unlocking MEDIUM
New: src/server/routers/jury-group.ts New router for jury group management MEDIUM
New: src/server/routers/submission-window.ts New router for submission window management MEDIUM

Services (11 files)

File Change Type Effort
src/server/services/stage-engine.ts Rename → round-engine.ts, update all type references HIGH
src/server/services/stage-filtering.ts Rename → round-filtering.ts, update to RoundType.FILTERING HIGH
src/server/services/stage-assignment.ts Rename → round-assignment.ts, add JuryGroup-based assignment HIGH
src/server/services/stage-notifications.ts Rename → round-notifications.ts, update event keys MEDIUM
src/server/services/live-control.ts Update stageId → roundId in cursor management MEDIUM
src/server/services/ai-filtering.ts Update stage references → round references LOW
src/server/services/ai-assignment.ts Update to use JuryGroup model MEDIUM
src/server/services/ai-evaluation-summary.ts Update stage references LOW
New: src/server/services/deliberation-engine.ts Deliberation lifecycle, vote aggregation, Borda count HIGH
New: src/server/services/result-lock.ts Lock/unlock with audit trail MEDIUM
New: src/server/services/mentor-workspace.ts Messaging, file management, promotion MEDIUM

Types & Libraries (6 files)

File Change Type Effort
src/types/pipeline-wizard.ts Rewrite → competition-wizard.ts with Competition/Round types HIGH
src/types/wizard-config.ts Rewrite → update all Stage→Round type references HIGH
src/lib/pipeline-defaults.ts Rename → competition-defaults.ts, update all defaults MEDIUM
src/lib/pipeline-validation.ts Rename → competition-validation.ts MEDIUM
src/lib/pipeline-conversions.ts Rename → competition-conversions.ts MEDIUM
src/lib/stage-config-schema.ts Rename → round-config-schema.ts, update to 7 typed Zod schemas HIGH

Admin Pages (13+ files)

File Change Type Effort
src/app/(admin)/pipelines/* Rename → competitions/*, update all router calls HIGH
src/app/(admin)/pipelines/[id]/stages/* Rename → competitions/[id]/rounds/* HIGH
src/app/(admin)/pipelines/[id]/tracks/* Remove — track UI eliminated MEDIUM
New: src/app/(admin)/competitions/[id]/juries/* New jury management section (3 pages) HIGH
New: src/app/(admin)/competitions/[id]/deliberation/* New deliberation management HIGH
New: src/app/(admin)/competitions/[id]/results/* New results & locks page MEDIUM
New: src/app/(admin)/competitions/[id]/submission-windows/* New submission window management MEDIUM

Jury Pages (6 files)

File Change Type Effort
src/app/(jury)/stages/[stageId]/* Rename → rounds/[roundId]/* (6 routes) HIGH
src/app/(jury)/stages/[stageId]/evaluate/* Update to multi-round doc viewing, JuryGroup context HIGH
src/app/(jury)/stages/[stageId]/compare/* Update cross-round project comparison MEDIUM
New: src/app/(jury)/rounds/[roundId]/deliberation/* Juror deliberation voting interface HIGH

Applicant Pages (8 files)

File Change Type Effort
src/app/(applicant)/pipeline/* Rename → competition/*, redesign progress visualization HIGH
src/app/(applicant)/pipeline/[stageId]/documents/* Rename → multi-round aware doc upload with read-only enforcement HIGH
src/app/(applicant)/pipeline/[stageId]/status/* Rename → round-based status with cross-round visibility MEDIUM

Shared Components (24+ files)

Component Change Effort
StageTimeline Rename → RoundTimeline, update props from stageId to roundId MEDIUM
StageWindowBadge Rename → RoundStatusBadge LOW
RequirementUploadSlot Update stageId prop → roundId + submissionWindowId LOW
PipelineWizard Rename → CompetitionWizard, rewrite step flow HIGH
StageSidebar Rename → RoundSidebar LOW
StageConfigEditor Rename → RoundConfigEditor, update to typed Zod schemas HIGH
TrackSelector Remove LOW
Breadcrumb components Update Pipeline→Track→Stage to Competition→Round LOW

Infrastructure & Config (5 files)

File Change Type Effort
prisma/seed.ts Update all Pipeline/Stage creation to Competition/Round (300+ lines) HIGH
docker/docker-entrypoint.sh Update migration flow for new tables LOW
tests/helpers.ts Add new factory functions for Competition/Round/JuryGroup/etc. MEDIUM
.env.example Add any new feature flag env vars LOW
CLAUDE.md Update architecture documentation LOW

Background Jobs / Cron (3 files)

File Change Type Effort
src/server/cron/evaluation-reminders.ts Update stageId → roundId in deadline checks LOW
src/server/cron/digest-sender.ts Update stageId references in digest generation LOW
src/server/cron/ai-tagging.ts Update stageId → roundId in tagging jobs LOW

Test Files (12 files)

File Change Type Effort
tests/unit/stage-engine.test.ts Rename → round-engine.test.ts, update all references MEDIUM
tests/unit/stage-filtering.test.ts Rename → round-filtering.test.ts MEDIUM
tests/unit/stage-assignment.test.ts Rename, add JuryGroup-based tests, cap mode tests MEDIUM
tests/integration/pipeline-crud.test.ts Rename → competition-crud.test.ts MEDIUM
tests/integration/evaluation-flow.test.ts Update to Round model, multi-round doc visibility MEDIUM
New: tests/unit/policy-resolution.test.ts 5-layer policy precedence tests HIGH
New: tests/unit/borda-count.test.ts Borda count aggregation tests LOW
New: tests/unit/deliberation-tally.test.ts Vote tallying for both modes MEDIUM
New: tests/unit/config-validation.test.ts All 7 Zod schema validation tests MEDIUM
New: tests/integration/deliberation-flow.test.ts Full deliberation lifecycle HIGH
New: tests/integration/mentor-workspace.test.ts Messaging, files, comments, promotion MEDIUM
New: tests/e2e/monaco-full-flow.test.ts Complete 8-round simulation HIGH

Webhook & Event Mapping

Old Event Type New Event Type
stage.transitioned round.transitioned
stage.opened round.opened
stage.closed round.closed
pipeline.created competition.created
pipeline.statusChanged competition.statusChanged
stage.assignmentCompleted round.assignmentCompleted
stage.evaluationCompleted round.evaluationCompleted
stage.filteringCompleted round.filteringCompleted
(new) deliberation.sessionCreated
(new) deliberation.voteSubmitted
(new) deliberation.resultLocked
(new) deliberation.resultUnlocked
(new) mentoring.filePromoted
(new) submission.windowOpened
(new) submission.windowClosed

Effort Summary

Category Files New Modified Removed Estimated Hours
Prisma & DB 1 0 1 0 16–24
tRPC Routers 24 4 16 1 40–60
Services 11 3 8 0 30–40
Types & Libs 6 0 6 0 16–24
Admin Pages 13+ 4 9 1 30–40
Jury Pages 6+ 1 5 0 20–30
Applicant Pages 8 0 8 0 16–24
Components 24+ 0 20+ 2+ 20–30
Infrastructure 5 0 5 0 8–12
Background Jobs 3 0 3 0 4–6
Tests 12 7 5 0 30–40
Total 113+ 19 86+ 4+ 230–330