From 6ca39c976bf240ed7b6fd02362a24b986bb318ed Mon Sep 17 00:00:00 2001 From: Matt Date: Sun, 15 Feb 2026 23:04:15 +0100 Subject: [PATCH] Competition/Round architecture: full platform rewrite (Phases 1-9) Replace Pipeline/Stage system with Competition/Round architecture. New schema: Competition, Round (7 types), JuryGroup, AssignmentPolicy, ProjectRoundState, DeliberationSession, ResultLock, SubmissionWindow. New services: round-engine, round-assignment, deliberation, result-lock, submission-manager, competition-context, ai-prompt-guard. Full admin/jury/applicant/mentor UI rewrite. AI prompt hardening with structured prompts, retry logic, and injection detection. All legacy pipeline/stage code removed. 4 new migrations + seed aligned. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 507 +-- .../00-executive-summary.md | 201 + .../01-current-system-audit.md | 591 +++ .../02-gap-analysis.md | 786 ++++ .../03-data-model.md | 1139 ++++++ .../04-round-intake.md | 1539 ++++++++ .../05-round-filtering.md | 1438 +++++++ .../06-round-evaluation.md | 698 ++++ .../07-round-submission.md | 2053 ++++++++++ .../08-round-mentoring.md | 499 +++ .../09-round-live-finals.md | 660 ++++ .../10-round-confirmation.md | 1299 +++++++ .../11-special-awards.md | 965 +++++ .../12-jury-groups.md | 960 +++++ .../13-notifications-deadlines.md | 2898 ++++++++++++++ .../14-ai-services.md | 3384 +++++++++++++++++ .../15-admin-ui.md | 761 ++++ .../16-jury-ui.md | 1806 +++++++++ .../17-applicant-ui.md | 1787 +++++++++ .../18-mentor-ui.md | 1760 +++++++++ .../19-api-router-reference.md | 1734 +++++++++ .../20-service-layer-changes.md | 2185 +++++++++++ .../21-migration-strategy.md | 2972 +++++++++++++++ .../22-integration-map.md | 1907 ++++++++++ .../23-implementation-sequence.md | 2580 +++++++++++++ .../01-current-platform-architecture-audit.md | 146 + .../02-monaco-flow-target-architecture.md | 285 ++ ...p-analysis-and-simplification-decisions.md | 98 + ...ified-domain-model-and-config-contracts.md | 317 ++ .../05-platform-wide-integration-matrix.md | 174 + ...plementation-roadmap-and-migration-plan.md | 193 + ...testing-observability-and-release-gates.md | 157 + .../08-open-questions-for-flow-owners.md | 88 + .../09-appendix-system-inventory.md | 153 + .../10-monaco-reference-configuration.md | 162 + .../README.md | 65 + .../README.md | 68 - .../flowcharts/dependency-refit-map.md | 15 - .../flowcharts/end-to-end-pipeline.md | 25 - .../flowcharts/live-stage-controller.md | 15 - .../flowcharts/main-vs-award-routing.md | 17 - .../flowcharts/override-audit-flow.md | 14 - .../master-implementation-plan.md | 95 - .../acceptance-gates.md | 13 - .../phase-00-contract-freeze/overview.md | 35 - .../phase-00-contract-freeze/tasks.md | 31 - .../acceptance-gates.md | 14 - .../migration-cutover-plan.md | 48 - .../overview.md | 27 - .../schema-spec.md | 59 - .../tasks.md | 24 - .../acceptance-gates.md | 14 - .../assignment-spec.md | 43 - .../filtering-routing-spec.md | 55 - .../live-control-spec.md | 32 - .../overview.md | 23 - .../stage-engine-spec.md | 46 - .../phase-02-backend-orchestration/tasks.md | 30 - .../acceptance-gates.md | 12 - .../advanced-editor-spec.md | 34 - .../form-behavior-and-validation.md | 30 - .../overview.md | 23 - .../phase-03-admin-control-plane-ux/tasks.md | 19 - .../wizard-ia.md | 78 - .../acceptance-gates.md | 11 - .../applicant-experience-spec.md | 29 - .../audience-live-vote-spec.md | 24 - .../jury-experience-spec.md | 26 - .../phase-04-participant-journeys/overview.md | 21 - .../phase-04-participant-journeys/tasks.md | 21 - .../acceptance-gates.md | 10 - .../award-track-and-governance-spec.md | 39 - .../overview.md | 21 - .../tasks.md | 7 - .../acceptance-gates.md | 12 - .../module-refit-map.md | 26 - .../overview.md | 21 - .../symbol-sweep-checklist.md | 13 - .../tasks.md | 8 - .../acceptance-gates.md | 13 - .../phase-07-validation-release/overview.md | 21 - .../performance-and-resilience-plan.md | 27 - .../phase-07-validation-release/runbook.md | 39 - .../phase-07-validation-release/tasks.md | 7 - .../shared/api-contracts.md | 97 - .../shared/authz-matrix.md | 32 - .../shared/decision-log.md | 16 - .../shared/dependency-refit-inventory.md | 75 - .../shared/domain-model.md | 156 - .../shared/phase-gate-traceability.md | 32 - .../shared/program-charter.md | 43 - .../shared/release-evidence-template.md | 65 - .../shared/risk-register.md | 17 - .../shared/test-matrix.md | 57 - .../phase-0-validation/domain-model-review.md | 661 ---- .../00-README.md | 61 + .../01-architecture-and-decisions.md | 283 ++ .../02-data-model.md | 1801 +++++++++ .../03-competition-flow.md | 2949 ++++++++++++++ .../04-jury-groups-and-assignment-policy.md | 349 ++ .../05-special-awards.md | 248 ++ .../06-mentoring-and-document-lifecycle.md | 315 ++ .../07-live-finals-and-deliberation.md | 1431 +++++++ .../08-platform-integration-matrix.md | 503 +++ .../09-implementation-roadmap.md | 247 ++ .../10-migration-strategy.md | 565 +++ .../11-testing-and-qa.md | 303 ++ .../12-observability-and-release-gates.md | 322 ++ .../13-open-questions-and-governance.md | 360 ++ next.config.ts | 35 + prisma/integrity-checks.ts | 19 +- .../20260130000000_init/migration.sql | 1818 ++++----- .../migration.sql | 1100 +++--- .../migration.sql | 182 +- .../migration.sql | 82 +- .../migration.sql | 26 +- .../migration.sql | 60 +- .../migration.sql | 258 +- .../migration.sql | 4 +- .../migration.sql | 198 +- .../migration.sql | 572 +++ .../migration.sql | 3 + .../migration.sql | 300 ++ .../migration.sql | 31 + prisma/schema.prisma | 1049 +++-- prisma/seed.ts | 761 ++-- src/app/(admin)/admin/awards/[id]/page.tsx | 5 +- .../[competitionId]/assignments/page.tsx | 170 + .../[competitionId]/awards/[awardId]/page.tsx | 154 + .../[competitionId]/awards/new/page.tsx | 164 + .../[competitionId]/awards/page.tsx | 104 + .../deliberation/[sessionId]/page.tsx | 224 ++ .../[competitionId]/deliberation/page.tsx | 317 ++ .../juries/[juryGroupId]/page.tsx | 139 + .../[competitionId]/juries/page.tsx | 187 + .../[competitionId]/live/[roundId]/page.tsx | 37 + .../[competitionId]/rounds/[roundId]/page.tsx | 178 + .../(admin)/admin/competitions/[id]/page.tsx | 531 +++ .../(admin)/admin/competitions/new/page.tsx | 307 ++ .../pipelines => competitions}/page.tsx | 402 +- src/app/(admin)/admin/dashboard-content.tsx | 112 +- src/app/(admin)/admin/members/invite/page.tsx | 42 +- src/app/(admin)/admin/messages/page.tsx | 20 +- .../programs/[id]/apply-settings/page.tsx | 2 +- src/app/(admin)/admin/programs/[id]/page.tsx | 11 +- src/app/(admin)/admin/programs/page.tsx | 38 +- .../admin/projects/[id]/mentor/page.tsx | 5 + src/app/(admin)/admin/projects/[id]/page.tsx | 30 +- .../(admin)/admin/projects/import/page.tsx | 42 +- src/app/(admin)/admin/projects/new/page.tsx | 8 +- src/app/(admin)/admin/projects/page.tsx | 137 +- src/app/(admin)/admin/projects/pool/page.tsx | 14 +- .../admin/projects/project-filters.tsx | 20 +- src/app/(admin)/admin/reports/page.tsx | 54 +- src/app/(admin)/admin/reports/stages/page.tsx | 671 ---- .../admin/rounds/new-pipeline/page.tsx | 352 -- .../rounds/pipeline/[id]/advanced/page.tsx | 12 - .../admin/rounds/pipeline/[id]/edit/page.tsx | 11 - .../admin/rounds/pipeline/[id]/page.tsx | 675 ---- .../rounds/pipeline/[id]/wizard/page.tsx | 410 -- .../competitions/[windowId]/page.tsx | 180 + .../applicant/competitions/page.tsx | 124 + .../(applicant)/applicant/documents/page.tsx | 30 +- src/app/(applicant)/applicant/page.tsx | 8 +- .../pipeline/[stageId]/documents/page.tsx | 167 - .../pipeline/[stageId]/status/page.tsx | 278 -- .../(applicant)/applicant/pipeline/page.tsx | 267 -- src/app/(applicant)/error.tsx | 72 + src/app/(auth)/onboarding/page.tsx | 147 +- .../jury/competitions/[roundId]/live/page.tsx | 153 + .../jury/competitions/[roundId]/page.tsx | 118 + .../projects/[projectId]/evaluate/page.tsx | 252 ++ .../[roundId]/projects/[projectId]/page.tsx | 149 + .../deliberation/[sessionId]/page.tsx | 149 + src/app/(jury)/jury/competitions/page.tsx | 116 + src/app/(jury)/jury/page.tsx | 164 +- .../stages/[stageId]/assignments/page.tsx | 368 -- .../jury/stages/[stageId]/compare/page.tsx | 311 -- .../jury/stages/[stageId]/live/page.tsx | 269 -- .../projects/[projectId]/evaluate/page.tsx | 199 - .../projects/[projectId]/evaluation/page.tsx | 235 -- .../[stageId]/projects/[projectId]/page.tsx | 217 -- src/app/(jury)/jury/stages/page.tsx | 247 -- .../mentor/workspace/[projectId]/page.tsx | 141 + src/app/(mentor)/mentor/workspace/page.tsx | 128 + src/app/(observer)/observer/reports/page.tsx | 52 +- src/app/(public)/apply/[slug]/page.tsx | 8 +- .../apply/edition/[programSlug]/page.tsx | 2 +- .../live-scores/stage/[sessionId]/page.tsx | 267 -- .../[id]/submission-detail-client.tsx | 2 +- src/app/(public)/vote/[sessionId]/page.tsx | 4 +- .../vote/competition/[roundId]/page.tsx | 88 + .../(public)/vote/stage/[sessionId]/page.tsx | 215 -- .../api/sse/stage-live/[sessionId]/route.ts | 216 -- .../assignment/assignment-preview-sheet.tsx | 181 + .../admin/assignment/coverage-report.tsx | 98 + .../competition/competition-timeline.tsx | 156 + .../admin/competition/round-config-form.tsx | 248 ++ .../competition/sections/basics-section.tsx | 159 + .../sections/jury-groups-section.tsx | 150 + .../competition/sections/review-section.tsx | 213 ++ .../competition/sections/rounds-section.tsx | 195 + .../deliberation/admin-override-dialog.tsx | 144 + .../admin/deliberation/results-panel.tsx | 179 + .../admin/evaluation-summary-card.tsx | 13 +- .../admin/file-requirements-editor.tsx | 18 +- .../admin/jury/add-member-dialog.tsx | 168 + .../admin/jury/jury-members-table.tsx | 156 + .../admin/live/live-control-panel.tsx | 194 + .../admin/live/project-navigator-grid.tsx | 55 + src/components/admin/pdf-report.tsx | 6 +- .../pipeline/award-governance-editor.tsx | 358 -- .../admin/pipeline/filtering-rules-editor.tsx | 379 -- .../admin/pipeline/pipeline-flowchart.tsx | 276 -- .../admin/pipeline/pipeline-visualization.tsx | 121 - .../admin/pipeline/predicate-builder.tsx | 450 --- .../pipeline/sections/assignment-section.tsx | 243 -- .../pipeline/sections/awards-section.tsx | 254 -- .../pipeline/sections/basics-section.tsx | 99 - .../pipeline/sections/filtering-section.tsx | 479 --- .../pipeline/sections/intake-section.tsx | 289 -- .../pipeline/sections/live-finals-section.tsx | 158 - .../pipeline/sections/main-track-section.tsx | 228 -- .../sections/notifications-section.tsx | 161 - .../pipeline/sections/results-section.tsx | 93 - .../pipeline/sections/review-section.tsx | 314 -- .../pipeline/sections/selection-section.tsx | 179 - .../admin/pipeline/stage-config-editor.tsx | 416 -- .../admin/pipeline/stage-detail-sheet.tsx | 178 - .../stage-panels/evaluation-panel.tsx | 136 - .../pipeline/stage-panels/filter-panel.tsx | 184 - .../pipeline/stage-panels/intake-panel.tsx | 135 - .../stage-panels/live-final-panel.tsx | 173 - .../pipeline/stage-panels/results-panel.tsx | 120 - .../pipeline/stage-panels/selection-panel.tsx | 259 -- .../pipeline/stage-transitions-editor.tsx | 344 -- .../admin/result/result-lock-controls.tsx | 239 ++ .../admin/round/project-states-table.tsx | 33 + .../admin/round/submission-window-manager.tsx | 291 ++ .../applicant/competition-timeline.tsx | 144 + src/components/applicant/file-upload-slot.tsx | 181 + .../charts/cross-round-comparison.tsx | 6 +- .../forms/apply-steps/step-contact.tsx | 4 +- .../forms/apply-steps/step-project.tsx | 2 +- src/components/forms/apply-wizard-dynamic.tsx | 6 +- src/components/forms/evaluation-form.tsx | 2 +- .../jury/collapsible-files-section.tsx | 6 +- .../jury/deliberation-ranking-form.tsx | 181 + src/components/jury/live-voting-form.tsx | 124 + .../jury/multi-window-doc-viewer.tsx | 145 + src/components/jury/project-files-section.tsx | 25 +- src/components/layouts/admin-sidebar.tsx | 12 +- src/components/layouts/applicant-nav.tsx | 4 +- src/components/layouts/jury-nav.tsx | 16 +- .../mentor/file-promotion-panel.tsx | 191 + src/components/mentor/workspace-chat.tsx | 179 + .../observer/observer-dashboard-content.tsx | 86 +- src/components/public/audience-vote-card.tsx | 51 + src/components/shared/export-pdf-button.tsx | 6 +- src/components/shared/file-upload.tsx | 32 +- src/components/shared/file-viewer.tsx | 26 +- .../shared/requirement-upload-slot.tsx | 24 +- src/components/shared/stage-breadcrumb.tsx | 47 - src/components/shared/stage-timeline.tsx | 205 - src/components/shared/stage-window-badge.tsx | 133 - src/hooks/use-pipeline-inline-edit.ts | 46 - src/lib/feature-flags.ts | 49 + src/lib/pipeline-conversions.ts | 67 - src/lib/pipeline-defaults.ts | 145 - src/lib/pipeline-validation.ts | 149 - src/lib/stage-config-schema.ts | 457 --- src/lib/wizard-config.ts | 213 +- src/server/routers/_app.ts | 37 +- src/server/routers/analytics.ts | 444 +-- src/server/routers/applicant.ts | 60 +- src/server/routers/application.ts | 132 +- src/server/routers/assignment.ts | 169 +- src/server/routers/assignmentIntent.ts | 82 + src/server/routers/assignmentPolicy.ts | 113 + src/server/routers/award.ts | 571 +-- src/server/routers/cohort.ts | 42 +- src/server/routers/competition.ts | 252 ++ src/server/routers/dashboard.ts | 50 +- src/server/routers/decision.ts | 18 +- src/server/routers/deliberation.ts | 244 ++ src/server/routers/evaluation.ts | 164 +- src/server/routers/export.ts | 64 +- src/server/routers/file.ts | 395 +- src/server/routers/filtering.ts | 148 +- src/server/routers/gracePeriod.ts | 34 +- src/server/routers/juryGroup.ts | 348 ++ src/server/routers/live-voting.ts | 72 +- src/server/routers/live.ts | 180 +- src/server/routers/mentor.ts | 157 +- src/server/routers/message.ts | 18 +- src/server/routers/pipeline.ts | 1091 ------ src/server/routers/program.ts | 126 +- src/server/routers/project-pool.ts | 42 +- src/server/routers/project.ts | 42 +- src/server/routers/resultLock.ts | 100 + src/server/routers/round.ts | 457 +++ src/server/routers/roundAssignment.ts | 117 + src/server/routers/roundEngine.ts | 143 + src/server/routers/stage.ts | 966 ----- src/server/routers/stageAssignment.ts | 632 --- src/server/routers/stageFiltering.ts | 514 --- src/server/routers/user.ts | 215 +- src/server/services/ai-assignment.ts | 100 +- src/server/services/ai-award-eligibility.ts | 94 +- src/server/services/ai-evaluation-summary.ts | 125 +- src/server/services/ai-filtering.ts | 96 +- src/server/services/ai-prompt-guard.ts | 167 + src/server/services/ai-shortlist.ts | 284 ++ src/server/services/ai-tagging.ts | 10 +- src/server/services/assignment-intent.ts | 290 ++ src/server/services/assignment-policy.ts | 262 ++ src/server/services/competition-context.ts | 160 + src/server/services/deliberation.ts | 716 ++++ src/server/services/email-digest.ts | 28 +- src/server/services/evaluation-reminders.ts | 52 +- src/server/services/in-app-notification.ts | 4 +- src/server/services/live-control.ts | 100 +- src/server/services/mentor-workspace.ts | 314 ++ src/server/services/result-lock.ts | 284 ++ src/server/services/round-assignment.ts | 568 +++ src/server/services/round-engine.ts | 510 +++ src/server/services/smart-assignment.ts | 54 +- src/server/services/stage-assignment.ts | 776 ---- src/server/services/stage-engine.ts | 464 --- src/server/services/stage-filtering.ts | 646 ---- src/server/services/stage-notifications.ts | 463 --- src/server/services/submission-manager.ts | 358 ++ src/types/competition-configs.ts | 330 ++ src/types/competition.ts | 171 + src/types/pipeline-wizard.ts | 137 - tests/helpers.ts | 163 +- tests/integration/assignment-preview.test.ts | 92 - tests/integration/cohort-voting.test.ts | 156 - tests/integration/decision-audit.test.ts | 115 - tests/integration/live-runtime.test.ts | 139 - tests/integration/pipeline-crud.test.ts | 145 - tests/integration/stage-config.test.ts | 166 - tests/unit/assignment-policy.test.ts | 382 ++ tests/unit/award-governance.test.ts | 154 - tests/unit/live-control.test.ts | 188 - tests/unit/override-validation.test.ts | 103 - tests/unit/stage-assignment.test.ts | 170 - tests/unit/stage-engine.test.ts | 175 - tests/unit/stage-filtering.test.ts | 173 - 349 files changed, 69938 insertions(+), 28767 deletions(-) create mode 100644 docs/claude-architecture-redesign/00-executive-summary.md create mode 100644 docs/claude-architecture-redesign/01-current-system-audit.md create mode 100644 docs/claude-architecture-redesign/02-gap-analysis.md create mode 100644 docs/claude-architecture-redesign/03-data-model.md create mode 100644 docs/claude-architecture-redesign/04-round-intake.md create mode 100644 docs/claude-architecture-redesign/05-round-filtering.md create mode 100644 docs/claude-architecture-redesign/06-round-evaluation.md create mode 100644 docs/claude-architecture-redesign/07-round-submission.md create mode 100644 docs/claude-architecture-redesign/08-round-mentoring.md create mode 100644 docs/claude-architecture-redesign/09-round-live-finals.md create mode 100644 docs/claude-architecture-redesign/10-round-confirmation.md create mode 100644 docs/claude-architecture-redesign/11-special-awards.md create mode 100644 docs/claude-architecture-redesign/12-jury-groups.md create mode 100644 docs/claude-architecture-redesign/13-notifications-deadlines.md create mode 100644 docs/claude-architecture-redesign/14-ai-services.md create mode 100644 docs/claude-architecture-redesign/15-admin-ui.md create mode 100644 docs/claude-architecture-redesign/16-jury-ui.md create mode 100644 docs/claude-architecture-redesign/17-applicant-ui.md create mode 100644 docs/claude-architecture-redesign/18-mentor-ui.md create mode 100644 docs/claude-architecture-redesign/19-api-router-reference.md create mode 100644 docs/claude-architecture-redesign/20-service-layer-changes.md create mode 100644 docs/claude-architecture-redesign/21-migration-strategy.md create mode 100644 docs/claude-architecture-redesign/22-integration-map.md create mode 100644 docs/claude-architecture-redesign/23-implementation-sequence.md create mode 100644 docs/codex-architecture-redesign-docs/01-current-platform-architecture-audit.md create mode 100644 docs/codex-architecture-redesign-docs/02-monaco-flow-target-architecture.md create mode 100644 docs/codex-architecture-redesign-docs/03-gap-analysis-and-simplification-decisions.md create mode 100644 docs/codex-architecture-redesign-docs/04-unified-domain-model-and-config-contracts.md create mode 100644 docs/codex-architecture-redesign-docs/05-platform-wide-integration-matrix.md create mode 100644 docs/codex-architecture-redesign-docs/06-implementation-roadmap-and-migration-plan.md create mode 100644 docs/codex-architecture-redesign-docs/07-testing-observability-and-release-gates.md create mode 100644 docs/codex-architecture-redesign-docs/08-open-questions-for-flow-owners.md create mode 100644 docs/codex-architecture-redesign-docs/09-appendix-system-inventory.md create mode 100644 docs/codex-architecture-redesign-docs/10-monaco-reference-configuration.md create mode 100644 docs/codex-architecture-redesign-docs/README.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/README.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/flowcharts/dependency-refit-map.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/flowcharts/end-to-end-pipeline.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/flowcharts/live-stage-controller.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/flowcharts/main-vs-award-routing.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/flowcharts/override-audit-flow.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/master-implementation-plan.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-00-contract-freeze/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-00-contract-freeze/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-00-contract-freeze/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-01-schema-runtime-foundation/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-01-schema-runtime-foundation/migration-cutover-plan.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-01-schema-runtime-foundation/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-01-schema-runtime-foundation/schema-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-01-schema-runtime-foundation/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-02-backend-orchestration/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-02-backend-orchestration/assignment-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-02-backend-orchestration/filtering-routing-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-02-backend-orchestration/live-control-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-02-backend-orchestration/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-02-backend-orchestration/stage-engine-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-02-backend-orchestration/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-03-admin-control-plane-ux/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-03-admin-control-plane-ux/advanced-editor-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-03-admin-control-plane-ux/form-behavior-and-validation.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-03-admin-control-plane-ux/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-03-admin-control-plane-ux/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-03-admin-control-plane-ux/wizard-ia.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-04-participant-journeys/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-04-participant-journeys/applicant-experience-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-04-participant-journeys/audience-live-vote-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-04-participant-journeys/jury-experience-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-04-participant-journeys/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-04-participant-journeys/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-05-special-awards-governance/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-05-special-awards-governance/award-track-and-governance-spec.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-05-special-awards-governance/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-05-special-awards-governance/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-06-platform-dependency-refit/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-06-platform-dependency-refit/module-refit-map.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-06-platform-dependency-refit/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-06-platform-dependency-refit/symbol-sweep-checklist.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-06-platform-dependency-refit/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-07-validation-release/acceptance-gates.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-07-validation-release/overview.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-07-validation-release/performance-and-resilience-plan.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-07-validation-release/runbook.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-07-validation-release/tasks.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/api-contracts.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/authz-matrix.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/decision-log.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/dependency-refit-inventory.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/domain-model.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/phase-gate-traceability.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/program-charter.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/release-evidence-template.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/risk-register.md delete mode 100644 docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/shared/test-matrix.md delete mode 100644 docs/round-redesign-architecture-docs/phase-0-validation/domain-model-review.md create mode 100644 docs/unified-architecture-redesign/00-README.md create mode 100644 docs/unified-architecture-redesign/01-architecture-and-decisions.md create mode 100644 docs/unified-architecture-redesign/02-data-model.md create mode 100644 docs/unified-architecture-redesign/03-competition-flow.md create mode 100644 docs/unified-architecture-redesign/04-jury-groups-and-assignment-policy.md create mode 100644 docs/unified-architecture-redesign/05-special-awards.md create mode 100644 docs/unified-architecture-redesign/06-mentoring-and-document-lifecycle.md create mode 100644 docs/unified-architecture-redesign/07-live-finals-and-deliberation.md create mode 100644 docs/unified-architecture-redesign/08-platform-integration-matrix.md create mode 100644 docs/unified-architecture-redesign/09-implementation-roadmap.md create mode 100644 docs/unified-architecture-redesign/10-migration-strategy.md create mode 100644 docs/unified-architecture-redesign/11-testing-and-qa.md create mode 100644 docs/unified-architecture-redesign/12-observability-and-release-gates.md create mode 100644 docs/unified-architecture-redesign/13-open-questions-and-governance.md create mode 100644 prisma/migrations/20260215000000_add_competition_round_architecture/migration.sql create mode 100644 prisma/migrations/20260215100000_add_self_service_fields/migration.sql create mode 100644 prisma/migrations/20260215200000_phase7_fk_renames/migration.sql create mode 100644 prisma/migrations/20260215200001_phase7_drop_legacy/migration.sql create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/assignments/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/awards/[awardId]/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/awards/new/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/awards/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/deliberation/[sessionId]/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/deliberation/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/juries/[juryGroupId]/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/juries/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/live/[roundId]/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[competitionId]/rounds/[roundId]/page.tsx create mode 100644 src/app/(admin)/admin/competitions/[id]/page.tsx create mode 100644 src/app/(admin)/admin/competitions/new/page.tsx rename src/app/(admin)/admin/{rounds/pipelines => competitions}/page.tsx (61%) delete mode 100644 src/app/(admin)/admin/reports/stages/page.tsx delete mode 100644 src/app/(admin)/admin/rounds/new-pipeline/page.tsx delete mode 100644 src/app/(admin)/admin/rounds/pipeline/[id]/advanced/page.tsx delete mode 100644 src/app/(admin)/admin/rounds/pipeline/[id]/edit/page.tsx delete mode 100644 src/app/(admin)/admin/rounds/pipeline/[id]/page.tsx delete mode 100644 src/app/(admin)/admin/rounds/pipeline/[id]/wizard/page.tsx create mode 100644 src/app/(applicant)/applicant/competitions/[windowId]/page.tsx create mode 100644 src/app/(applicant)/applicant/competitions/page.tsx delete mode 100644 src/app/(applicant)/applicant/pipeline/[stageId]/documents/page.tsx delete mode 100644 src/app/(applicant)/applicant/pipeline/[stageId]/status/page.tsx delete mode 100644 src/app/(applicant)/applicant/pipeline/page.tsx create mode 100644 src/app/(applicant)/error.tsx create mode 100644 src/app/(jury)/jury/competitions/[roundId]/live/page.tsx create mode 100644 src/app/(jury)/jury/competitions/[roundId]/page.tsx create mode 100644 src/app/(jury)/jury/competitions/[roundId]/projects/[projectId]/evaluate/page.tsx create mode 100644 src/app/(jury)/jury/competitions/[roundId]/projects/[projectId]/page.tsx create mode 100644 src/app/(jury)/jury/competitions/deliberation/[sessionId]/page.tsx create mode 100644 src/app/(jury)/jury/competitions/page.tsx delete mode 100644 src/app/(jury)/jury/stages/[stageId]/assignments/page.tsx delete mode 100644 src/app/(jury)/jury/stages/[stageId]/compare/page.tsx delete mode 100644 src/app/(jury)/jury/stages/[stageId]/live/page.tsx delete mode 100644 src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/evaluate/page.tsx delete mode 100644 src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/evaluation/page.tsx delete mode 100644 src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/page.tsx delete mode 100644 src/app/(jury)/jury/stages/page.tsx create mode 100644 src/app/(mentor)/mentor/workspace/[projectId]/page.tsx create mode 100644 src/app/(mentor)/mentor/workspace/page.tsx delete mode 100644 src/app/(public)/live-scores/stage/[sessionId]/page.tsx create mode 100644 src/app/(public)/vote/competition/[roundId]/page.tsx delete mode 100644 src/app/(public)/vote/stage/[sessionId]/page.tsx delete mode 100644 src/app/api/sse/stage-live/[sessionId]/route.ts create mode 100644 src/components/admin/assignment/assignment-preview-sheet.tsx create mode 100644 src/components/admin/assignment/coverage-report.tsx create mode 100644 src/components/admin/competition/competition-timeline.tsx create mode 100644 src/components/admin/competition/round-config-form.tsx create mode 100644 src/components/admin/competition/sections/basics-section.tsx create mode 100644 src/components/admin/competition/sections/jury-groups-section.tsx create mode 100644 src/components/admin/competition/sections/review-section.tsx create mode 100644 src/components/admin/competition/sections/rounds-section.tsx create mode 100644 src/components/admin/deliberation/admin-override-dialog.tsx create mode 100644 src/components/admin/deliberation/results-panel.tsx create mode 100644 src/components/admin/jury/add-member-dialog.tsx create mode 100644 src/components/admin/jury/jury-members-table.tsx create mode 100644 src/components/admin/live/live-control-panel.tsx create mode 100644 src/components/admin/live/project-navigator-grid.tsx delete mode 100644 src/components/admin/pipeline/award-governance-editor.tsx delete mode 100644 src/components/admin/pipeline/filtering-rules-editor.tsx delete mode 100644 src/components/admin/pipeline/pipeline-flowchart.tsx delete mode 100644 src/components/admin/pipeline/pipeline-visualization.tsx delete mode 100644 src/components/admin/pipeline/predicate-builder.tsx delete mode 100644 src/components/admin/pipeline/sections/assignment-section.tsx delete mode 100644 src/components/admin/pipeline/sections/awards-section.tsx delete mode 100644 src/components/admin/pipeline/sections/basics-section.tsx delete mode 100644 src/components/admin/pipeline/sections/filtering-section.tsx delete mode 100644 src/components/admin/pipeline/sections/intake-section.tsx delete mode 100644 src/components/admin/pipeline/sections/live-finals-section.tsx delete mode 100644 src/components/admin/pipeline/sections/main-track-section.tsx delete mode 100644 src/components/admin/pipeline/sections/notifications-section.tsx delete mode 100644 src/components/admin/pipeline/sections/results-section.tsx delete mode 100644 src/components/admin/pipeline/sections/review-section.tsx delete mode 100644 src/components/admin/pipeline/sections/selection-section.tsx delete mode 100644 src/components/admin/pipeline/stage-config-editor.tsx delete mode 100644 src/components/admin/pipeline/stage-detail-sheet.tsx delete mode 100644 src/components/admin/pipeline/stage-panels/evaluation-panel.tsx delete mode 100644 src/components/admin/pipeline/stage-panels/filter-panel.tsx delete mode 100644 src/components/admin/pipeline/stage-panels/intake-panel.tsx delete mode 100644 src/components/admin/pipeline/stage-panels/live-final-panel.tsx delete mode 100644 src/components/admin/pipeline/stage-panels/results-panel.tsx delete mode 100644 src/components/admin/pipeline/stage-panels/selection-panel.tsx delete mode 100644 src/components/admin/pipeline/stage-transitions-editor.tsx create mode 100644 src/components/admin/result/result-lock-controls.tsx create mode 100644 src/components/admin/round/project-states-table.tsx create mode 100644 src/components/admin/round/submission-window-manager.tsx create mode 100644 src/components/applicant/competition-timeline.tsx create mode 100644 src/components/applicant/file-upload-slot.tsx create mode 100644 src/components/jury/deliberation-ranking-form.tsx create mode 100644 src/components/jury/live-voting-form.tsx create mode 100644 src/components/jury/multi-window-doc-viewer.tsx create mode 100644 src/components/mentor/file-promotion-panel.tsx create mode 100644 src/components/mentor/workspace-chat.tsx create mode 100644 src/components/public/audience-vote-card.tsx delete mode 100644 src/components/shared/stage-breadcrumb.tsx delete mode 100644 src/components/shared/stage-timeline.tsx delete mode 100644 src/components/shared/stage-window-badge.tsx delete mode 100644 src/hooks/use-pipeline-inline-edit.ts create mode 100644 src/lib/feature-flags.ts delete mode 100644 src/lib/pipeline-conversions.ts delete mode 100644 src/lib/pipeline-defaults.ts delete mode 100644 src/lib/pipeline-validation.ts delete mode 100644 src/lib/stage-config-schema.ts create mode 100644 src/server/routers/assignmentIntent.ts create mode 100644 src/server/routers/assignmentPolicy.ts create mode 100644 src/server/routers/competition.ts create mode 100644 src/server/routers/deliberation.ts create mode 100644 src/server/routers/juryGroup.ts delete mode 100644 src/server/routers/pipeline.ts create mode 100644 src/server/routers/resultLock.ts create mode 100644 src/server/routers/round.ts create mode 100644 src/server/routers/roundAssignment.ts create mode 100644 src/server/routers/roundEngine.ts delete mode 100644 src/server/routers/stage.ts delete mode 100644 src/server/routers/stageAssignment.ts delete mode 100644 src/server/routers/stageFiltering.ts create mode 100644 src/server/services/ai-prompt-guard.ts create mode 100644 src/server/services/ai-shortlist.ts create mode 100644 src/server/services/assignment-intent.ts create mode 100644 src/server/services/assignment-policy.ts create mode 100644 src/server/services/competition-context.ts create mode 100644 src/server/services/deliberation.ts create mode 100644 src/server/services/mentor-workspace.ts create mode 100644 src/server/services/result-lock.ts create mode 100644 src/server/services/round-assignment.ts create mode 100644 src/server/services/round-engine.ts delete mode 100644 src/server/services/stage-assignment.ts delete mode 100644 src/server/services/stage-engine.ts delete mode 100644 src/server/services/stage-filtering.ts delete mode 100644 src/server/services/stage-notifications.ts create mode 100644 src/server/services/submission-manager.ts create mode 100644 src/types/competition-configs.ts create mode 100644 src/types/competition.ts delete mode 100644 src/types/pipeline-wizard.ts delete mode 100644 tests/integration/assignment-preview.test.ts delete mode 100644 tests/integration/cohort-voting.test.ts delete mode 100644 tests/integration/decision-audit.test.ts delete mode 100644 tests/integration/live-runtime.test.ts delete mode 100644 tests/integration/pipeline-crud.test.ts delete mode 100644 tests/integration/stage-config.test.ts create mode 100644 tests/unit/assignment-policy.test.ts delete mode 100644 tests/unit/award-governance.test.ts delete mode 100644 tests/unit/live-control.test.ts delete mode 100644 tests/unit/override-validation.test.ts delete mode 100644 tests/unit/stage-assignment.test.ts delete mode 100644 tests/unit/stage-engine.test.ts delete mode 100644 tests/unit/stage-filtering.test.ts diff --git a/CLAUDE.md b/CLAUDE.md index bd5f08b..e1e648d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,388 +1,171 @@ -# MOPC Platform - Claude Code Context +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview -**MOPC (Monaco Ocean Protection Challenge)** is a secure jury online voting platform for managing project selection rounds. The platform enables jury members to evaluate submitted ocean conservation projects, with Phase 1 supporting two selection rounds: - -- **Round 1**: ~130 projects → ~60 semi-finalists -- **Round 2**: ~60 projects → 6 finalists - -**Domain**: `monaco-opc.com` - -The platform is designed for future expansion into a comprehensive program management system including learning hub, communication workflows, and partner modules. - -## Key Decisions - -| Decision | Choice | -|----------|--------| -| Evaluation Criteria | Fully configurable per round (admin defines) | -| CSV Import | Flexible column mapping (admin maps columns) | -| Max File Size | 500MB (for videos) | -| Observer Role | Included in Phase 1 | -| First Admin | Database seed script | -| Past Evaluations | Visible read-only after submit | -| Grace Period | Admin-configurable per juror/project | -| Smart Assignment | AI-powered (GPT) + Smart Algorithm fallback + geo-diversity, familiarity, COI scoring | -| AI Data Privacy | All data anonymized before sending to GPT | -| Evaluation Criteria Types | `numeric`, `text`, `boolean`, `section_header` (backward-compatible) | -| COI Workflow | Mandatory declaration before evaluation, admin review | -| Evaluation Reminders | Cron-based email reminders with countdown urgency | - -## Brand Identity - -| Name | Hex | Usage | -|------|-----|-------| -| Primary Red | `#de0f1e` | CTAs, alerts | -| Dark Blue | `#053d57` | Headers, sidebar | -| White | `#fefefe` | Backgrounds | -| Teal | `#557f8c` | Links, secondary | - -**Typography**: Montserrat (600/700 for headings, 300/400 for body) - -## Tech Stack - -| Layer | Technology | Version | -|-------|-----------|---------| -| **Framework** | Next.js (App Router) | 15.x | -| **Language** | TypeScript | 5.x | -| **UI Components** | shadcn/ui | latest | -| **Styling** | Tailwind CSS | 3.x | -| **API Layer** | tRPC | 11.x | -| **Database** | PostgreSQL | 16.x | -| **ORM** | Prisma | 6.x | -| **Authentication** | NextAuth.js (Auth.js) | 5.x | -| **AI** | OpenAI GPT | 4.x SDK | -| **Animation** | Motion (Framer Motion) | 11.x | -| **Notifications** | Sonner | 1.x | -| **Command Palette** | cmdk | 1.x | -| **File Storage** | MinIO (S3-compatible) | External | -| **Email** | Nodemailer + Poste.io | External | -| **Containerization** | Docker Compose | 2.x | -| **Reverse Proxy** | Nginx | External | - -## Architecture Principles - -1. **Type Safety First**: End-to-end TypeScript from database to UI via Prisma → tRPC → React -2. **Mobile-First Responsive**: All components designed for mobile, enhanced for desktop -3. **Full Control**: No black-box services; every component is understood and maintainable -4. **Extensible Data Model**: JSON fields for future attributes without schema migrations -5. **Security by Default**: RBAC, audit logging, secure file access with pre-signed URLs - -## File Structure - -``` -mopc-platform/ -├── CLAUDE.md # This file - project context -├── docs/ -│ └── architecture/ # Architecture documentation -│ ├── README.md # System overview -│ ├── database.md # Database design -│ ├── api.md # API design -│ ├── infrastructure.md # Deployment docs -│ └── ui.md # UI/UX patterns -├── src/ -│ ├── app/ # Next.js App Router pages -│ │ ├── (auth)/ # Public auth routes (login, verify) -│ │ ├── (admin)/ # Admin dashboard (protected) -│ │ ├── (jury)/ # Jury interface (protected) -│ │ ├── api/ # API routes -│ │ │ ├── trpc/ # tRPC endpoint -│ │ │ └── cron/ -│ │ │ └── reminders/ # Cron endpoint for evaluation reminders (F4) -│ │ ├── layout.tsx # Root layout -│ │ └── page.tsx # Home/landing -│ ├── components/ -│ │ ├── ui/ # shadcn/ui components -│ │ ├── admin/ # Admin-specific components -│ │ │ └── evaluation-summary-card.tsx # AI summary display -│ │ ├── forms/ # Form components -│ │ │ ├── evaluation-form.tsx # With progress indicator (F1) -│ │ │ ├── coi-declaration-dialog.tsx # COI blocking dialog (F5) -│ │ │ └── evaluation-form-with-coi.tsx # COI-gated wrapper (F5) -│ │ ├── layouts/ # Layout components (sidebar, nav) -│ │ └── shared/ # Shared components -│ │ └── countdown-timer.tsx # Live countdown with urgency (F4) -│ ├── lib/ -│ │ ├── auth.ts # NextAuth configuration -│ │ ├── prisma.ts # Prisma client singleton -│ │ ├── trpc/ # tRPC client & server setup -│ │ ├── minio.ts # MinIO client -│ │ └── email.ts # Email utilities -│ ├── server/ -│ │ ├── routers/ # tRPC routers by domain -│ │ │ ├── program.ts -│ │ │ ├── round.ts -│ │ │ ├── project.ts -│ │ │ ├── user.ts -│ │ │ ├── assignment.ts -│ │ │ ├── evaluation.ts -│ │ │ ├── audit.ts -│ │ │ ├── settings.ts -│ │ │ ├── gracePeriod.ts -│ │ │ ├── export.ts # CSV export incl. filtering results (F2) -│ │ │ ├── analytics.ts # Reports/analytics (observer access, F3) -│ │ │ └── mentor.ts # Mentor messaging endpoints (F10) -│ │ ├── services/ # Business logic services -│ │ │ ├── smart-assignment.ts # With geo/familiarity/COI scoring (F8) -│ │ │ ├── evaluation-reminders.ts # Email reminder service (F4) -│ │ │ └── ai-evaluation-summary.ts # GPT summary generation (F7) -│ │ └── middleware/ # RBAC & auth middleware -│ ├── hooks/ # React hooks -│ ├── types/ # Shared TypeScript types -│ └── utils/ # Utility functions -├── prisma/ -│ ├── schema.prisma # Database schema -│ ├── migrations/ # Migration files -│ └── seed.ts # Seed data -├── public/ # Static assets -├── docker/ -│ ├── Dockerfile # Production build -│ ├── docker-compose.yml # Production stack -│ └── docker-compose.dev.yml # Development stack -├── tests/ -│ ├── unit/ # Unit tests -│ └── e2e/ # End-to-end tests -└── config files... # package.json, tsconfig, etc. -``` - -## Coding Standards - -### TypeScript -- Strict mode enabled -- Explicit return types for functions -- Use `type` over `interface` for consistency (unless extending) -- Prefer `unknown` over `any` - -### React/Next.js -- Use Server Components by default -- `'use client'` only when needed (interactivity, hooks) -- Collocate components with their routes when specific to that route -- Use React Query (via tRPC) for server state - -### Naming Conventions -- **Files**: kebab-case (`user-profile.tsx`) -- **Components**: PascalCase (`UserProfile`) -- **Functions/Variables**: camelCase (`getUserById`) -- **Constants**: SCREAMING_SNAKE_CASE (`MAX_FILE_SIZE`) -- **Database Tables**: PascalCase in Prisma (`User`, `Project`) -- **Database Columns**: camelCase in Prisma (`createdAt`) - -### Styling -- Tailwind CSS utility classes -- Mobile-first: base styles for mobile, `md:` for tablet, `lg:` for desktop -- Use shadcn/ui components as base, customize via CSS variables -- No inline styles; no separate CSS files unless absolutely necessary - -### API Design (tRPC) -- Group by domain: `trpc.program.create()`, `trpc.round.list()` -- Use Zod for input validation -- Return consistent response shapes -- Throw `TRPCError` with appropriate codes +**MOPC (Monaco Ocean Protection Challenge)** — a secure jury voting platform for managing multi-round project selection. Jury members evaluate ocean conservation projects through configurable competitions with rounds (intake, filtering, evaluation, submission, mentoring, live finals, deliberation). Domain: `monaco-opc.com`. ## Common Commands ```bash # Development -npm run dev # Start Next.js dev server -npm run db:studio # Open Prisma Studio -npm run db:push # Push schema changes (dev only) -npm run db:migrate # Run migrations -npm run db:seed # Seed database +npm run dev # Next.js dev (Turbopack) +npm run build # Production build (always test before push) +npm run typecheck # tsc --noEmit -# Testing -npm run test # Run unit tests -npm run test:e2e # Run E2E tests -npm run test:coverage # Test with coverage +# Database +npx prisma generate # Regenerate client after schema changes +npx prisma migrate dev # Create + apply migration +npx prisma studio # GUI database browser +npm run db:seed # Run seed (tsx prisma/seed.ts) -# Build & Deploy -npm run build # Production build -npm run start # Start production server -docker compose up -d # Start Docker stack -docker compose logs -f app # View app logs +# Testing (vitest, not jest) +npx vitest # Run all tests (watch mode) +npx vitest run # Run all tests once +npx vitest run tests/unit/round-engine.test.ts # Single file +npx vitest run -t 'test name' # Single test by name # Code Quality -npm run lint # ESLint -npm run format # Prettier -npm run typecheck # TypeScript check +npm run lint # ESLint +npm run format # Prettier + +# Docker (production) +docker compose -f docker/docker-compose.yml up -d +docker compose -f docker/docker-compose.dev.yml up -d # Dev stack ``` -## Windows Development Notes +## Tech Stack -**IMPORTANT**: On Windows, all Docker commands AND all npm/node commands must be run using PowerShell (`powershell -ExecutionPolicy Bypass -Command "..."`), not bash/cmd. This is required for proper Docker Desktop integration and Node.js execution. +Next.js 15 (App Router) | TypeScript 5 (strict) | Tailwind CSS 4 | shadcn/ui | tRPC 11 (superjson) | Prisma 6 | PostgreSQL 16 | NextAuth 5 (Auth.js) | Vitest 4 | OpenAI SDK 6 | MinIO (S3) | Nodemailer + Poste.io -**IMPORTANT**: When invoking PowerShell from bash, always use `-ExecutionPolicy Bypass` to skip the user profile script which is blocked by execution policy: -```bash -powershell -ExecutionPolicy Bypass -Command "..." +## Architecture + +### Data Flow: Prisma → tRPC → React + +End-to-end type safety: `prisma/schema.prisma` defines models → `src/server/routers/*.ts` expose tRPC procedures with Zod validation → `src/lib/trpc/client.ts` provides typed React hooks → components call `trpc.domain.procedure.useQuery()`. + +### tRPC Middleware Hierarchy (`src/server/trpc.ts`) + +All role-based access is enforced via procedure types: + +| Procedure | Roles Allowed | +|-----------|---------------| +| `publicProcedure` | Anyone (no auth) | +| `protectedProcedure` | Any authenticated user | +| `adminProcedure` | SUPER_ADMIN, PROGRAM_ADMIN | +| `superAdminProcedure` | SUPER_ADMIN only | +| `juryProcedure` | JURY_MEMBER only | +| `mentorProcedure` | SUPER_ADMIN, PROGRAM_ADMIN, MENTOR | +| `observerProcedure` | SUPER_ADMIN, PROGRAM_ADMIN, OBSERVER | +| `awardMasterProcedure` | SUPER_ADMIN, PROGRAM_ADMIN, AWARD_MASTER | +| `audienceProcedure` | Any authenticated user | + +### Route Groups (Next.js App Router) + +- `src/app/(auth)/` — Public auth pages (login, verify, accept-invite, onboarding) +- `src/app/(admin)/` — Admin dashboard, competition management, round config +- `src/app/(jury)/` — Jury evaluation interface, round assignments, live voting +- `src/app/(applicant)/` — Applicant dashboard, competition progress, document uploads +- `src/app/(mentor)/` — Mentor workspace + +### Competition System + +The core domain model. A **Competition** represents a complete evaluation cycle: + +``` +Competition → has many Rounds (ordered) ``` -Examples: -```bash -# npm commands -powershell -ExecutionPolicy Bypass -Command "npm install" -powershell -ExecutionPolicy Bypass -Command "npm run build" -powershell -ExecutionPolicy Bypass -Command "npx prisma generate" +- **Competition** (`src/server/routers/competition.ts`): Top-level competition config with program link, status, and settings +- **Round** (`RoundType: INTAKE | FILTERING | EVALUATION | SUBMISSION | MENTORING | LIVE_FINAL | DELIBERATION`): Each competition has ordered rounds with type-specific config in `configJson` -# Docker commands -powershell -ExecutionPolicy Bypass -Command "docker compose -f docker/docker-compose.dev.yml up -d" -``` +Key models: +- `JuryGroup` — Named jury panel with chair/member/observer roles +- `AdvancementRule` — Auto-advance, score threshold, top-N, admin selection between rounds +- `SubmissionWindow` — File submission deadlines per round +- `AssignmentPolicy` / `AssignmentIntent` — Governance layer for jury assignment +- `ProjectRoundState` — Per-project state within each round +- `DeliberationSession` / `DeliberationVote` / `ResultLock` — Structured deliberation and result finalization -```powershell -# Docker commands on Windows (use PowerShell) -docker compose -f docker/docker-compose.dev.yml up -d -docker compose -f docker/docker-compose.dev.yml build --no-cache app -docker compose -f docker/docker-compose.dev.yml logs -f app -docker compose -f docker/docker-compose.dev.yml down -``` +Key services: +- `src/server/services/round-engine.ts` — State machine for round transitions +- `src/server/services/round-assignment.ts` — Jury assignment generation with policy enforcement +- `src/server/services/submission-manager.ts` — File submission + filtering with duplicate detection +- `src/server/services/deliberation.ts` — Deliberation session management and vote tallying +- `src/server/services/result-lock.ts` — Result finalization and unlock governance +- `src/server/services/live-control.ts` — Live ceremony cursor management +- `src/server/services/competition-context.ts` — Cross-cutting competition context resolver + +Competition types: `src/types/competition.ts`, `src/types/competition-configs.ts` + +### AI Services (`src/server/services/ai-*.ts`) + +All AI calls anonymize data before sending to OpenAI. Services: +- `ai-filtering.ts` — AI-powered project screening with rubric +- `ai-assignment.ts` — GPT-suggested jury-project matching +- `ai-evaluation-summary.ts` — Strengths/weaknesses synthesis from evaluations +- `ai-tagging.ts` — Auto-tagging projects +- `ai-award-eligibility.ts` — Award eligibility assessment +- `ai-shortlist.ts` — AI-powered shortlist recommendations +- `anonymization.ts` — Strips PII before AI calls + +### Auth System + +NextAuth v5 with two providers: **Email** (magic links) and **Credentials** (password + invite token). Failed login tracking with 5-attempt lockout (15 min). Session includes `user.role` for RBAC. + +### Docker Entrypoint (`docker/docker-entrypoint.sh`) + +On container start: retry `prisma migrate deploy` → `prisma generate` → auto-seed if User table is empty → `node server.js`. A `docker compose down -v && docker compose up -d` will run all migrations from scratch and seed. + +## Testing Infrastructure + +- **Framework**: Vitest 4 with `fileParallelism: false` and `pool: 'forks'` (tests run sequentially) +- **Setup**: `tests/setup.ts` provides `prisma` client (uses `DATABASE_URL_TEST` or `DATABASE_URL`), `createTestContext(user)`, `createCaller(router, user)` +- **Factories**: `tests/helpers.ts` has `createTestUser()`, `createTestProgram()`, `createTestCompetition()`, `createTestRound()`, `uid()` helper, and `cleanupTestData()` +- **Pattern**: Create data with factories → build caller with `createCaller(routerModule, user)` → call procedures → assert → cleanup in `afterAll` + +## User Roles + +`SUPER_ADMIN` | `PROGRAM_ADMIN` | `JURY_MEMBER` | `OBSERVER` | `MENTOR` | `APPLICANT` | `AWARD_MASTER` | `AUDIENCE` + +## Coding Standards + +- **TypeScript**: Strict mode, `type` over `interface`, prefer `unknown` over `any` +- **Files**: kebab-case. **Components**: PascalCase. **DB models**: PascalCase in Prisma +- **React**: Server Components by default, `'use client'` only when needed +- **Styling**: Tailwind utility classes, mobile-first (`md:`, `lg:` breakpoints), shadcn/ui as base +- **tRPC**: Group by domain (`trpc.competition.create()`), Zod input validation, `TRPCError` for errors +- **Brand colors**: Primary Red `#de0f1e`, Dark Blue `#053d57`, White `#fefefe`, Teal `#557f8c` +- **Typography**: Montserrat (600/700 headings, 300/400 body) + +## Key Constraints + +1. Jury can only see assigned projects (enforced at query level) +2. Voting windows are strict — submissions blocked outside active window +3. All admin actions are audited via `DecisionAuditLog` +4. Files accessed via MinIO pre-signed URLs only (no public bucket) +5. COI declaration required before evaluation (blocking dialog) +6. Smart assignment skips COI-declared jurors, applies geo-diversity penalty and familiarity bonus +7. Cron endpoints protected by `CRON_SECRET` header +8. Round notifications never throw — all errors caught and logged + +## Security + +- CSRF: tRPC uses `application/json` (triggers CORS preflight). Do NOT add permissive CORS headers. +- Rate limiting: 100 req/min tRPC, 10 req/min auth, 5-attempt lockout +- AI privacy: All data anonymized before OpenAI calls + +## Seed Data + +`prisma/seed.ts` imports from `docs/Candidatures 2026 *.csv` with special handling for non-breaking spaces (U+00A0) around French guillemets. Includes ALL CSV rows (no filtering/dedup) — duplicate detection happens in `submission-manager.ts` at runtime. ## Environment Variables -```env -# Database -DATABASE_URL="postgresql://user:pass@localhost:5432/mopc" +Required: `DATABASE_URL`, `NEXTAUTH_URL`, `NEXTAUTH_SECRET`, `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_BUCKET`, `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `EMAIL_FROM`, `OPENAI_API_KEY`, `CRON_SECRET` -# NextAuth -NEXTAUTH_URL="https://monaco-opc.com" -NEXTAUTH_SECRET="your-secret-key" +External services (pre-existing on VPS): MinIO `:9000`, Poste.io `:587`, Nginx reverse proxy with SSL. -# MinIO (existing separate stack) -MINIO_ENDPOINT="http://localhost:9000" -MINIO_ACCESS_KEY="your-access-key" -MINIO_SECRET_KEY="your-secret-key" -MINIO_BUCKET="mopc-files" +## Git -# Email (Poste.io - existing) -SMTP_HOST="localhost" -SMTP_PORT="587" -SMTP_USER="noreply@monaco-opc.com" -SMTP_PASS="your-smtp-password" -EMAIL_FROM="MOPC Platform " - -# OpenAI (for smart assignment and AI evaluation summaries) -OPENAI_API_KEY="your-openai-api-key" - -# Cron (for scheduled evaluation reminders) -CRON_SECRET="your-cron-secret-key" -``` - -## Key Architectural Decisions - -### 1. Next.js App Router over Pages Router -**Rationale**: Server Components reduce client bundle, better data fetching patterns, layouts system - -### 2. tRPC over REST -**Rationale**: End-to-end type safety without code generation, excellent DX with autocomplete - -### 3. Prisma over raw SQL -**Rationale**: Type-safe queries, migration system, works seamlessly with TypeScript - -### 4. NextAuth.js over custom auth -**Rationale**: Battle-tested, supports magic links, session management built-in - -### 5. MinIO (external) over local file storage -**Rationale**: S3-compatible, pre-signed URLs for security, scalable, already deployed - -### 6. JSON fields for extensibility -**Rationale**: `metadata_json`, `settings_json` allow adding attributes without migrations - -### 7. Soft deletes with status fields -**Rationale**: Audit trail preservation, recovery capability, referential integrity - -## User Roles (RBAC) - -| Role | Permissions | -|------|------------| -| **SUPER_ADMIN** | Full system access, all programs, user management | -| **PROGRAM_ADMIN** | Manage specific programs, rounds, projects, jury | -| **JURY_MEMBER** | View assigned projects only, submit evaluations, declare COI | -| **OBSERVER** | Read-only access to dashboards, all analytics/reports | -| **MENTOR** | View assigned projects, message applicants via `mentorProcedure` | -| **APPLICANT** | View own project status, upload documents per round, message mentor | - -## Important Constraints - -1. **Jury can only see assigned projects** - enforced at query level -2. **Voting windows are strict** - submissions blocked outside active window -3. **Evaluations are versioned** - edits create new versions -4. **All admin actions are audited** - immutable audit log -5. **Files accessed via pre-signed URLs** - no public bucket access -6. **Mobile responsiveness is mandatory** - every view must work on phones -7. **File downloads require project authorization** - jury/mentor must be assigned to the project -8. **Mentor endpoints require MENTOR role** - uses `mentorProcedure` middleware -9. **COI declaration required before evaluation** - blocking dialog gates evaluation form; admin reviews COI declarations -10. **Evaluation form supports multiple criterion types** - `numeric`, `text`, `boolean`, `section_header`; defaults to `numeric` for backward compatibility -11. **Smart assignment respects COI** - jurors with declared conflicts are skipped entirely; geo-diversity penalty and prior-round familiarity bonus applied -12. **Cron endpoints protected by CRON_SECRET** - `/api/cron/reminders` validates secret header -13. **Project status changes tracked** - every status update creates a `ProjectStatusHistory` record -14. **Per-round document management** - `ProjectFile` supports `roundId` scoping and `isLate` deadline tracking - -## Security Notes - -### CSRF Protection -tRPC mutations are protected against CSRF attacks because: -- tRPC uses `application/json` content type, which triggers CORS preflight on cross-origin requests -- Browsers block cross-origin JSON POSTs by default (Same-Origin Policy) -- NextAuth's own routes (`/api/auth/*`) have built-in CSRF token protection -- No custom CORS headers are configured to allow external origins - -**Do NOT add permissive CORS headers** (e.g., `Access-Control-Allow-Origin: *`) without also implementing explicit CSRF token validation on all mutation endpoints. - -### Rate Limiting -- tRPC API: 100 requests/minute per IP -- Auth endpoints: 10 POST requests/minute per IP -- Account lockout: 5 failed password attempts triggers 15-minute lockout - -## External Services (Pre-existing) - -These services are already running on the VPS in separate Docker Compose stacks: - -- **MinIO**: `http://localhost:9000` - S3-compatible storage -- **Poste.io**: `localhost:587` - SMTP server for emails -- **Nginx**: Host-level reverse proxy with SSL (certbot) - -The MOPC platform connects to these via environment variables. - -## Phase 1 Scope - -### In Scope -- Round management (create, configure, activate/close) -- Project import (CSV) and file uploads -- Jury invitation (magic link) -- Manual project assignment (single + bulk) -- Evaluation form (configurable criteria) -- Autosave + final submit -- Voting window enforcement -- Progress dashboards -- CSV export -- Audit logging -- **F1: Evaluation progress indicator** - sticky status bar with percentage tracking across criteria, global score, decision, feedback -- **F2: Export filtering results as CSV** - dynamic AI column flattening from `aiScreeningJson` -- **F3: Observer access to reports/analytics** - all 8 analytics procedures use `observerProcedure`; observer reports page with round selector, tabs, charts -- **F4: Countdown timer + email reminders** - live countdown with urgency colors; `EvaluationRemindersService` with cron endpoint (`/api/cron/reminders`) -- **F5: Conflict of Interest declaration** - `ConflictOfInterest` model; blocking dialog before evaluation; admin COI review page -- **F6: Bulk status update UI** - checkbox selection, floating toolbar, `ProjectStatusHistory` tracking -- **F7: AI-powered evaluation summary** - `EvaluationSummary` model; GPT-generated strengths/weaknesses, themes, scoring stats -- **F8: Smart assignment improvements** - `geoDiversityPenalty`, `previousRoundFamiliarity`, `coiPenalty` scoring factors -- **F9: Evaluation form flexibility** - extended criterion types (`numeric`, `text`, `boolean`, `section_header`); conditional visibility, section grouping -- **F10: Applicant portal enhancements** - `ProjectStatusHistory` timeline; per-round document management (`roundId` + `isLate` on `ProjectFile`); `MentorMessage` model for mentor-applicant chat - -### Out of Scope (Phase 2+) -- Typeform/Notion integrations -- WhatsApp notifications -- Learning hub -- Partner modules -- Public website - -## Testing Strategy - -- **Unit Tests**: Business logic, utilities, validators -- **Integration Tests**: tRPC routers with test database -- **E2E Tests**: Critical user flows (Playwright) -- **Manual Testing**: Responsive design on real devices - -## Documentation Links - -- [Architecture Overview](./docs/architecture/README.md) -- [Database Design](./docs/architecture/database.md) -- [API Design](./docs/architecture/api.md) -- [Infrastructure](./docs/architecture/infrastructure.md) -- [UI/UX Patterns](./docs/architecture/ui.md) +Remote: `code.monaco-opc.com/MOPC/MOPC-Portal`. Branch: `main`. Always `npm run build` before pushing. diff --git a/docs/claude-architecture-redesign/00-executive-summary.md b/docs/claude-architecture-redesign/00-executive-summary.md new file mode 100644 index 0000000..3902ebf --- /dev/null +++ b/docs/claude-architecture-redesign/00-executive-summary.md @@ -0,0 +1,201 @@ +# Executive Summary: MOPC Architecture Redesign + +## Why This Redesign + +The MOPC platform currently uses a **Pipeline -> Track -> Stage** model with generic JSON configs to orchestrate the competition. While technically sound, this architecture introduces unnecessary abstraction for what is fundamentally a **linear sequential competition flow**. + +### Current Problems + +| Problem | Impact | +|---------|--------| +| **3-level nesting** (Pipeline->Track->Stage) | Cognitive overhead for admins configuring rounds | +| **Generic `configJson` blobs** per stage type | "Vague" — hard to know what's configurable without reading code | +| **No explicit jury entities** | Juries are implicit (per-stage assignments), can't manage "Jury 1" as a thing | +| **Single submission round** | No way to open a second submission window for semi-finalists | +| **Track layer for main flow** | MAIN track adds indirection without value for a linear flow | +| **No mentoring workspace** | Mentor file exchange exists but no comments, no promotion to submission | +| **No winner confirmation** | No multi-party agreement step to cement winners | +| **Missing round types** | Can't model a "Semi-finalist Submission" or "Mentoring" or "Confirmation" step | + +### Design Principles + +1. **Domain over abstraction** — Models map directly to competition concepts (Jury 1, Round 2, etc.) +2. **Linear by default** — The main flow is sequential. Branching is only for special awards. +3. **Typed configs over JSON blobs** — Each round type has explicit, documented fields. +4. **Explicit entities** — Juries, submission windows, and confirmation steps are first-class models. +5. **Deep integration** — Every feature connects. Jury groups link to rounds, rounds link to submissions, submissions link to evaluations. +6. **Admin override everywhere** — Any automated decision can be manually overridden with audit trail. + +--- + +## Before & After: Architecture Comparison + +### BEFORE (Current System) + +``` +Program + └── Pipeline (generic container) + ├── Track: "Main Competition" (MAIN) + │ ├── Stage: "Intake" (INTAKE, configJson: {...}) + │ ├── Stage: "Filtering" (FILTER, configJson: {...}) + │ ├── Stage: "Evaluation" (EVALUATION, configJson: {...}) + │ ├── Stage: "Selection" (SELECTION, configJson: {...}) + │ ├── Stage: "Live Finals" (LIVE_FINAL, configJson: {...}) + │ └── Stage: "Results" (RESULTS, configJson: {...}) + ├── Track: "Award 1" (AWARD) + │ ├── Stage: "Evaluation" (EVALUATION) + │ └── Stage: "Results" (RESULTS) + └── Track: "Award 2" (AWARD) + ├── Stage: "Evaluation" (EVALUATION) + └── Stage: "Results" (RESULTS) + +Juries: implicit (assignments per stage, no named entity) +Submissions: single round (one INTAKE stage) +Mentoring: basic (messages + notes, no workspace) +Winner confirmation: none +``` + +### AFTER (Redesigned System) + +``` +Program + └── Competition (purpose-built, replaces Pipeline) + ├── Rounds (linear sequence, replaces Track+Stage): + │ ├── Round 1: "Application Window" ─────── (INTAKE) + │ ├── Round 2: "AI Screening" ──────────── (FILTERING) + │ ├── Round 3: "Jury 1 - Semi-finalist" ── (EVALUATION) ── juryGroupId: jury-1 + │ ├── Round 4: "Semi-finalist Docs" ─────── (SUBMISSION) ── submissionWindowId: sw-2 + │ ├── Round 5: "Jury 2 - Finalist" ──────── (EVALUATION) ── juryGroupId: jury-2 + │ ├── Round 6: "Finalist Mentoring" ─────── (MENTORING) + │ ├── Round 7: "Live Finals" ────────────── (LIVE_FINAL) ── juryGroupId: jury-3 + │ └── Round 8: "Confirm Winners" ─────────── (CONFIRMATION) + │ + ├── Jury Groups (explicit, named): + │ ├── "Jury 1" ── members: [judge-a, judge-b, ...] ── linked to Round 3 + │ ├── "Jury 2" ── members: [judge-c, judge-d, ...] ── linked to Round 5 + │ └── "Jury 3" ── members: [judge-e, judge-f, ...] ── linked to Round 7 + │ + ├── Submission Windows (multi-round): + │ ├── Window 1: "Round 1 Docs" ── requirements: [Exec Summary, Business Plan] + │ └── Window 2: "Round 2 Docs" ── requirements: [Updated Plan, Video Pitch] + │ + └── Special Awards (standalone): + ├── "Innovation Award" ── mode: STAY_IN_MAIN, juryGroup: jury-2-award + └── "Impact Award" ── mode: SEPARATE_POOL, juryGroup: dedicated-jury +``` + +--- + +## Key Decisions + +### 1. Eliminate the Track Layer + +**Decision:** Remove the `Track` model entirely. The main competition is a linear sequence of Rounds. Special awards become standalone entities. + +**Rationale:** The MOPC competition has one main flow (Intake -> Filtering -> Jury 1 -> Submission 2 -> Jury 2 -> Mentoring -> Finals -> Confirmation). The `Track` concept (MAIN/AWARD/SHOWCASE with RoutingMode and DecisionMode) was designed for branching flows that don't exist in this competition. Awards don't need their own track — they're parallel evaluation/voting processes that reference the same projects. + +**Impact:** +- `Track` model deleted +- `TrackKind`, `RoutingMode` enums deleted +- `ProjectStageState.trackId` removed (becomes `ProjectRoundState` with just `projectId` + `roundId`) +- Award tracks replaced with enhanced `SpecialAward` model +- ~200 lines of Track CRUD code eliminated + +### 2. Rename Pipeline -> Competition, Stage -> Round + +**Decision:** Use domain-specific names that map to the competition vocabulary. + +**Rationale:** Admins think in terms of "Competition 2026" and "Round 3: Jury 1 Evaluation", not "Pipeline" and "Stage". The rename costs nothing but improves comprehension. + +### 3. Expand RoundType Enum + +**Decision:** Add SUBMISSION, MENTORING, and CONFIRMATION to the existing types. + +**Current:** `INTAKE | FILTER | EVALUATION | SELECTION | LIVE_FINAL | RESULTS` + +**New:** `INTAKE | FILTERING | EVALUATION | SUBMISSION | MENTORING | LIVE_FINAL | CONFIRMATION` + +**Changes:** +- `FILTER` -> `FILTERING` (clearer naming) +- `SELECTION` removed (merged into EVALUATION's advancement config) +- `RESULTS` removed (results are a view, not a round — handled by the CONFIRMATION round output) +- `SUBMISSION` added (new doc requirements for advancing teams) +- `MENTORING` added (mentor-team workspace activation) +- `CONFIRMATION` added (multi-party winner agreement) + +### 4. Explicit JuryGroup Model + +**Decision:** Juries are first-class entities with names, members, and per-juror configuration. + +**Before:** Assignments were per-stage with no grouping concept. "Jury 1" only existed in the admin's head. + +**After:** `JuryGroup` model with members, linked to specific evaluation/live-final rounds. A juror can belong to multiple groups. + +### 5. Multi-Round Submissions via SubmissionWindow + +**Decision:** A new `SubmissionWindow` model handles document requirements per round, with automatic locking of previous windows. + +**Before:** One INTAKE stage with one set of `FileRequirement` records. + +**After:** Each submission window has its own requirements. When a new window opens, previous ones lock for applicants. Jury rounds can see docs from specific windows. + +### 6. Typed Configs Replace JSON Blobs + +**Decision:** Replace generic `configJson: Json?` with round-type-specific config models or strongly-typed JSON with Zod validation. + +**Before:** `Stage.configJson` could be anything — you'd have to read the code to know what fields exist for each StageType. + +**After:** Each round type has a documented, validated config shape. The wizard presents only the fields relevant to each type. + +--- + +## Scope Summary + +| Area | Action | Complexity | +|------|--------|------------| +| **Schema** | Major changes (new models, renamed models, deleted Track) | High | +| **Stage engine** | Rename to round engine, simplify (no Track references) | Medium | +| **Assignment service** | Enhance with jury groups, hard/soft caps, category ratios | Medium | +| **Filtering service** | Minimal changes (rename stageId -> roundId) | Low | +| **Live control** | Enhanced stage manager UI, same core logic | Medium | +| **Mentor system** | Major enhancement (workspace, files, comments, promotion) | High | +| **Winner confirmation** | New system (proposal, approvals, freezing) | High | +| **Special awards** | Enhanced (standalone, two modes, own jury groups) | Medium | +| **Notification system** | Enhanced (deadline countdowns, reminder triggers) | Medium | +| **Admin UI** | Full redesign (competition wizard, round management) | High | +| **Jury UI** | Enhanced (multi-jury dashboard, cross-round docs) | Medium | +| **Applicant UI** | Enhanced (multi-round submissions, mentoring workspace) | Medium | +| **Mentor UI** | New (dedicated mentor dashboard and workspace) | High | +| **API routers** | Major refactor (rename, new endpoints, removed endpoints) | High | +| **Migration** | Data migration from old schema to new | Medium | + +--- + +## Document Index + +| # | Document | Purpose | +|---|----------|---------| +| 00 | This document | Executive summary and key decisions | +| 01 | Current System Audit | What exists today — models, services, routers, UI | +| 02 | Gap Analysis | Current vs required, feature-by-feature comparison | +| 03 | Data Model | Complete Prisma schema redesign with migration SQL | +| 04 | Round: Intake | Application window, forms, deadlines, drafts | +| 05 | Round: Filtering | AI screening, eligibility, admin overrides | +| 06 | Round: Evaluation | Multi-jury, caps, ratios, scoring, advancement | +| 07 | Round: Submission | Multi-round docs, locking, jury visibility | +| 08 | Round: Mentoring | Private workspace, file comments, promotion | +| 09 | Round: Live Finals | Stage manager, live voting, deliberation | +| 10 | Round: Confirmation | Jury signatures, admin override, result freezing | +| 11 | Special Awards | Two modes, award juries, integration | +| 12 | Jury Groups | Multi-jury architecture, members, overrides | +| 13 | Notifications & Deadlines | Countdowns, reminders, window management | +| 14 | AI Services | Filtering, assignment, summaries, eligibility | +| 15 | Admin UI Redesign | Dashboard, wizard, round management | +| 16 | Jury UI Redesign | Dashboard, evaluation, live voting | +| 17 | Applicant UI Redesign | Dashboard, multi-round uploads, mentoring | +| 18 | Mentor UI Redesign | Dashboard, workspace, file review | +| 19 | API Router Reference | tRPC changes — new, modified, removed | +| 20 | Service Layer Changes | Engine, assignment, new services | +| 21 | Migration Strategy | Schema migration, data migration, rollback | +| 22 | Integration Map | Cross-reference of all feature connections | +| 23 | Implementation Sequence | Phased order with dependencies | diff --git a/docs/claude-architecture-redesign/01-current-system-audit.md b/docs/claude-architecture-redesign/01-current-system-audit.md new file mode 100644 index 0000000..071e353 --- /dev/null +++ b/docs/claude-architecture-redesign/01-current-system-audit.md @@ -0,0 +1,591 @@ +# Current System Audit: MOPC Platform + +**Document Version:** 1.0 +**Date:** 2026-02-15 +**Status:** Complete +**Purpose:** Comprehensive inventory of all data models, services, routers, pages, and capabilities in the MOPC platform as of February 2026. + +--- + +## Table of Contents + +1. [Data Models](#1-data-models) +2. [Enums](#2-enums) +3. [Services](#3-services) +4. [tRPC Routers](#4-trpc-routers) +5. [UI Pages](#5-ui-pages) +6. [Strengths](#6-strengths-of-current-system) +7. [Weaknesses](#7-weaknesses-of-current-system) + +--- + +## 1. Data Models + +### 1.1 Competition Structure Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **Pipeline** | Top-level competition round container | `programId`, `name`, `slug`, `status`, `settingsJson` | → Program, → Track[] | +| **Track** | Competition lane (MAIN or AWARD) | `pipelineId`, `name`, `kind`, `routingMode`, `decisionMode`, `sortOrder`, `settingsJson` | → Pipeline, → Stage[], → ProjectStageState[], ← SpecialAward? | +| **Stage** | Individual competition phase within a track | `trackId`, `stageType`, `name`, `slug`, `status`, `sortOrder`, `configJson`, `windowOpenAt`, `windowCloseAt` | → Track, → ProjectStageState[], → StageTransition[], → Cohort[], → LiveProgressCursor?, → LiveVotingSession? | +| **StageTransition** | Defines valid stage-to-stage movements | `fromStageId`, `toStageId`, `isDefault`, `guardJson` | → Stage (from), → Stage (to) | +| **ProjectStageState** | Tracks project position in pipeline | `projectId`, `trackId`, `stageId`, `state`, `enteredAt`, `exitedAt`, `metadataJson` | → Project, → Track, → Stage | +| **Cohort** | Groups projects for live voting | `stageId`, `name`, `votingMode`, `isOpen`, `windowOpenAt`, `windowCloseAt` | → Stage, → CohortProject[] | +| **CohortProject** | Project membership in a cohort | `cohortId`, `projectId`, `sortOrder` | → Cohort, → Project | + +### 1.2 Project & Submission Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **Project** | Core project/application entity | `programId`, `title`, `teamName`, `description`, `competitionCategory`, `oceanIssue`, `country`, `geographicZone`, `institution`, `wantsMentorship`, `foundedAt`, `status`, `submissionSource`, `submittedByEmail`, `submittedAt`, `tags`, `metadataJson`, `isDraft` | → Program, → ProjectFile[], → Assignment[], → TeamMember[], → MentorAssignment?, → FilteringResult[], → AwardEligibility[], → ProjectStageState[], → CohortProject[] | +| **ProjectFile** | File uploads attached to projects | `projectId`, `requirementId`, `fileType`, `fileName`, `mimeType`, `size`, `bucket`, `objectKey`, `version`, `replacedById`, `isLate` | → Project, → FileRequirement?, → ProjectFile (versioning) | +| **FileRequirement** | Defines required file uploads per stage | `stageId`, `name`, `description`, `acceptedMimeTypes`, `maxSizeMB`, `isRequired`, `sortOrder` | → Stage, ← ProjectFile[] | +| **TeamMember** | Team composition for projects | `projectId`, `userId`, `role`, `title` | → Project, → User | + +### 1.3 Jury & Evaluation Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **Assignment** | Jury member assigned to evaluate a project | `userId`, `projectId`, `stageId`, `method`, `isRequired`, `isCompleted`, `aiConfidenceScore`, `expertiseMatchScore`, `aiReasoning` | → User, → Project, → Stage, → Evaluation?, → ConflictOfInterest? | +| **Evaluation** | Jury member's assessment of a project | `assignmentId`, `formId`, `status`, `criterionScoresJson`, `globalScore`, `binaryDecision`, `feedbackText`, `version`, `submittedAt` | → Assignment, → EvaluationForm | +| **EvaluationForm** | Configurable evaluation criteria per stage | `stageId`, `version`, `criteriaJson`, `scalesJson`, `isActive` | → Stage, ← Evaluation[] | +| **ConflictOfInterest** | COI declarations by jury members | `assignmentId`, `userId`, `projectId`, `hasConflict`, `conflictType`, `description`, `declaredAt`, `reviewedById`, `reviewAction` | → Assignment, → User, → User (reviewer) | +| **GracePeriod** | Extended deadlines for specific jury members | `stageId`, `userId`, `projectId`, `extendedUntil`, `reason`, `grantedById` | → Stage, → User, → User (granter) | +| **EvaluationSummary** | AI-generated synthesis of evaluations | `projectId`, `stageId`, `summaryJson`, `generatedAt`, `generatedById`, `model`, `tokensUsed` | → Project, → Stage, → User | +| **EvaluationDiscussion** | Discussion thread for deliberation | `projectId`, `stageId`, `status`, `createdAt`, `closedAt`, `closedById` | → Project, → Stage, → User, → DiscussionComment[] | +| **DiscussionComment** | Individual comment in discussion | `discussionId`, `userId`, `content`, `createdAt` | → EvaluationDiscussion, → User | + +### 1.4 Live Voting Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **LiveVotingSession** | Live final event configuration | `stageId`, `status`, `currentProjectIndex`, `currentProjectId`, `votingStartedAt`, `votingEndsAt`, `projectOrderJson`, `votingMode`, `criteriaJson`, `allowAudienceVotes`, `audienceVoteWeight`, `tieBreakerMethod` | → Stage, → LiveVote[], → AudienceVoter[] | +| **LiveVote** | Individual vote during live event | `sessionId`, `projectId`, `userId`, `score`, `isAudienceVote`, `votedAt`, `criterionScoresJson`, `audienceVoterId` | → LiveVotingSession, → User?, → AudienceVoter? | +| **AudienceVoter** | Anonymous audience participant | `sessionId`, `token`, `identifier`, `identifierType`, `ipAddress`, `userAgent` | → LiveVotingSession, → LiveVote[] | +| **LiveProgressCursor** | Real-time cursor for live presentation | `stageId`, `sessionId`, `activeProjectId`, `activeOrderIndex`, `isPaused` | → Stage | + +### 1.5 Awards Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **SpecialAward** | Special prize/recognition category | `programId`, `trackId`, `name`, `description`, `status`, `criteriaText`, `autoTagRulesJson`, `useAiEligibility`, `scoringMode`, `maxRankedPicks`, `votingStartAt`, `votingEndAt`, `winnerProjectId`, `winnerOverridden`, `eligibilityJobStatus` | → Program, → Track?, → Project (winner), → AwardEligibility[], → AwardJuror[], → AwardVote[] | +| **AwardEligibility** | AI-determined award eligibility | `awardId`, `projectId`, `method`, `eligible`, `aiReasoningJson`, `overriddenBy`, `overriddenAt` | → SpecialAward, → Project, → User? | +| **AwardJuror** | Jury panel for special award | `awardId`, `userId` | → SpecialAward, → User | +| **AwardVote** | Vote for special award winner | `awardId`, `userId`, `projectId`, `rank`, `votedAt` | → SpecialAward, → User, → Project | + +### 1.6 Mentoring Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **MentorAssignment** | Mentor-project pairing | `projectId`, `mentorId`, `method`, `assignedAt`, `assignedBy`, `aiConfidenceScore`, `expertiseMatchScore`, `completionStatus` | → Project (unique), → User (mentor), → MentorNote[], → MentorMilestoneCompletion[] | +| **MentorMessage** | Chat messages between mentor and team | `projectId`, `senderId`, `message`, `isRead` | → Project, → User | +| **MentorNote** | Private notes by mentor/admin | `mentorAssignmentId`, `authorId`, `content`, `isVisibleToAdmin` | → MentorAssignment, → User | +| **MentorMilestone** | Program-wide mentorship checkpoints | `programId`, `name`, `description`, `isRequired`, `deadlineOffsetDays`, `sortOrder` | → Program, → MentorMilestoneCompletion[] | +| **MentorMilestoneCompletion** | Completion record for milestones | `milestoneId`, `mentorAssignmentId`, `completedById`, `completedAt` | → MentorMilestone, → MentorAssignment, → User | + +### 1.7 Filtering Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **FilteringRule** | Automated screening rule | `stageId`, `name`, `ruleType`, `configJson`, `priority`, `isActive` | → Stage | +| **FilteringResult** | Per-project filtering outcome | `stageId`, `projectId`, `outcome`, `ruleResultsJson`, `aiScreeningJson`, `overriddenBy`, `overriddenAt`, `overrideReason`, `finalOutcome` | → Stage, → Project, → User? | +| **FilteringJob** | Progress tracking for filtering runs | `stageId`, `status`, `totalProjects`, `processedCount`, `passedCount`, `filteredCount`, `flaggedCount`, `errorMessage`, `startedAt`, `completedAt` | → Stage | +| **AssignmentJob** | Progress tracking for assignment generation | `stageId`, `status`, `totalProjects`, `processedCount`, `suggestionsCount`, `suggestionsJson`, `errorMessage`, `fallbackUsed` | → Stage | +| **TaggingJob** | Progress tracking for AI tagging | `programId`, `status`, `totalProjects`, `processedCount`, `taggedCount`, `skippedCount`, `failedCount`, `errorsJson` | → Program? | + +### 1.8 Users & Auth Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **User** | Platform user account | `email`, `name`, `role`, `status`, `expertiseTags`, `maxAssignments`, `country`, `bio`, `phoneNumber`, `notificationPreference`, `digestFrequency`, `preferredWorkload`, `passwordHash`, `inviteToken`, `onboardingCompletedAt` | → Assignment[], → GracePeriod[], → LiveVote[], → TeamMember[], → MentorAssignment[], → AwardJuror[], → ConflictOfInterest[], → InAppNotification[] | +| **Account** | NextAuth provider accounts | `userId`, `provider`, `providerAccountId`, `access_token`, `refresh_token` | → User | +| **Session** | NextAuth active sessions | `userId`, `sessionToken`, `expires` | → User | +| **VerificationToken** | NextAuth magic link tokens | `identifier`, `token`, `expires` | (standalone) | + +### 1.9 Audit & Logging Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **AuditLog** | General platform activity log | `userId`, `action`, `entityType`, `entityId`, `detailsJson`, `previousDataJson`, `ipAddress`, `userAgent`, `sessionId`, `timestamp` | → User? | +| **DecisionAuditLog** | Pipeline decision tracking | `eventType`, `entityType`, `entityId`, `actorId`, `detailsJson`, `snapshotJson`, `createdAt` | (no FK relations) | +| **OverrideAction** | Manual admin overrides log | `entityType`, `entityId`, `previousValue`, `newValueJson`, `reasonCode`, `reasonText`, `actorId`, `createdAt` | (no FK relations) | +| **AIUsageLog** | AI API consumption tracking | `userId`, `action`, `entityType`, `entityId`, `model`, `promptTokens`, `completionTokens`, `estimatedCostUsd`, `status`, `errorMessage` | (no FK relations) | +| **NotificationLog** | Email/SMS delivery tracking | `userId`, `channel`, `provider`, `type`, `status`, `externalId`, `errorMsg` | → User | + +### 1.10 Program & Resources Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **Program** | Competition edition/year | `name`, `slug`, `year`, `status`, `description`, `settingsJson` | → Pipeline[], → Project[], → LearningResource[], → Partner[], → SpecialAward[] | +| **LearningResource** | Educational content for teams | `programId`, `title`, `description`, `contentJson`, `resourceType`, `cohortLevel`, `fileName`, `mimeType`, `bucket`, `objectKey`, `externalUrl`, `isPublished` | → Program?, → User (creator), → ResourceAccess[] | +| **ResourceAccess** | Access log for learning materials | `resourceId`, `userId`, `accessedAt`, `ipAddress` | → LearningResource, → User | +| **Partner** | Sponsor/partner organization | `programId`, `name`, `description`, `website`, `partnerType`, `visibility`, `logoFileName`, `sortOrder`, `isActive` | → Program? | +| **WizardTemplate** | Saved pipeline configuration templates | `name`, `description`, `config`, `isGlobal`, `programId`, `createdBy` | → Program?, → User | + +### 1.11 Communication Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **InAppNotification** | Bell icon notifications | `userId`, `type`, `priority`, `icon`, `title`, `message`, `linkUrl`, `linkLabel`, `metadata`, `groupKey`, `isRead`, `expiresAt` | → User | +| **NotificationEmailSetting** | Email notification toggles per type | `notificationType`, `category`, `label`, `sendEmail`, `emailSubject`, `emailTemplate` | (standalone) | +| **NotificationPolicy** | Event-driven notification config | `eventType`, `channel`, `templateId`, `isActive`, `configJson` | (no FK relations) | +| **Message** | Bulk messaging system | `senderId`, `recipientType`, `recipientFilter`, `stageId`, `templateId`, `subject`, `body`, `deliveryChannels`, `scheduledAt`, `sentAt` | → User (sender), → Stage?, → MessageTemplate?, → MessageRecipient[] | +| **MessageRecipient** | Individual message delivery | `messageId`, `userId`, `channel`, `isRead`, `readAt`, `deliveredAt` | → Message, → User | +| **MessageTemplate** | Reusable email templates | `name`, `category`, `subject`, `body`, `variables`, `isActive`, `createdBy` | → User, ← Message[] | + +### 1.12 Webhooks & Integrations + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **Webhook** | Outbound event webhooks | `name`, `url`, `secret`, `events`, `headers`, `maxRetries`, `isActive`, `createdById` | → User, → WebhookDelivery[] | +| **WebhookDelivery** | Webhook delivery log | `webhookId`, `event`, `payload`, `status`, `responseStatus`, `responseBody`, `attempts`, `lastAttemptAt` | → Webhook | + +### 1.13 Miscellaneous Models + +| Model | Purpose | Key Fields | Relations | +|-------|---------|------------|-----------| +| **SystemSettings** | Platform-wide config KV store | `key`, `value`, `type`, `category`, `description`, `isSecret` | (standalone) | +| **ExpertiseTag** | Tag taxonomy for matching | `name`, `description`, `category`, `color`, `isActive`, `sortOrder` | → ProjectTag[] | +| **ProjectTag** | Project-tag association | `projectId`, `tagId`, `confidence`, `source` | → Project, → ExpertiseTag | +| **ProjectStatusHistory** | Historical status changes | `projectId`, `status`, `changedAt`, `changedBy` | → Project | +| **ReminderLog** | Evaluation deadline reminders | `stageId`, `userId`, `type`, `sentAt` | → Stage, → User | +| **DigestLog** | Email digest delivery log | `userId`, `digestType`, `contentJson`, `sentAt` | → User | + +--- + +## 2. Enums + +### 2.1 User & Auth Enums + +| Enum | Values | Usage | +|------|--------|-------| +| **UserRole** | `SUPER_ADMIN`, `PROGRAM_ADMIN`, `JURY_MEMBER`, `MENTOR`, `OBSERVER`, `APPLICANT`, `AWARD_MASTER`, `AUDIENCE` | User permissions hierarchy | +| **UserStatus** | `NONE`, `INVITED`, `ACTIVE`, `SUSPENDED` | User account state | + +### 2.2 Project & Competition Enums + +| Enum | Values | Usage | +|------|--------|-------| +| **ProjectStatus** | `SUBMITTED`, `ELIGIBLE`, `ASSIGNED`, `SEMIFINALIST`, `FINALIST`, `REJECTED` | Legacy project state (superseded by ProjectStageState) | +| **CompetitionCategory** | `STARTUP`, `BUSINESS_CONCEPT` | Project type (existing company vs. student idea) | +| **OceanIssue** | `POLLUTION_REDUCTION`, `CLIMATE_MITIGATION`, `TECHNOLOGY_INNOVATION`, `SUSTAINABLE_SHIPPING`, `BLUE_CARBON`, `HABITAT_RESTORATION`, `COMMUNITY_CAPACITY`, `SUSTAINABLE_FISHING`, `CONSUMER_AWARENESS`, `OCEAN_ACIDIFICATION`, `OTHER` | Project focus area | + +### 2.3 Pipeline Enums + +| Enum | Values | Usage | +|------|--------|-------| +| **StageType** | `INTAKE`, `FILTER`, `EVALUATION`, `SELECTION`, `LIVE_FINAL`, `RESULTS` | Stage functional type | +| **TrackKind** | `MAIN`, `AWARD`, `SHOWCASE` | Track purpose | +| **RoutingMode** | `SHARED`, `EXCLUSIVE` | Project routing behavior (can projects be in multiple tracks?) | +| **StageStatus** | `STAGE_DRAFT`, `STAGE_ACTIVE`, `STAGE_CLOSED`, `STAGE_ARCHIVED` | Stage lifecycle state | +| **ProjectStageStateValue** | `PENDING`, `IN_PROGRESS`, `PASSED`, `REJECTED`, `ROUTED`, `COMPLETED`, `WITHDRAWN` | Project state within a stage | +| **DecisionMode** | `JURY_VOTE`, `AWARD_MASTER_DECISION`, `ADMIN_DECISION` | How winners are determined in a track | + +### 2.4 Evaluation & Assignment Enums + +| Enum | Values | Usage | +|------|--------|-------| +| **EvaluationStatus** | `NOT_STARTED`, `DRAFT`, `SUBMITTED`, `LOCKED` | Evaluation completion state | +| **AssignmentMethod** | `MANUAL`, `BULK`, `AI_SUGGESTED`, `AI_AUTO`, `ALGORITHM` | How assignment was created | +| **MentorAssignmentMethod** | `MANUAL`, `AI_SUGGESTED`, `AI_AUTO`, `ALGORITHM` | How mentor was paired | + +### 2.5 Filtering Enums + +| Enum | Values | Usage | +|------|--------|-------| +| **FilteringOutcome** | `PASSED`, `FILTERED_OUT`, `FLAGGED` | Filtering result | +| **FilteringRuleType** | `FIELD_BASED`, `DOCUMENT_CHECK`, `AI_SCREENING` | Type of filtering rule | +| **FilteringJobStatus** | `PENDING`, `RUNNING`, `COMPLETED`, `FAILED` | Job progress state | +| **AssignmentJobStatus** | `PENDING`, `RUNNING`, `COMPLETED`, `FAILED` | Job progress state | +| **TaggingJobStatus** | `PENDING`, `RUNNING`, `COMPLETED`, `FAILED` | Job progress state | + +### 2.6 Awards Enums + +| Enum | Values | Usage | +|------|--------|-------| +| **AwardScoringMode** | `PICK_WINNER`, `RANKED`, `SCORED` | Award voting method | +| **AwardStatus** | `DRAFT`, `NOMINATIONS_OPEN`, `VOTING_OPEN`, `CLOSED`, `ARCHIVED` | Award lifecycle | +| **EligibilityMethod** | `AUTO`, `MANUAL` | How eligibility was determined | + +### 2.7 Miscellaneous Enums + +| Enum | Values | Usage | +|------|--------|-------| +| **FileType** | `EXEC_SUMMARY`, `PRESENTATION`, `VIDEO`, `OTHER`, `BUSINESS_PLAN`, `VIDEO_PITCH`, `SUPPORTING_DOC` | Project file categorization | +| **SubmissionSource** | `MANUAL`, `CSV`, `NOTION`, `TYPEFORM`, `PUBLIC_FORM` | How project was submitted | +| **NotificationChannel** | `EMAIL`, `WHATSAPP`, `BOTH`, `NONE` | Notification delivery method | +| **ResourceType** | `PDF`, `VIDEO`, `DOCUMENT`, `LINK`, `OTHER` | Learning resource type | +| **CohortLevel** | `ALL`, `SEMIFINALIST`, `FINALIST` | Access level for resources | +| **PartnerVisibility** | `ADMIN_ONLY`, `JURY_VISIBLE`, `PUBLIC` | Who can see partner | +| **PartnerType** | `SPONSOR`, `PARTNER`, `SUPPORTER`, `MEDIA`, `OTHER` | Partner categorization | +| **TeamMemberRole** | `LEAD`, `MEMBER`, `ADVISOR` | Team composition | +| **OverrideReasonCode** | `DATA_CORRECTION`, `POLICY_EXCEPTION`, `JURY_CONFLICT`, `SPONSOR_DECISION`, `ADMIN_DISCRETION` | Why decision was overridden | +| **ProgramStatus** | `DRAFT`, `ACTIVE`, `ARCHIVED` | Program lifecycle | +| **SettingType** | `STRING`, `NUMBER`, `BOOLEAN`, `JSON`, `SECRET` | System setting data type | +| **SettingCategory** | `AI`, `BRANDING`, `EMAIL`, `STORAGE`, `SECURITY`, `DEFAULTS`, `WHATSAPP`, `AUDIT_CONFIG`, `LOCALIZATION`, `DIGEST`, `ANALYTICS`, `INTEGRATIONS`, `COMMUNICATION` | Setting organization | + +--- + +## 3. Services + +All services located in `src/server/services/*.ts`. + +| Service | Purpose | Key Functions | +|---------|---------|---------------| +| **stage-engine.ts** | State machine for project transitions | `validateTransition()`, `executeTransition()`, `executeBatchTransition()` - handles guard evaluation, atomic PSS updates, audit logging | +| **stage-filtering.ts** | Runs filtering pipeline scoped to stage | `runStageFiltering()`, `resolveManualDecision()`, `getManualQueue()` - executes field-based, document, and AI rules; duplicate detection built-in | +| **stage-assignment.ts** | Smart jury assignment generation | `previewStageAssignment()`, `executeStageAssignment()`, `getCoverageReport()`, `rebalance()` - tag matching, workload balancing, COI handling | +| **stage-notifications.ts** | Event-driven notification producer | `emitStageEvent()`, `onStageTransitioned()`, `onFilteringCompleted()`, `onAssignmentGenerated()`, `onCursorUpdated()` - never throws, creates DecisionAuditLog + in-app + email | +| **live-control.ts** | Real-time live ceremony control | `startSession()`, `setActiveProject()`, `jumpToProject()`, `reorderQueue()`, `pauseResume()`, `openCohortWindow()`, `closeCohortWindow()` - manages LiveProgressCursor | +| **ai-filtering.ts** | AI-powered project screening | Anonymizes data, calls OpenAI API, confidence banding, spam detection (delegates to stage-filtering.ts for execution) | +| **ai-assignment.ts** | AI-suggested jury matching | GPT-based assignment generation with expertise matching (100 lines) | +| **ai-evaluation-summary.ts** | GPT synthesis of evaluations | Generates strengths/weaknesses summary from jury feedback | +| **ai-tagging.ts** | Automatic project categorization | Tags projects with expertise areas using GPT | +| **ai-award-eligibility.ts** | Award eligibility assessment | GPT determines if project meets award criteria | +| **anonymization.ts** | GDPR-compliant data stripping | Removes PII before AI calls (name, email, institution, etc.) | +| **ai-errors.ts** | Centralized AI error handling | Classifies errors (rate limit, token limit, API down), provides retry logic | +| **award-eligibility-job.ts** | Batch award eligibility processing | Runs AI eligibility checks across all projects for an award | +| **smart-assignment.ts** | Scoring algorithm for matching | Tag overlap, bio match, workload balance, geo diversity, COI blocking, availability checking | +| **mentor-matching.ts** | Mentor-project pairing logic | Similar to smart-assignment but for mentorship | +| **evaluation-reminders.ts** | Cron job for deadline reminders | Sends 3-day, 24h, 1h reminders to jury with incomplete evaluations | +| **email-digest.ts** | Daily/weekly email summaries | Aggregates pending tasks for users | +| **in-app-notification.ts** | In-app notification helpers | Creates bell-icon notifications with linking | +| **notification.ts** | Email sending service | Wraps Nodemailer, supports templates | +| **webhook-dispatcher.ts** | Webhook delivery service | Sends events to registered webhook URLs with retry logic | + +--- + +## 4. tRPC Routers + +All routers located in `src/server/routers/*.ts`. Total: 38 routers. + +| Router | Procedure Count | Key Procedures | Purpose | +|--------|-----------------|----------------|---------| +| **pipeline.ts** | ~15 | `create`, `update`, `delete`, `list`, `getById`, `archive` | Pipeline CRUD, linking to Program | +| **stage.ts** | ~20 | `create`, `updateConfig`, `updateStatus`, `delete`, `getByTrack`, `reorderStages`, `createTransition` | Stage CRUD, window management, transition setup | +| **stageFiltering.ts** | ~10 | `createRule`, `runFiltering`, `getManualQueue`, `resolveManualDecision`, `getJobStatus` | Filtering rule management + execution | +| **stageAssignment.ts** | ~8 | `previewAssignment`, `executeAssignment`, `getCoverage`, `rebalance`, `bulkDelete` | Assignment generation, coverage analysis | +| **project.ts** | ~25 | `create`, `update`, `delete`, `getById`, `list`, `import`, `advanceToRound`, `updateStatus` | Project CRUD, CSV import, status changes | +| **assignment.ts** | ~12 | `create`, `bulkCreate`, `delete`, `getByUser`, `getByProject`, `markComplete` | Manual assignment management | +| **evaluation.ts** | ~15 | `create`, `update`, `submit`, `lock`, `unlock`, `getByAssignment`, `generateSummary` | Evaluation submission, locking | +| **gracePeriod.ts** | ~6 | `create`, `delete`, `getByStage`, `getByUser`, `checkActive` | Grace period management | +| **user.ts** | ~20 | `create`, `update`, `delete`, `invite`, `resendInvite`, `list`, `updateProfile`, `uploadAvatar` | User management, invites | +| **specialAward.ts** | ~15 | `create`, `update`, `delete`, `runEligibility`, `vote`, `getResults`, `overrideWinner` | Award creation, voting, eligibility | +| **live-voting.ts** | ~12 | `createSession`, `vote`, `getResults`, `closeSession`, `updateCriteria` | Live voting session management (legacy LiveVotingSession model) | +| **live.ts** | ~10 | `startSession`, `setActiveProject`, `jumpToProject`, `pauseResume`, `openCohort`, `closeCohort` | Live control (new LiveProgressCursor model) | +| **cohort.ts** | ~8 | `create`, `update`, `delete`, `addProjects`, `removeProjects`, `reorder` | Cohort management for live finals | +| **mentor.ts** | ~12 | `assignMentor`, `removeMentor`, `sendMessage`, `addNote`, `completeMilestone`, `getMentorDashboard` | Mentorship workflow | +| **learningResource.ts** | ~10 | `create`, `update`, `delete`, `list`, `upload`, `markAccessed` | Learning hub content | +| **partner.ts** | ~8 | `create`, `update`, `delete`, `list`, `uploadLogo` | Partner management | +| **tag.ts** | ~10 | `create`, `update`, `delete`, `list`, `runTagging`, `getTaggingJobStatus` | Expertise tag management | +| **notification.ts** | ~8 | `getInApp`, `markRead`, `markAllRead`, `getUnreadCount`, `updateEmailSettings` | Notification center | +| **message.ts** | ~10 | `send`, `schedule`, `list`, `getRecipients`, `createTemplate`, `listTemplates` | Bulk messaging | +| **webhook.ts** | ~8 | `create`, `update`, `delete`, `test`, `getDeliveries`, `retry` | Webhook management | +| **audit.ts** | ~6 | `getAuditLog`, `getDecisionLog`, `getOverrides`, `export` | Audit trail viewing | +| **analytics.ts** | ~12 | `getDashboardStats`, `getProjectStats`, `getJuryStats`, `getAwardStats`, `getEngagementMetrics` | Reporting and analytics | +| **dashboard.ts** | ~8 | `getAdminDashboard`, `getJuryDashboard`, `getApplicantDashboard`, `getMentorDashboard` | Role-specific dashboards | +| **export.ts** | ~8 | `exportProjects`, `exportEvaluations`, `exportVotes`, `exportAuditLog` | CSV/Excel exports | +| **file.ts** | ~8 | `uploadFile`, `getPresignedUrl`, `deleteFile`, `listFiles`, `createRequirement` | MinIO file management | +| **filtering.ts** | ~6 | Legacy filtering endpoints (superseded by stageFiltering) | Deprecated | +| **avatar.ts** | ~4 | `upload`, `delete`, `getUrl` | User profile images | +| **logo.ts** | ~4 | `upload`, `delete`, `getUrl` | Project logos | +| **decision.ts** | ~6 | `overrideFilteringResult`, `overrideAwardEligibility`, `overridePSS`, `getOverrideHistory` | Admin override controls | +| **program.ts** | ~10 | `create`, `update`, `delete`, `list`, `getById`, `archive` | Program CRUD | +| **application.ts** | ~8 | `submitApplication`, `saveDraft`, `getDraft`, `deleteDraft` | Public application form | +| **applicant.ts** | ~10 | `getMyProjects`, `updateTeam`, `uploadDocument`, `requestMentorship` | Applicant portal | +| **notion-import.ts** | ~4 | `sync`, `import`, `getStatus` | Notion integration | +| **typeform-import.ts** | ~4 | `sync`, `import`, `getStatus` | Typeform integration | +| **settings.ts** | ~8 | `get`, `set`, `getBulk`, `setBulk`, `getByCategory` | System settings KV store | +| **project-pool.ts** | ~6 | `getUnassignedProjects`, `getProjectsByStage`, `getProjectsByStatus` | Project queries for assignment | +| **wizard-template.ts** | ~8 | `create`, `update`, `delete`, `list`, `clone`, `applyTemplate` | Pipeline wizard templates | + +**Total Procedures:** ~400+ + +--- + +## 5. UI Pages + +### 5.1 Admin Pages (`src/app/(admin)/admin/`) + +| Route | Purpose | Key Features | +|-------|---------|--------------| +| `/admin` | Admin dashboard | Overview metrics, recent activity, quick actions | +| `/admin/members` | User management list | User table with filters, role assignment, status changes | +| `/admin/members/[id]` | User detail/edit | Profile editing, role changes, assignment history | +| `/admin/members/invite` | Invite new users | Bulk invite form with role selection | +| `/admin/programs` | Program list | Program cards, create/archive/edit | +| `/admin/programs/[id]` | Program detail | Program overview, linked pipelines, projects | +| `/admin/programs/[id]/edit` | Program settings editor | Name, year, status, settingsJson editor | +| `/admin/programs/[id]/apply-settings` | Application form config | Public submission form customization | +| `/admin/programs/[id]/mentorship` | Mentorship milestones | Milestone creation, completion tracking | +| `/admin/projects` | Project list | Searchable/filterable project table | +| `/admin/projects/[id]` | Project detail | Full project view with evaluations, history | +| `/admin/projects/[id]/edit` | Project editor | Edit project metadata, team, tags | +| `/admin/projects/[id]/mentor` | Mentor assignment | Assign/remove mentor, view messages | +| `/admin/projects/new` | Manual project creation | Add project without public form | +| `/admin/projects/import` | CSV/Typeform/Notion import | Bulk import wizard | +| `/admin/projects/pool` | Unassigned project pool | Projects awaiting assignment | +| `/admin/rounds/pipelines` | Pipeline list | All pipelines across programs | +| `/admin/rounds/pipeline/[id]` | Pipeline detail | Track/stage tree, project flow diagram | +| `/admin/rounds/pipeline/[id]/edit` | Pipeline settings | Name, slug, status, settingsJson | +| `/admin/rounds/pipeline/[id]/wizard` | Pipeline wizard | Step-by-step configuration UI (tracks, stages, transitions) | +| `/admin/rounds/pipeline/[id]/advanced` | Advanced pipeline editor | JSON config editor, raw transitions | +| `/admin/rounds/new-pipeline` | Pipeline creation wizard | Multi-step pipeline setup | +| `/admin/awards` | Special awards list | Award cards with status | +| `/admin/awards/[id]` | Award detail | Eligibility, votes, results | +| `/admin/awards/[id]/edit` | Award editor | Criteria, voting config, jury panel | +| `/admin/awards/new` | Create award | Award creation form | +| `/admin/mentors` | Mentor list | All users with MENTOR role | +| `/admin/mentors/[id]` | Mentor detail | Assigned projects, notes, milestones | +| `/admin/learning` | Learning hub management | Resource list, upload, publish | +| `/admin/learning/[id]` | Resource detail/edit | Content editor (BlockNote), access logs | +| `/admin/learning/new` | Create resource | Upload or link external content | +| `/admin/partners` | Partner management | Partner list, logos, visibility | +| `/admin/partners/[id]` | Partner detail/edit | Edit partner info, upload logo | +| `/admin/partners/new` | Add partner | Partner creation form | +| `/admin/messages` | Messaging dashboard | Send bulk messages, view sent messages | +| `/admin/messages/templates` | Message templates | Template CRUD | +| `/admin/settings` | System settings | Category tabs, KV editor | +| `/admin/settings/tags` | Expertise tags | Tag taxonomy management | +| `/admin/settings/webhooks` | Webhook management | Webhook CRUD, delivery logs | +| `/admin/audit` | Audit log viewer | Searchable audit trail | +| `/admin/reports` | Analytics reports | Charts, exports, metrics | +| `/admin/reports/stages` | Stage-level reports | Per-stage assignment coverage, completion rates | + +### 5.2 Jury Pages (`src/app/(jury)/jury/`) + +| Route | Purpose | Key Features | +|-------|---------|--------------| +| `/jury` | Jury dashboard | Assigned stages, pending evaluations, deadlines | +| `/jury/stages` | Jury stage list | Stages where user has assignments | +| `/jury/stages/[stageId]/assignments` | Assignment list for stage | Projects assigned to this user | +| `/jury/stages/[stageId]/projects/[projectId]` | Project detail view | Full project info, files, team | +| `/jury/stages/[stageId]/projects/[projectId]/evaluate` | Evaluation form | Criterion scoring, feedback, submit | +| `/jury/stages/[stageId]/projects/[projectId]/evaluation` | View submitted evaluation | Read-only evaluation, edit if not locked | +| `/jury/stages/[stageId]/compare` | Side-by-side comparison | Compare multiple projects, scoring matrix | +| `/jury/stages/[stageId]/live` | Live voting interface | Real-time voting during live ceremony | +| `/jury/awards` | Special awards list | Awards where user is juror | +| `/jury/awards/[id]` | Award voting | View eligible projects, cast votes | +| `/jury/learning` | Learning hub (jury access) | Resources for jury members | + +### 5.3 Applicant Pages (`src/app/(applicant)/applicant/`) + +| Route | Purpose | Key Features | +|-------|---------|--------------| +| `/applicant` | Applicant dashboard | Application status, next steps | +| `/applicant/pipeline` | Pipeline progress view | Visual pipeline with current stage | +| `/applicant/pipeline/[stageId]/status` | Stage detail view | Stage status, requirements, deadlines | +| `/applicant/pipeline/[stageId]/documents` | Document upload | Upload required files for stage | +| `/applicant/documents` | All documents | Document library, versions | +| `/applicant/team` | Team management | Add/remove team members, roles | +| `/applicant/mentor` | Mentorship dashboard | Chat with mentor, milestones | + +### 5.4 Auth Pages (`src/app/(auth)/`) + +| Route | Purpose | Key Features | +|-------|---------|--------------| +| `/login` | Login page | Email magic link + password login | +| `/verify` | Magic link verification | Token verification, auto-login | +| `/verify-email` | Email verification | Verify email after signup | +| `/accept-invite` | Invitation acceptance | One-click invite token handling | +| `/set-password` | Password setup | First-time password creation | +| `/onboarding` | User onboarding wizard | Profile completion, expertise tags | +| `/error` | Auth error page | Error display with retry | + +--- + +## 6. Strengths of Current System + +### 6.1 Architecture Strengths + +| Strength | Description | +|----------|-------------| +| **Full Type Safety** | End-to-end TypeScript from DB → tRPC → React. Prisma generates types, tRPC enforces them, components consume them safely. | +| **Atomic Transactions** | All critical operations (stage transitions, filtering, assignments) use `$transaction` with proper rollback. | +| **Comprehensive Audit** | Dual audit system: `AuditLog` for general activity, `DecisionAuditLog` for pipeline decisions. Full traceability. | +| **RBAC Enforcement** | tRPC middleware hierarchy (`adminProcedure`, `juryProcedure`, etc.) enforces role-based access at API level. | +| **GDPR Compliance** | All AI calls strip PII via `anonymization.ts`. No personal data sent to OpenAI. | +| **Event-Driven Design** | `stage-notifications.ts` emits events on every pipeline action. Notifications never block core operations (catch all errors). | +| **Graceful AI Error Handling** | `ai-errors.ts` classifies errors (rate limit, token limit, API down) and provides retry guidance. AI failures never crash the system. | +| **Duplicate Detection** | Built-in duplicate submission detection in `stage-filtering.ts` (by email). Always flags for manual review, never auto-rejects. | + +### 6.2 Data Model Strengths + +| Strength | Description | +|----------|-------------| +| **Flexible Pipeline Model** | Pipeline → Track → Stage → ProjectStageState allows arbitrary round structures. Main track + multiple award tracks supported. | +| **Guard-Based Transitions** | StageTransition `guardJson` field allows complex conditional routing (e.g., "only advance if avgScore >= 7"). | +| **Stage Config Polymorphism** | `Stage.configJson` adapts to `stageType`. FILTER stages have filtering config, EVALUATION stages have evaluation config, etc. | +| **Versioned Evaluations** | `Evaluation.version` field allows rollback (though not currently used). | +| **Override Audit Trail** | `OverrideAction` model logs all admin overrides with reason codes. Immutable audit. | + +### 6.3 Service Layer Strengths + +| Strength | Description | +|----------|-------------| +| **State Machine Isolation** | `stage-engine.ts` is the ONLY service that modifies `ProjectStageState`. All transitions go through it. Single source of truth. | +| **Service Purity** | Services are pure functions that accept Prisma client as parameter. Testable without mocking globals. | +| **Progress Tracking** | Long-running operations (filtering, assignment, tagging) use Job models (`FilteringJob`, `AssignmentJob`, `TaggingJob`) for progress tracking. | +| **AI Batching** | All AI services batch projects (20-50 per call) to reduce API cost and latency. | + +### 6.4 UX Strengths + +| Strength | Description | +|----------|-------------| +| **Wizard-Driven Setup** | Pipeline wizard (`/admin/rounds/pipeline/[id]/wizard`) guides admins through complex configuration. | +| **Real-Time Live Control** | `/jury/stages/[stageId]/live` provides live voting with cursor sync via `LiveProgressCursor`. | +| **Notification Center** | In-app notification bell with grouping, priorities, expiration. | +| **Grace Period UX** | Admins can grant individual deadline extensions with reason tracking. | +| **Filtering Manual Queue** | Flagged projects go to dedicated review queue (`/admin/rounds/pipeline/[id]/filtering/manual`) for admin decision. | + +--- + +## 7. Weaknesses of Current System + +### 7.1 Data Model Issues + +| Issue | Description | Impact | +|-------|-------------|--------| +| **Legacy `roundId` Fields** | 50+ models have `roundId String?` (marked "Legacy — kept for historical data"). Adds noise, not enforced. | Confusing for new developers. No FK constraints. | +| **Unclear Pipeline Lifecycle** | Pipeline has `status` enum (`DRAFT`, `ACTIVE`, `ARCHIVED`), but no enforcement. Active pipelines can have draft stages. | Inconsistent state possible. | +| **Overlapping Voting Models** | `LiveVotingSession` (old) and `Cohort` + `LiveProgressCursor` (new) both exist. Unclear which to use. | Duplicate functionality, confusion. | +| **No PSS Validation Constraints** | `ProjectStageState` allows multiple active (non-exited) records for same project/track/stage combo. Should be unique. | Data integrity risk. | +| **Track-Award Linkage Vague** | `SpecialAward.trackId` is optional. Unclear if awards MUST have a track or can exist independently. | Ambiguous design. | + +### 7.2 Service Layer Issues + +| Issue | Description | Impact | +|-------|-------------|--------| +| **Mixed Abstraction Levels** | `stage-filtering.ts` contains both high-level orchestration AND low-level rule evaluation. Hard to test individually. | Tight coupling. | +| **Notification Side Effects** | Services call `stage-notifications.ts` directly. If notification fails (e.g., email down), error is swallowed. | Lost notifications, no visibility. | +| **AI Service Duplication** | `ai-filtering.ts`, `ai-assignment.ts`, `ai-tagging.ts` all have similar batching/retry logic. Should be abstracted. | Code duplication. | +| **No Explicit Workflow Engine** | Stage transitions are ad-hoc. No central workflow definition. Must read code to understand flow. | Hard to visualize, modify. | + +### 7.3 tRPC Router Issues + +| Issue | Description | Impact | +|-------|-------------|--------| +| **Router Bloat** | `project.ts` has 25+ procedures. `user.ts` has 20+. Hard to navigate. | Monolithic routers. | +| **Inconsistent Naming** | `stage.ts` has `updateConfig`, `stage-filtering.ts` router has `updateRule`. Naming conventions vary. | Confusing API. | +| **No Batch Procedures** | Most CRUD operations are one-at-a-time. No bulk create/update/delete (except assignments). | N+1 queries in UI. | +| **Missing Pagination** | List procedures (`project.list`, `user.list`) return all records. No cursor or offset pagination. | Performance issue at scale. | + +### 7.4 UI/UX Issues + +| Issue | Description | Impact | +|-------|-------------|--------| +| **No Pipeline Visualization** | Pipeline detail page shows table of stages, not a flowchart. Hard to see transitions. | Poor admin UX. | +| **Filtering Manual Queue Hidden** | Flagged projects not prominently surfaced. Admin must navigate deep into pipeline detail. | Flagged items forgotten. | +| **No Bulk Actions** | Can't bulk-assign projects, bulk-approve evaluations, bulk-transition projects. Must click one-by-one. | Tedious admin work. | +| **Live Voting Lacks Feedback** | Jury votes during live event but doesn't see if vote was counted. No confirmation toast. | Uncertainty. | +| **No Undo** | All admin actions (delete pipeline, archive stage, reject project) are immediate. No soft delete or undo. | Risky operations. | + +### 7.5 Missing Features + +| Missing Feature | Description | Impact | +|-----------------|-------------|--------| +| **Stage Dependency Graph** | No visual representation of stage transitions and guards. Admin must infer from transitions table. | Hard to debug routing. | +| **Evaluation Calibration** | No juror calibration (e.g., flag jurors who score 10x higher/lower than peers). | Scoring bias undetected. | +| **Award Winner Tie-Breaking** | `SpecialAward.tieBreakerMethod` exists in `LiveVotingSession` but not in `SpecialAward`. No tie resolution for ranked awards. | Undefined behavior on ties. | +| **Project Search Ranking** | Project search is basic string match. No relevance ranking, fuzzy matching, or faceted filters. | Poor search UX. | +| **Stage Templates** | No template system for common stage configs (e.g., "Standard 3-juror evaluation stage"). | Repetitive setup. | +| **Notification Preferences** | Users can toggle email on/off globally but not per event type. No granular control. | All-or-nothing notifications. | +| **Pipeline Cloning** | No way to duplicate a pipeline for a new year/program. Must recreate manually. | Time-consuming setup. | +| **Evaluation Rubric Library** | Each stage creates evaluation forms from scratch. No reusable rubrics. | Reinventing the wheel. | + +### 7.6 Code Quality Issues + +| Issue | Description | Impact | +|-------|-------------|--------| +| **Inconsistent Error Messages** | Some procedures throw `TRPCError` with clear messages, others just throw generic Error. | Debugging harder. | +| **No Input Sanitization** | Zod validates types but doesn't trim strings, lowercase emails, etc. | Data inconsistency. | +| **Magic Numbers** | Hardcoded constants (e.g., `AI_CONFIDENCE_THRESHOLD_PASS = 0.75`) scattered across services. | Hard to tune. | +| **Limited Test Coverage** | Only `stage-engine.test.ts` exists. No tests for filtering, assignment, AI services. | Regression risk. | +| **No API Versioning** | tRPC routers have no version prefix. Breaking changes would break old clients. | API fragility. | + +### 7.7 Performance Issues + +| Issue | Description | Impact | +|-------|-------------|--------| +| **N+1 Queries** | Project list page loads projects, then fetches assignments for each in a loop. | Slow page load. | +| **No Caching** | Every tRPC call hits database. No Redis, no in-memory cache. | High DB load. | +| **Unindexed Joins** | Some `ProjectStageState` queries join on `(projectId, trackId)` without composite index. | Slow at scale. | +| **AI Batching Non-Optimal** | AI services batch by count (20 projects) not by token size. Large projects can exceed token limits. | API errors. | + +### 7.8 Documentation Issues + +| Issue | Description | Impact | +|-------|-------------|--------| +| **No Architecture Docs** | No high-level system overview. New developers must read code. | Steep onboarding. | +| **Minimal JSDoc** | Most services have file-level comments but not function-level. | Hard to use without reading implementation. | +| **No API Reference** | tRPC procedures not documented in OpenAPI or similar. | Client integration difficult. | +| **No Runbook** | No operational docs for common tasks (e.g., "How to fix a stuck pipeline"). | Manual troubleshooting. | + +--- + +## Summary Statistics + +| Category | Count | +|----------|-------| +| **Database Models** | 73 | +| **Enums** | 31 | +| **Service Files** | 20 | +| **tRPC Routers** | 38 | +| **tRPC Procedures** | ~400 | +| **Admin Pages** | 45 | +| **Jury Pages** | 11 | +| **Applicant Pages** | 7 | +| **Auth Pages** | 7 | +| **Total Distinct Routes** | ~70 | + +--- + +## Appendix: Service Function Inventory + +### stage-engine.ts +- `evaluateGuardCondition()` - Evaluates a single guard condition +- `evaluateGuard()` - Evaluates guard config with AND/OR logic +- `validateTransition()` - Checks if transition is allowed (PSS exists, transition defined, stage active, window open, guards pass) +- `executeTransition()` - Atomically transitions a project between stages (exits source PSS, creates/updates dest PSS, logs in DecisionAuditLog + AuditLog) +- `executeBatchTransition()` - Batch wrapper around executeTransition (processes 50 at a time) + +### stage-filtering.ts +- `evaluateFieldCondition()` - Evaluates a single field-based rule condition +- `evaluateFieldRule()` - Evaluates field-based rule with AND/OR logic +- `evaluateDocumentCheck()` - Checks if project has required files +- `bandByConfidence()` - AI confidence thresholding (0.75+ = PASSED, 0.25- = FILTERED_OUT, else FLAGGED) +- `runStageFiltering()` - Main orchestration: loads projects, rules, runs deterministic then AI, saves FilteringResults, creates FilteringJob +- `resolveManualDecision()` - Admin resolves a FLAGGED result to PASSED or FILTERED_OUT, logs override +- `getManualQueue()` - Returns all FLAGGED results for a stage + +### stage-assignment.ts +- `calculateTagOverlapScore()` - Counts matching tags between juror and project (max 40 points) +- `calculateWorkloadScore()` - Scores juror based on current load vs preferred (max 25 points) +- `previewStageAssignment()` - Dry run: scores all juror-project pairs, returns top N per project +- `executeStageAssignment()` - Creates Assignment records, logs in AssignmentJob +- `getCoverageReport()` - Returns per-project review counts, per-juror assignment counts +- `rebalance()` - Identifies overloaded/underloaded jurors, suggests reassignments + +### stage-notifications.ts +- `emitStageEvent()` - Core event producer: creates DecisionAuditLog, checks NotificationPolicy, creates InAppNotification, sends email (never throws) +- `resolveRecipients()` - Determines who gets notified based on event type (admins, jury, etc.) +- `buildNotificationMessage()` - Builds human-readable message from event details +- `onStageTransitioned()` - Convenience wrapper for stage.transitioned event +- `onFilteringCompleted()` - Convenience wrapper for filtering.completed event +- `onAssignmentGenerated()` - Convenience wrapper for assignment.generated event +- `onCursorUpdated()` - Convenience wrapper for live.cursor_updated event +- `onDecisionOverridden()` - Convenience wrapper for decision.overridden event + +### live-control.ts +- `generateSessionId()` - Creates unique session ID (timestamp + random) +- `startSession()` - Creates/resets LiveProgressCursor, sets first project active +- `setActiveProject()` - Updates cursor to point to a specific project (validates project is in cohort) +- `jumpToProject()` - Jumps to project by order index +- `reorderQueue()` - Updates CohortProject sortOrder values in batch +- `pauseResume()` - Toggles cursor pause state +- `openCohortWindow()` - Opens voting window for a cohort (sets isOpen=true, windowOpenAt=now) +- `closeCohortWindow()` - Closes voting window for a cohort (sets isOpen=false, windowCloseAt=now) + +--- + +**End of Document** diff --git a/docs/claude-architecture-redesign/02-gap-analysis.md b/docs/claude-architecture-redesign/02-gap-analysis.md new file mode 100644 index 0000000..b4cae08 --- /dev/null +++ b/docs/claude-architecture-redesign/02-gap-analysis.md @@ -0,0 +1,786 @@ +# Gap Analysis: Current System vs. Target 8-Step Competition Flow + +**Document Version:** 1.0 +**Date:** 2026-02-15 +**Author:** Architecture Review (Claude) + +--- + +## Executive Summary + +This gap analysis compares the **current MOPC platform** (pipeline-based, stage-engine architecture) against the **target 8-step competition flow** required for the 2026 Monaco Ocean Protection Challenge. + +**Key Findings:** +- **Foundation is Strong**: Pipeline/Track/Stage architecture, stage-engine transitions, AI filtering, jury assignment, and live voting infrastructure are all in place. +- **Critical Gaps**: Multi-jury support (named jury groups with overlap), multi-round submission windows with read-only enforcement, per-juror capacity constraints (hard cap vs soft cap + buffer), category ratio preferences, countdown timers, and mentoring workspace features are **missing or incomplete**. +- **Integration Gaps**: The current system treats each stage independently; the target flow requires **cross-stage coordination** (e.g., Round 1 docs become read-only in Round 2, jury sees cumulative files). + +--- + +## Table of Contents + +1. [Feature-by-Feature Comparison Table](#1-feature-by-feature-comparison-table) +2. [Per-Step Deep Analysis](#2-per-step-deep-analysis) +3. [Cross-Cutting Gap Analysis](#3-cross-cutting-gap-analysis) +4. [Integration Gaps](#4-integration-gaps) +5. [Priority Matrix](#5-priority-matrix) + +--- + +## 1. Feature-by-Feature Comparison Table + +| Feature | Required by Flow | Current Status | Gap Level | Notes | File References | +|---------|-----------------|----------------|-----------|-------|-----------------| +| **Intake (Submission Round 1)** | +| Public submission form | Applicants upload Round 1 docs, deadline enforcement | ✅ Exists | **None** | `applicantRouter.saveSubmission()` handles create/update, deadline checked via `Stage.windowCloseAt` | `src/server/routers/applicant.ts:126` | +| Configurable deadline behavior | Grace periods, late submission flags | ✅ Exists | **None** | `GracePeriod` model, `isLate` flag on `ProjectFile` | `prisma/schema.prisma:703-728`, `ProjectFile.isLate:606` | +| File requirements per stage | Specify required file types, max size, mime types | ✅ Exists | **None** | `FileRequirement` model linked to stages | `prisma/schema.prisma:569-588` | +| Draft support | Save progress without submitting | ✅ Exists | **None** | `isDraft`, `draftDataJson`, `draftExpiresAt` on `Project` | `prisma/schema.prisma:528-530` | +| **AI Filtering** | +| Automated eligibility screening | Run deterministic + AI rules, band by confidence | ✅ Exists | **None** | `stage-filtering.ts` with banding logic, `FilteringResult` outcome | `src/server/services/stage-filtering.ts:173-191` | +| Admin override capability | Manually resolve flagged projects | ✅ Exists | **None** | `resolveManualDecision()` updates `finalOutcome`, logs override in `OverrideAction` | `src/server/services/stage-filtering.ts:529-611` | +| Duplicate detection | Flag duplicate submissions (same email) | ✅ Exists | **None** | Built-in duplicate check by `submittedByEmail`, always flags (never auto-rejects) | `src/server/services/stage-filtering.ts:267-289` | +| **Jury 1 (Evaluation Round 1)** | +| Semi-finalist selection | Jury evaluates and votes Yes/No | ✅ Exists | **None** | `Evaluation.binaryDecision` field, evaluation submission flow | `src/server/routers/evaluation.ts:130-200` | +| Hard cap per juror | Max N projects per juror (enforced) | ⚠️ **Partial** | **Partial** | `User.maxAssignments` exists but used as global limit, not stage-specific hard cap | `prisma/schema.prisma:249` | +| Soft cap + buffer | Target N, allow up to N+buffer with warning | ❌ **Missing** | **Missing** | No concept of soft cap vs hard cap, no buffer configuration | — | +| Category ratio preferences per juror | Juror wants X% Startup / Y% Concept | ❌ **Missing** | **Missing** | No `User.preferredCategoryRatio` or equivalent | — | +| Explicit Jury 1 group | Named jury entity with members | ❌ **Missing** | **Missing** | All JURY_MEMBER users are global pool, no stage-scoped jury groups | — | +| **Semi-finalist Submission (Submission Round 2)** | +| New doc requirements | Round 2 has different file requirements | ✅ Exists | **None** | Each stage can have its own `FileRequirement` list | `prisma/schema.prisma:569-588` | +| Round 1 docs become read-only | Applicants can't edit/delete Round 1 files | ❌ **Missing** | **Missing** | No `ProjectFile.isReadOnly` or `FileRequirement.allowEdits` field | — | +| Jury sees both rounds | Jury can access Round 1 + Round 2 files | ⚠️ **Partial** | **Partial** | File access checks in `fileRouter.getDownloadUrl()` allow prior stages but complex logic, no explicit "cumulative view" | `src/server/routers/file.ts:66-108` | +| Multi-round submission windows | Distinct open/close dates for Round 1 vs Round 2 | ✅ Exists | **None** | Each stage has `windowOpenAt` / `windowCloseAt` | `prisma/schema.prisma:1888-1889` | +| **Jury 2 (Evaluation Round 2)** | +| Finalist selection | Jury evaluates semifinalists, selects finalists | ✅ Exists | **None** | Same evaluation flow, can configure different form per stage | `prisma/schema.prisma:450-472` | +| Special awards alongside | Run award eligibility + voting in parallel | ✅ Exists | **None** | `SpecialAward` system with `AwardEligibility`, `AwardJuror`, `AwardVote` | `prisma/schema.prisma:1363-1481` | +| Explicit Jury 2 group | Named jury entity, possibly overlapping with Jury 1 | ❌ **Missing** | **Missing** | Same global jury pool issue | — | +| Same cap/ratio features | Per-juror hard cap, soft cap, category ratios | ❌ **Missing** | **Missing** | (Same as Jury 1) | — | +| **Mentoring** | +| Private mentor-team workspace | Chat, file upload, threaded discussions | ⚠️ **Partial** | **Partial** | `MentorMessage` exists but no threading, no file comments, no promotion mechanism | `prisma/schema.prisma:1577-1590` | +| Mentor file upload | Mentor can upload files to project | ❌ **Missing** | **Missing** | No `ProjectFile.uploadedByMentorId` or mentor file upload router endpoint | — | +| Threaded file comments | Comment on specific files with replies | ❌ **Missing** | **Missing** | No `FileComment` model | — | +| File promotion to official submission | Mentor-uploaded file becomes part of official docs | ❌ **Missing** | **Missing** | No promotion workflow or `ProjectFile.promotedFromMentorFileId` | — | +| **Jury 3 Live Finals** | +| Stage manager admin controls | Cursor navigation, pause/resume, queue reorder | ✅ Exists | **None** | `live-control.ts` service with `LiveProgressCursor`, `Cohort` | `src/server/services/live-control.ts:1-619` | +| Jury live voting with notes | Vote during presentation, add notes | ⚠️ **Partial** | **Partial** | `LiveVote` exists but no `notes` field for per-vote commentary | `prisma/schema.prisma:1073-1099` | +| Audience voting | Audience can vote with configurable weight | ✅ Exists | **None** | `AudienceVoter`, `allowAudienceVotes`, `audienceVoteWeight` | `prisma/schema.prisma:1051-1060, 1101-1117` | +| Deliberation period | Time for jury discussion before final vote | ❌ **Missing** | **Missing** | No stage-specific `deliberationDurationMinutes` or deliberation status | — | +| Explicit Jury 3 group | Named jury entity for live finals | ❌ **Missing** | **Missing** | (Same global pool issue) | — | +| **Winner Confirmation** | +| Individual jury member confirmation | Each juror digitally signs off on results | ❌ **Missing** | **Missing** | No `JuryConfirmation` model or per-user signature workflow | — | +| Admin override to force majority | Admin can override and pick winner | ⚠️ **Partial** | **Partial** | `SpecialAward.winnerOverridden` exists, `OverrideAction` logs admin actions, but no explicit "force majority" vs "choose winner" distinction | `prisma/schema.prisma:1388-1389, 2024-2040` | +| Results frozen with audit trail | Immutable record of final decision | ⚠️ **Partial** | **Partial** | `DecisionAuditLog` exists, `OverrideAction` tracks changes, but no `ResultsSnapshot` or explicit freeze mechanism | `prisma/schema.prisma:2042-2057` | +| **Cross-Cutting Features** | +| Multi-jury support (named entities) | Jury 1, Jury 2, Jury 3 with overlapping members | ❌ **Missing** | **Missing** | No `JuryGroup` or `JuryMembership` model | — | +| Countdown timers on dashboards | Show time remaining until deadline | ❌ **Missing** | **Missing** | Backend has `windowCloseAt` but no tRPC endpoint for countdown state | — | +| Email reminders as deadlines approach | Automated reminders at 72h, 24h, 1h | ⚠️ **Partial** | **Partial** | `processEvaluationReminders()` exists for jury, `ReminderLog` tracks sent reminders, but no applicant deadline reminders | `prisma/schema.prisma:1487-1501` | +| Full audit trail for all decisions | Every action logged, immutable | ✅ Exists | **None** | `DecisionAuditLog`, `OverrideAction`, `AuditLog` comprehensive | `prisma/schema.prisma:754-783, 2024-2057` | + +**Legend:** +- ✅ **Exists** = Feature fully implemented +- ⚠️ **Partial** = Feature partially implemented, needs extension +- ❌ **Missing** = Feature does not exist + +--- + +## 2. Per-Step Deep Analysis + +### Step 1: Intake (Submission Round 1) + +**What the Flow Requires:** +- Applicants submit initial docs (executive summary, pitch deck, video) +- Public submission form with deadline enforcement +- Configurable grace periods for late submissions +- Draft support to save progress without submitting +- File type/size validation per requirement + +**What Currently Exists:** +- ✅ **Public submission form**: `applicantRouter.saveSubmission()` creates/updates projects, `isDraft` flag allows partial saves +- ✅ **Deadline enforcement**: `Stage.windowOpenAt` / `windowCloseAt` enforced in `evaluationRouter.submit()` and applicant submission logic +- ✅ **Grace periods**: `GracePeriod` model per stage/user, `extendedUntil` overrides default deadline +- ✅ **File requirements**: `FileRequirement` linked to stages, defines `acceptedMimeTypes`, `maxSizeMB`, `isRequired` +- ✅ **Late submission tracking**: `ProjectFile.isLate` flag set if uploaded after deadline + +**What's Missing:** +- (None — intake is fully functional) + +**What Needs Modification:** +- (None — intake meets requirements) + +**File References:** +- `src/server/routers/applicant.ts:126-200` (saveSubmission) +- `prisma/schema.prisma:569-588` (FileRequirement) +- `prisma/schema.prisma:703-728` (GracePeriod) + +--- + +### Step 2: AI Filtering + +**What the Flow Requires:** +- Automated eligibility screening using deterministic rules (field checks, doc checks) + AI rubric +- Confidence banding: high confidence auto-pass, low confidence auto-reject, medium confidence flagged for manual review +- Admin override capability to resolve flagged projects +- Duplicate submission detection (never auto-reject, always flag) + +**What Currently Exists:** +- ✅ **Filtering service**: `stage-filtering.ts` runs deterministic rules first, then AI screening if deterministic passes +- ✅ **Confidence banding**: `bandByConfidence()` function with thresholds 0.75 (pass) / 0.25 (reject), middle = flagged +- ✅ **Manual queue**: `getManualQueue()` returns flagged projects, `resolveManualDecision()` sets `finalOutcome` +- ✅ **Duplicate detection**: Built-in check by `submittedByEmail`, groups duplicates, always flags (never auto-rejects) +- ✅ **FilteringResult model**: Stores `outcome` (PASSED/FILTERED_OUT/FLAGGED), `ruleResultsJson`, `aiScreeningJson`, `finalOutcome` after override + +**What's Missing:** +- (None — filtering is fully functional) + +**What Needs Modification:** +- (None — filtering meets requirements) + +**File References:** +- `src/server/services/stage-filtering.ts:1-647` (full filtering pipeline) +- `prisma/schema.prisma:1190-1237` (FilteringRule, FilteringResult) + +--- + +### Step 3: Jury 1 (Evaluation Round 1) + +**What the Flow Requires:** +- Semi-finalist selection with hard/soft caps per juror +- Per-juror hard cap (e.g., max 20 projects, enforced) +- Per-juror soft cap + buffer (e.g., target 15, allow up to 18 with warning) +- Per-juror category ratio preferences (e.g., "I want 60% Startup / 40% Concept") +- Explicit Jury 1 group (named entity, distinct from Jury 2/Jury 3) + +**What Currently Exists:** +- ✅ **Evaluation flow**: `evaluationRouter.submit()` accepts `binaryDecision` for yes/no semifinalist vote +- ✅ **Assignment system**: `stage-assignment.ts` generates assignments with workload balancing +- ⚠️ **Per-juror max**: `User.maxAssignments` exists but treated as global limit across all stages, not stage-specific hard cap +- ⚠️ **Workload scoring**: `calculateWorkloadScore()` in `stage-assignment.ts` uses `preferredWorkload` but not distinct soft vs hard cap +- ❌ **Soft cap + buffer**: No configuration for soft cap + buffer (e.g., target 15, allow up to 18) +- ❌ **Category ratio preferences**: No `User.preferredCategoryRatioJson` or similar field +- ❌ **Named jury groups**: All `JURY_MEMBER` users are a global pool, no `JuryGroup` model to create Jury 1, Jury 2, Jury 3 as separate entities + +**What's Missing:** +1. **Soft cap + buffer**: Need `User.targetAssignments` (soft cap) and `User.maxAssignments` (hard cap), with UI warning when juror is in buffer zone +2. **Category ratio preferences**: Need `User.preferredCategoryRatioJson: { STARTUP: 0.6, BUSINESS_CONCEPT: 0.4 }` and assignment scoring that respects ratios +3. **Named jury groups**: Need `JuryGroup` model with `name`, `stageId`, `members[]`, so assignment can be scoped to "Jury 1" vs "Jury 2" + +**What Needs Modification:** +- **Assignment service**: Update `stage-assignment.ts` to: + - Filter jury pool by `JuryGroup.members` for the stage + - Check both soft cap (warning) and hard cap (reject) when assigning + - Score assignments based on `preferredCategoryRatioJson` to balance category distribution per juror +- **Schema**: Add `JuryGroup`, `JuryMembership`, modify `User` to have `targetAssignments` and `preferredCategoryRatioJson` +- **Admin UI**: Jury group management, per-juror cap/ratio configuration + +**File References:** +- `src/server/services/stage-assignment.ts:1-777` (assignment algorithm) +- `src/server/routers/evaluation.ts:130-200` (evaluation submission) +- `prisma/schema.prisma:241-357` (User model) + +--- + +### Step 4: Semi-finalist Submission (Submission Round 2) + +**What the Flow Requires:** +- New doc requirements (e.g., detailed business plan, updated pitch deck) +- Round 1 docs become **read-only** for applicants (no edit/delete) +- Jury sees **both rounds** (cumulative file view) +- Multi-round submission windows (Round 2 opens after Jury 1 closes) + +**What Currently Exists:** +- ✅ **Multi-round file requirements**: Each stage can define its own `FileRequirement` list +- ✅ **Multi-round windows**: `Stage.windowOpenAt` / `windowCloseAt` per stage +- ⚠️ **Jury file access**: `fileRouter.getDownloadUrl()` checks if juror has assignment to project, allows access to files from prior stages in same track (lines 66-108), but logic is implicit and complex +- ❌ **Read-only enforcement**: No `ProjectFile.isReadOnly` or `FileRequirement.allowEdits` field +- ❌ **Cumulative view**: No explicit "show all files from all prior stages" flag on stages + +**What's Missing:** +1. **Read-only flag**: Need `ProjectFile.isReadOnlyForApplicant: Boolean` set when stage transitions, or `FileRequirement.allowEdits: Boolean` to control mutability +2. **Cumulative view**: Need `Stage.showPriorStageFiles: Boolean` or `Stage.cumulativeFileView: Boolean` to make jury file access explicit +3. **File versioning**: Current `replacedById` allows versioning but doesn't enforce read-only from prior rounds + +**What Needs Modification:** +- **Applicant file upload**: Check `isReadOnlyForApplicant` before allowing delete/replace +- **File router**: Simplify jury file access by checking `Stage.cumulativeFileView` instead of complex prior-stage logic +- **Stage transition**: When project moves from Round 1 to Round 2, mark all Round 1 files as `isReadOnlyForApplicant: true` +- **Schema**: Add `ProjectFile.isReadOnlyForApplicant`, `Stage.cumulativeFileView` + +**File References:** +- `src/server/routers/file.ts:12-125` (file download authorization) +- `prisma/schema.prisma:590-624` (ProjectFile) +- `prisma/schema.prisma:1879-1922` (Stage) + +--- + +### Step 5: Jury 2 (Evaluation Round 2) + +**What the Flow Requires:** +- Finalist selection (same evaluation mechanics as Jury 1) +- Special awards eligibility + voting alongside main track +- Explicit Jury 2 group (named entity, may overlap with Jury 1) +- Same per-juror caps and category ratio features as Jury 1 + +**What Currently Exists:** +- ✅ **Evaluation flow**: Identical to Jury 1, `binaryDecision` for finalist vote +- ✅ **Special awards**: Full system with `SpecialAward`, `AwardEligibility`, `AwardJuror`, `AwardVote`, AI eligibility screening +- ✅ **Award tracks**: `Track.kind: AWARD` allows award-specific stages to run in parallel +- ❌ **Named Jury 2 group**: Same global jury pool issue as Jury 1 + +**What's Missing:** +- (Same as Jury 1: named jury groups, soft cap + buffer, category ratio preferences) + +**What Needs Modification:** +- (Same as Jury 1: jury group scoping, cap/ratio logic in assignment service) + +**File References:** +- `src/server/routers/specialAward.ts:1-150` (award management) +- `prisma/schema.prisma:1363-1481` (award models) + +--- + +### Step 6: Mentoring + +**What the Flow Requires:** +- Private mentor-team workspace with: + - Chat/messaging (already exists) + - Mentor file upload (mentor uploads docs for team to review) + - Threaded file comments (comment on specific files with replies) + - File promotion (mentor-uploaded file becomes part of official submission) + +**What Currently Exists:** +- ✅ **Mentor assignment**: `MentorAssignment` model, AI-suggested matching, manual assignment +- ✅ **Mentor messages**: `MentorMessage` model for chat messages between mentor and team +- ❌ **Mentor file upload**: No `ProjectFile.uploadedByMentorId` or mentor file upload endpoint +- ❌ **Threaded file comments**: No `FileComment` model with `parentCommentId` for threading +- ❌ **File promotion**: No workflow to promote mentor-uploaded file to official project submission + +**What's Missing:** +1. **Mentor file upload**: Need `ProjectFile.uploadedByMentorId: String?`, extend `fileRouter.getUploadUrl()` to allow mentors to upload +2. **File comments**: Need `FileComment` model: + ```prisma + model FileComment { + id String @id @default(cuid()) + fileId String + file ProjectFile @relation(...) + authorId String + author User @relation(...) + content String @db.Text + parentCommentId String? + parentComment FileComment? @relation("CommentReplies", ...) + replies FileComment[] @relation("CommentReplies") + createdAt DateTime @default(now()) + } + ``` +3. **File promotion**: Need `ProjectFile.promotedFromMentorFileId: String?` and a promotion workflow (admin/team approves mentor file as official doc) + +**What Needs Modification:** +- **File router**: Add `mentorUploadFile` mutation, authorization check for mentor role +- **Mentor router**: Add `addFileComment`, `promoteFileToOfficial` mutations +- **Schema**: Add `FileComment`, modify `ProjectFile` to link mentor uploads and promotions + +**File References:** +- `src/server/routers/mentor.ts:1-200` (mentor operations) +- `prisma/schema.prisma:1145-1172` (MentorAssignment) +- `prisma/schema.prisma:1577-1590` (MentorMessage) + +--- + +### Step 7: Jury 3 Live Finals + +**What the Flow Requires:** +- Stage manager admin controls (cursor navigation, pause/resume, queue reorder) — **ALREADY EXISTS** +- Jury live voting with notes (vote + add commentary per vote) +- Audience voting — **ALREADY EXISTS** +- Deliberation period (pause for jury discussion before final vote) +- Explicit Jury 3 group (named entity for live finals) + +**What Currently Exists:** +- ✅ **Live control service**: `live-control.ts` with `LiveProgressCursor`, session management, cursor navigation, queue reordering +- ✅ **Live voting**: `LiveVote` model, jury/audience voting, criteria-based scoring +- ✅ **Cohort management**: `Cohort` groups projects for voting windows +- ⚠️ **Vote notes**: `LiveVote` has no `notes` or `commentary` field for per-vote notes +- ❌ **Deliberation period**: No `Cohort.deliberationDurationMinutes` or deliberation status +- ❌ **Named Jury 3 group**: Same global jury pool issue + +**What's Missing:** +1. **Vote notes**: Add `LiveVote.notes: String?` for jury commentary during voting +2. **Deliberation period**: Add `Cohort.deliberationDurationMinutes: Int?`, `Cohort.deliberationStartedAt: DateTime?`, `Cohort.deliberationEndedAt: DateTime?` +3. **Named Jury 3 group**: (Same as Jury 1/Jury 2) + +**What Needs Modification:** +- **LiveVote model**: Add `notes` field +- **Cohort model**: Add deliberation fields +- **Live voting router**: Add `startDeliberation()`, `endDeliberation()` procedures +- **Live control service**: Add deliberation status checks to prevent voting during deliberation + +**File References:** +- `src/server/services/live-control.ts:1-619` (live session management) +- `src/server/routers/live-voting.ts:1-150` (live voting procedures) +- `prisma/schema.prisma:1035-1071, 1969-2006` (LiveVotingSession, Cohort) + +--- + +### Step 8: Winner Confirmation + +**What the Flow Requires:** +- Individual jury member confirmation (each juror digitally signs off on results) +- Admin override to force majority or choose winner +- Results frozen with immutable audit trail + +**What Currently Exists:** +- ⚠️ **Admin override**: `SpecialAward.winnerOverridden` flag, `OverrideAction` logs admin actions, but no explicit "force majority" vs "choose winner" distinction +- ⚠️ **Audit trail**: `DecisionAuditLog`, `OverrideAction` comprehensive, but no explicit `ResultsSnapshot` or freeze mechanism +- ❌ **Individual jury confirmation**: No `JuryConfirmation` model for per-user digital signatures + +**What's Missing:** +1. **Jury confirmation**: Need `JuryConfirmation` model: + ```prisma + model JuryConfirmation { + id String @id @default(cuid()) + stageId String + stage Stage @relation(...) + userId String + user User @relation(...) + confirmedAt DateTime @default(now()) + signature String // Digital signature or consent hash + ipAddress String? + userAgent String? + } + ``` +2. **Results freeze**: Need `Stage.resultsFrozenAt: DateTime?` to mark results as immutable +3. **Override modes**: Add `OverrideAction.overrideMode: Enum(FORCE_MAJORITY, CHOOSE_WINNER)` for clarity + +**What Needs Modification:** +- **Live voting router**: Add `confirmResults()` procedure for jury members to sign off +- **Admin router**: Add `freezeResults()` procedure, check `resultsFrozenAt` before allowing further changes +- **Override service**: Update `OverrideAction` creation to include `overrideMode` + +**File References:** +- `prisma/schema.prisma:1363-1418` (SpecialAward with winner override) +- `prisma/schema.prisma:2024-2040` (OverrideAction) +- `prisma/schema.prisma:2042-2057` (DecisionAuditLog) + +--- + +## 3. Cross-Cutting Gap Analysis + +### Multi-Jury Support (Named Jury Entities with Overlap) + +**Requirement:** +- Create named jury groups (Jury 1, Jury 2, Jury 3) with explicit membership lists +- Allow jurors to be members of multiple groups (e.g., Juror A is in Jury 1 and Jury 3 but not Jury 2) +- Scope assignments, evaluations, and live voting to specific jury groups + +**Current State:** +- All users with `role: JURY_MEMBER` are treated as a global pool +- No scoping of jury to specific stages or rounds +- `stage-assignment.ts` queries all active jury members without filtering by group + +**Gap:** +- ❌ No `JuryGroup` model +- ❌ No `JuryMembership` model to link users to groups +- ❌ No stage-level configuration to specify which jury group evaluates that stage + +**Required Schema Changes:** +```prisma +model JuryGroup { + id String @id @default(cuid()) + programId String + program Program @relation(...) + name String // "Jury 1", "Jury 2", "Jury 3" + description String? + createdAt DateTime @default(now()) + + memberships JuryMembership[] + stages Stage[] // One-to-many: stages can specify which jury group evaluates them +} + +model JuryMembership { + id String @id @default(cuid()) + juryGroupId String + juryGroup JuryGroup @relation(...) + userId String + user User @relation(...) + joinedAt DateTime @default(now()) + + @@unique([juryGroupId, userId]) +} + +// Extend Stage model: +model Stage { + // ... existing fields + juryGroupId String? + juryGroup JuryGroup? @relation(...) +} +``` + +**Impact:** +- **High** — Affects assignment generation, evaluation authorization, live voting eligibility +- **Requires**: New admin UI for jury group management, updates to all jury-related queries/mutations + +--- + +### Multi-Round Submission Windows + +**Requirement:** +- Distinct submission windows for Round 1 (Intake), Round 2 (Semi-finalist submission) +- Round 1 files become read-only after Round 1 closes +- Jury sees cumulative files from all prior rounds + +**Current State:** +- ✅ Each stage has `windowOpenAt` / `windowCloseAt` (multi-round windows exist) +- ⚠️ File access is complex and implicit (checks prior stages in track but no clear flag) +- ❌ No read-only enforcement for applicants after stage transition + +**Gap:** +- ❌ No `ProjectFile.isReadOnlyForApplicant` field +- ❌ No `Stage.cumulativeFileView` flag for jury access +- ❌ No automated mechanism to mark files as read-only on stage transition + +**Required Schema Changes:** +```prisma +model ProjectFile { + // ... existing fields + isReadOnlyForApplicant Boolean @default(false) +} + +model Stage { + // ... existing fields + cumulativeFileView Boolean @default(false) // If true, jury sees files from all prior stages in track +} +``` + +**Impact:** +- **Medium** — Affects file upload/delete authorization, jury file listing queries +- **Requires**: Stage transition hook to mark files as read-only, applicant file UI updates, jury file view updates + +--- + +### Per-Juror Hard Cap vs Soft Cap + Buffer + +**Requirement:** +- **Hard cap**: Max N projects (e.g., 20), enforced, cannot exceed +- **Soft cap**: Target N projects (e.g., 15), preferred, can exceed with warning +- **Buffer**: Soft cap to hard cap range (e.g., 15-18), shows warning in UI + +**Current State:** +- ⚠️ `User.maxAssignments` exists but treated as global hard cap +- ⚠️ `User.preferredWorkload` used in assignment scoring but not enforced as soft cap +- ❌ No buffer concept, no UI warning when juror is over target + +**Gap:** +- ❌ No distinction between soft cap and hard cap +- ❌ No buffer configuration or warning mechanism + +**Required Schema Changes:** +```prisma +model User { + // ... existing fields + targetAssignments Int? // Soft cap (preferred target) + maxAssignments Int? // Hard cap (absolute max, enforced) + // preferredWorkload is deprecated in favor of targetAssignments +} +``` + +**Assignment Logic Changes:** +- Update `stage-assignment.ts`: + - Filter candidates to exclude jurors at `maxAssignments` + - Score jurors higher if below `targetAssignments`, lower if between `targetAssignments` and `maxAssignments` (buffer zone) + - UI shows warning icon for jurors in buffer zone (target < current < max) + +**Impact:** +- **Medium** — Affects assignment generation and admin UI for jury workload +- **Requires**: Update assignment service, admin assignment UI to show soft/hard cap status + +--- + +### Per-Juror Category Ratio Preferences + +**Requirement:** +- Juror specifies preferred category distribution (e.g., "I want 60% Startup / 40% Business Concept") +- Assignment algorithm respects these preferences when assigning projects + +**Current State:** +- ❌ No category ratio configuration per juror +- ⚠️ Assignment scoring uses tag overlap and workload but not category distribution + +**Gap:** +- ❌ No `User.preferredCategoryRatioJson` field +- ❌ Assignment algorithm doesn't score based on category distribution + +**Required Schema Changes:** +```prisma +model User { + // ... existing fields + preferredCategoryRatioJson Json? @db.JsonB // { "STARTUP": 0.6, "BUSINESS_CONCEPT": 0.4 } +} +``` + +**Assignment Logic Changes:** +- Update `stage-assignment.ts`: + - For each juror, calculate current category distribution of assigned projects + - Score candidates higher if assigning this project would bring juror's distribution closer to `preferredCategoryRatioJson` + - Example: Juror wants 60/40 Startup/Concept, currently has 70/30, algorithm prefers assigning Concept projects to rebalance + +**Impact:** +- **Medium** — Affects assignment generation quality, requires juror onboarding to set preferences +- **Requires**: Update assignment algorithm, admin UI for juror profile editing, onboarding flow + +--- + +### Countdown Timers on Dashboards + +**Requirement:** +- Applicant dashboard shows countdown to submission deadline +- Jury dashboard shows countdown to evaluation deadline +- Admin dashboard shows countdown to stage window close + +**Current State:** +- ✅ Backend has `Stage.windowCloseAt` timestamp +- ❌ No tRPC endpoint to fetch countdown state (time remaining, status: open/closing soon/closed) +- ❌ Frontend has no countdown component + +**Gap:** +- ❌ No `stageRouter.getCountdown()` or similar procedure +- ❌ No frontend countdown component + +**Required Changes:** +- Add tRPC procedure: + ```typescript + stageRouter.getCountdown: protectedProcedure + .input(z.object({ stageId: z.string() })) + .query(async ({ ctx, input }) => { + const stage = await ctx.prisma.stage.findUniqueOrThrow({ where: { id: input.stageId } }) + const now = new Date() + const closeAt = stage.windowCloseAt + if (!closeAt) return { status: 'no_deadline', timeRemaining: null } + const remaining = closeAt.getTime() - now.getTime() + if (remaining <= 0) return { status: 'closed', timeRemaining: 0 } + return { + status: remaining < 3600000 ? 'closing_soon' : 'open', // < 1 hour = closing soon + timeRemaining: remaining, + closeAt, + } + }) + ``` +- Frontend: Countdown component that polls `getCountdown()` and displays "X days Y hours Z minutes remaining" + +**Impact:** +- **Low** — UX improvement, no data model changes +- **Requires**: New tRPC procedure, frontend countdown component, dashboard integration + +--- + +### Email Reminders as Deadlines Approach + +**Requirement:** +- Automated email reminders at 72 hours, 24 hours, 1 hour before deadline +- For applicants (submission deadlines) and jury (evaluation deadlines) + +**Current State:** +- ⚠️ `processEvaluationReminders()` exists for jury reminders +- ⚠️ `ReminderLog` tracks sent reminders to prevent duplicates +- ❌ No applicant deadline reminder cron job +- ❌ No configurable reminder intervals (hardcoded to 3 days, 24h, 1h in evaluation reminders) + +**Gap:** +- ❌ No applicant reminder service +- ❌ No configurable reminder intervals per stage + +**Required Changes:** +- Add `Stage.reminderIntervalsJson: Json?` // `[72, 24, 1]` (hours before deadline) +- Add `src/server/services/applicant-reminders.ts`: + ```typescript + export async function processApplicantReminders(prisma: PrismaClient) { + const now = new Date() + const stages = await prisma.stage.findMany({ + where: { status: 'STAGE_ACTIVE', windowCloseAt: { gte: now } }, + }) + for (const stage of stages) { + const intervals = (stage.reminderIntervalsJson as number[]) ?? [72, 24, 1] + for (const hoursBeforeDeadline of intervals) { + const reminderTime = new Date(stage.windowCloseAt!.getTime() - hoursBeforeDeadline * 3600000) + if (now >= reminderTime && now < new Date(reminderTime.getTime() + 3600000)) { + // Send reminders to all applicants with draft projects in this stage + // Check ReminderLog to avoid duplicates + } + } + } + } + ``` +- Add cron job in `src/app/api/cron/applicant-reminders/route.ts` + +**Impact:** +- **Medium** — Improves applicant engagement, reduces late submissions +- **Requires**: New service, new cron endpoint, extend `ReminderLog` model if needed + +--- + +### Admin Override Capability at Every Step + +**Requirement:** +- Admin can override any automated decision (filtering, assignment, voting results) +- Override is logged with reason code and reason text in `OverrideAction` + +**Current State:** +- ✅ Filtering: `resolveManualDecision()` overrides flagged projects +- ✅ Assignment: Manual assignment creation bypasses AI +- ⚠️ Live voting: `SpecialAward.winnerOverridden` flag exists but no explicit override flow for live voting results +- ⚠️ Stage transitions: No override capability to force projects between stages + +**Gap:** +- ❌ No admin UI to override stage transitions (force project to next stage even if guard fails) +- ❌ No admin override for live voting results (admin can pick winner but not documented as override) + +**Required Changes:** +- Add `stageRouter.overrideTransition()` procedure: + ```typescript + overrideTransition: adminProcedure + .input(z.object({ + projectId: z.string(), + fromStageId: z.string(), + toStageId: z.string(), + reasonCode: z.nativeEnum(OverrideReasonCode), + reasonText: z.string(), + })) + .mutation(async ({ ctx, input }) => { + // Force executeTransition() without validation + // Log in OverrideAction + }) + ``` +- Add `liveVotingRouter.overrideWinner()` procedure (similar flow) + +**Impact:** +- **Low** — Fills gaps in admin control, already mostly exists +- **Requires**: New admin procedures, UI buttons for override actions + +--- + +## 4. Integration Gaps + +### Cross-Stage File Visibility + +**Issue:** +- Current file access is stage-scoped. Jury assigned to Round 2 can technically access Round 1 files (via complex `fileRouter.getDownloadUrl()` logic checking prior stages), but this is implicit and fragile. +- No clear flag to say "Round 2 jury should see Round 1 + Round 2 files" vs "Round 2 jury should only see Round 2 files". + +**Required:** +- Add `Stage.cumulativeFileView: Boolean` — if true, jury sees files from all prior stages in the track. +- Simplify `fileRouter.getDownloadUrl()` authorization logic to check this flag instead of manual prior-stage traversal. + +**Impact:** +- **Medium** — Simplifies file access logic, makes jury file view behavior explicit. + +--- + +### Round 1 to Round 2 Transition (File Read-Only Enforcement) + +**Issue:** +- When a project transitions from Round 1 (Intake) to Round 2 (Semi-finalist submission), Round 1 files should become read-only for applicants. +- Currently, no mechanism enforces this. Applicants could theoretically delete/replace Round 1 files during Round 2. + +**Required:** +- Stage transition hook in `stage-engine.ts` `executeTransition()`: + ```typescript + // After creating destination PSS: + if (fromStage.stageType === 'INTAKE' && toStage.stageType === 'INTAKE') { + // Mark all project files uploaded in fromStage as read-only for applicant + await tx.projectFile.updateMany({ + where: { projectId, roundId: fromStageRoundId }, + data: { isReadOnlyForApplicant: true }, + }) + } + ``` +- Applicant file upload/delete checks: Reject if `ProjectFile.isReadOnlyForApplicant: true`. + +**Impact:** +- **High** — Ensures data integrity, prevents applicants from tampering with prior round submissions. + +--- + +### Jury Group Scoping Across All Jury-Related Operations + +**Issue:** +- Assignments, evaluations, live voting all currently use global jury pool. +- Once `JuryGroup` is introduced, must update every jury-related query/mutation to filter by `Stage.juryGroupId`. + +**Affected Areas:** +1. **Assignment generation**: `stage-assignment.ts` `previewStageAssignment()` must filter `prisma.user.findMany({ where: { role: 'JURY_MEMBER', ... } })` to `prisma.juryMembership.findMany({ where: { juryGroupId: stage.juryGroupId } })`. +2. **Evaluation authorization**: `evaluationRouter.submit()` must verify `assignment.userId` is a member of `stage.juryGroupId`. +3. **Live voting authorization**: `liveVotingRouter.submitVote()` must verify juror is in `stage.juryGroupId`. +4. **Admin assignment UI**: Dropdown to select jurors must filter by jury group. + +**Impact:** +- **High** — Pervasive change across all jury-related features. +- **Requires**: Careful migration plan, extensive testing. + +--- + +### Countdown Timer Backend Support + +**Issue:** +- Dashboards need real-time countdown to deadlines, but no backend service provides this. +- Frontend would need to poll `Stage.windowCloseAt` directly and calculate client-side, or use a tRPC subscription. + +**Required:** +- Add `stageRouter.getCountdown()` procedure (described in Cross-Cutting section). +- Frontend uses `trpc.stage.getCountdown.useQuery()` with `refetchInterval: 60000` (1 minute polling). +- Optionally: WebSocket subscription for real-time updates (out of scope for now, polling is sufficient). + +**Impact:** +- **Low** — Backend is simple, frontend polling handles real-time updates. + +--- + +## 5. Priority Matrix + +Features ranked by **Business Impact** (High/Medium/Low) x **Implementation Effort** (High/Medium/Low). + +| Feature | Business Impact | Implementation Effort | Priority Quadrant | Notes | +|---------|----------------|----------------------|-------------------|-------| +| **Multi-jury support (named groups)** | **High** | **High** | **Critical** | Required for all 3 jury rounds, affects assignments/evaluations/voting | +| **Round 1 docs read-only enforcement** | **High** | **Low** | **Quick Win** | Data integrity essential, simple flag + hook | +| **Per-juror hard cap vs soft cap + buffer** | **High** | **Medium** | **Critical** | Ensures balanced workload, prevents burnout | +| **Per-juror category ratio preferences** | **Medium** | **Medium** | **Important** | Improves assignment quality, enhances juror satisfaction | +| **Jury vote notes (live finals)** | **Medium** | **Low** | **Quick Win** | Enhances deliberation, simple schema change | +| **Deliberation period (live finals)** | **Medium** | **Low** | **Quick Win** | Required for live finals flow, simple cohort fields | +| **Individual jury confirmation** | **High** | **Medium** | **Critical** | Legal/compliance requirement for final results | +| **Results freeze mechanism** | **High** | **Low** | **Quick Win** | Immutable audit trail, simple timestamp flag | +| **Cumulative file view flag** | **Medium** | **Low** | **Quick Win** | Simplifies jury file access logic | +| **Mentor file upload** | **Medium** | **Medium** | **Important** | Enhances mentoring, requires file router extension | +| **Threaded file comments** | **Low** | **Medium** | **Nice to Have** | Improves collaboration, but not blocking | +| **File promotion workflow** | **Low** | **Medium** | **Nice to Have** | Advanced feature, can defer to later phase | +| **Countdown timers (UI)** | **Low** | **Low** | **Nice to Have** | UX improvement, no data model changes | +| **Applicant deadline reminders** | **Medium** | **Low** | **Quick Win** | Reduces late submissions, simple cron job | +| **Admin override for stage transitions** | **Low** | **Low** | **Nice to Have** | Edge case, manual workaround exists | + +**Priority Quadrants:** +- **Critical (High Impact / High Effort)**: Multi-jury support, jury confirmation — **must do**, high planning required +- **Quick Wins (High Impact / Low Effort)**: Read-only enforcement, results freeze, deliberation period — **do first** +- **Important (Medium Impact / Medium Effort)**: Caps/ratios, mentor file upload — **do after quick wins** +- **Nice to Have (Low Impact / Any Effort)**: File comments threading, countdown timers — **defer or phase 2** + +--- + +## Conclusion + +The current MOPC platform has a **solid foundation** with the pipeline/track/stage architecture, stage-engine transitions, AI filtering, jury assignment, and live voting infrastructure fully implemented. The **critical gaps** are: + +1. **Multi-jury support** (named jury entities with overlap) — **highest priority**, affects all jury-related features +2. **Per-juror caps and category ratio preferences** — **essential for workload balancing** +3. **Round 1 read-only enforcement + cumulative file view** — **data integrity and jury UX** +4. **Individual jury confirmation + results freeze** — **compliance and audit requirements** +5. **Mentoring workspace features** (file upload, comments, promotion) — **enhances mentoring but lower priority** + +**Recommended Approach:** +- **Phase 1 (Quick Wins)**: Read-only enforcement, results freeze, deliberation period, vote notes, applicant reminders — **2-3 weeks** +- **Phase 2 (Critical)**: Multi-jury support, jury confirmation — **4-6 weeks** (complex, pervasive changes) +- **Phase 3 (Important)**: Caps/ratios, mentor file upload — **3-4 weeks** +- **Phase 4 (Nice to Have)**: Threaded comments, file promotion, countdown timers — **defer to post-MVP** + +Total estimated effort for Phases 1-3: **9-13 weeks** (assumes single developer, includes testing). + +--- + +**End of Gap Analysis Document** diff --git a/docs/claude-architecture-redesign/03-data-model.md b/docs/claude-architecture-redesign/03-data-model.md new file mode 100644 index 0000000..e6743b4 --- /dev/null +++ b/docs/claude-architecture-redesign/03-data-model.md @@ -0,0 +1,1139 @@ +# Data Model Redesign + +## Overview + +This document defines the complete Prisma schema for the MOPC architecture redesign. It covers new models, modified models, eliminated models, and the migration path from the current schema. + +### Naming Convention Changes + +| Current | Redesigned | Rationale | +|---------|-----------|-----------| +| `Pipeline` | `Competition` | Domain-specific — admins think "Competition 2026" | +| `Track` | *(eliminated)* | Main flow is linear; awards are standalone | +| `Stage` | `Round` | Domain-specific — "Round 3: Jury 1 Evaluation" | +| `StageType` | `RoundType` | Follows rename | +| `StageStatus` | `RoundStatus` | Follows rename | +| `ProjectStageState` | `ProjectRoundState` | Follows rename, drops trackId | +| `StageTransition` | *(eliminated)* | Replaced by linear sortOrder + advancement rules | + +--- + +## 1. Eliminated Models & Enums + +### Models Removed + +``` +Track -- Main flow is linear; awards are standalone SpecialAward entities +StageTransition -- Replaced by linear round ordering + AdvancementRule +CohortProject -- Merged into round-level project ordering +TrackKind (enum) -- No tracks +RoutingMode (enum) -- No tracks +DecisionMode (enum) -- Moved to SpecialAward.decisionMode as a string field +``` + +### Why Track Is Eliminated + +The `Track` model served two purposes: +1. **Main competition flow** — But this is always linear (Intake -> Filter -> Eval -> ... -> Finals) +2. **Award branches** — But awards don't need their own stage pipeline; they need eligibility + voting + +Without Track: +- `Round` belongs directly to `Competition` (no intermediate layer) +- `SpecialAward` is self-contained (has its own jury, voting, and result) +- `ProjectRoundState` drops `trackId` (project is in a round, period) +- Admin UI shows a flat list of rounds instead of nested Track > Stage + +--- + +## 2. Core Competition Structure + +### Competition (replaces Pipeline) + +```prisma +model Competition { + id String @id @default(cuid()) + programId String + name String // "MOPC 2026 Competition" + slug String @unique // "mopc-2026" + status CompetitionStatus @default(DRAFT) + + // Competition-wide settings (typed, not generic JSON) + categoryMode String @default("SHARED") // "SHARED" (both categories same flow) | "SPLIT" (separate finalist counts) + startupFinalistCount Int @default(3) + conceptFinalistCount Int @default(3) + + // Notification preferences + notifyOnRoundAdvance Boolean @default(true) + notifyOnDeadlineApproach Boolean @default(true) + deadlineReminderDays Int[] @default([7, 3, 1]) // Days before deadline to send reminders + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + program Program @relation(fields: [programId], references: [id], onDelete: Cascade) + rounds Round[] + juryGroups JuryGroup[] + submissionWindows SubmissionWindow[] + specialAwards SpecialAward[] + winnerProposals WinnerProposal[] + + @@index([programId]) + @@index([status]) +} + +enum CompetitionStatus { + DRAFT + ACTIVE + CLOSED + ARCHIVED +} +``` + +### Round (replaces Stage) + +```prisma +model Round { + id String @id @default(cuid()) + competitionId String + name String // "Jury 1 - Semi-finalist Selection" + slug String // "jury-1-semifinalist" + roundType RoundType + status RoundStatus @default(ROUND_DRAFT) + sortOrder Int @default(0) + + // Time windows + windowOpenAt DateTime? + windowCloseAt DateTime? + + // Round-type-specific configuration (validated by Zod per RoundType) + configJson Json? @db.JsonB + + // Links to other entities + juryGroupId String? // Which jury evaluates this round (EVALUATION, LIVE_FINAL) + submissionWindowId String? // Which submission window this round collects docs for (INTAKE, SUBMISSION) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + juryGroup JuryGroup? @relation(fields: [juryGroupId], references: [id], onDelete: SetNull) + submissionWindow SubmissionWindow? @relation(fields: [submissionWindowId], references: [id], onDelete: SetNull) + + projectRoundStates ProjectRoundState[] + assignments Assignment[] + evaluationForms EvaluationForm[] + filteringRules FilteringRule[] + filteringResults FilteringResult[] + filteringJobs FilteringJob[] + evaluationSummaries EvaluationSummary[] + evaluationDiscussions EvaluationDiscussion[] + gracePeriods GracePeriod[] + liveCursor LiveProgressCursor? + liveVotingSession LiveVotingSession? + cohorts Cohort[] + advancementRules AdvancementRule[] + + // Visible submission windows (which doc rounds jury can see) + visibleSubmissionWindows RoundSubmissionVisibility[] + + @@unique([competitionId, slug]) + @@unique([competitionId, sortOrder]) + @@index([competitionId]) + @@index([roundType]) + @@index([status]) +} + +enum RoundType { + INTAKE // Application window — collect initial submissions + FILTERING // AI screening — automated eligibility check + EVALUATION // Jury evaluation — scoring, feedback, advancement decision + SUBMISSION // New submission window — additional docs from advancing teams + MENTORING // Mentor-team collaboration period + LIVE_FINAL // Live ceremony — real-time voting, audience participation + CONFIRMATION // Winner agreement — jury signatures + admin confirmation +} + +enum RoundStatus { + ROUND_DRAFT // Being configured, not visible to participants + ROUND_ACTIVE // Open/in progress + ROUND_CLOSED // Window closed, results pending or finalized + ROUND_ARCHIVED // Historical, read-only +} +``` + +### ProjectRoundState (replaces ProjectStageState) + +```prisma +model ProjectRoundState { + id String @id @default(cuid()) + projectId String + roundId String + state ProjectRoundStateValue @default(PENDING) + enteredAt DateTime @default(now()) + exitedAt DateTime? + metadataJson Json? @db.JsonB // Round-type-specific state data + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + round Round @relation(fields: [roundId], references: [id], onDelete: Cascade) + + @@unique([projectId, roundId]) + @@index([projectId]) + @@index([roundId]) + @@index([state]) +} + +enum ProjectRoundStateValue { + PENDING // Entered round, awaiting action + IN_PROGRESS // Active (submission in progress, evaluation ongoing) + PASSED // Cleared this round, eligible to advance + REJECTED // Did not pass this round + COMPLETED // Round fully complete for this project + WITHDRAWN // Project withdrew +} +``` + +### AdvancementRule (replaces StageTransition + guardJson) + +```prisma +model AdvancementRule { + id String @id @default(cuid()) + roundId String // The round this rule applies to (source round) + targetRoundId String? // Where projects advance to (null = next round by sortOrder) + + ruleType AdvancementRuleType + configJson Json @db.JsonB // Rule-type-specific config + + isDefault Boolean @default(true) // Default advancement path + sortOrder Int @default(0) // Priority when multiple rules exist + + createdAt DateTime @default(now()) + + round Round @relation(fields: [roundId], references: [id], onDelete: Cascade) + + @@index([roundId]) +} + +enum AdvancementRuleType { + AUTO_ADVANCE // All PASSED projects advance to next round automatically + SCORE_THRESHOLD // Projects above score threshold advance + TOP_N // Top N projects per category advance + ADMIN_SELECTION // Admin manually selects who advances + AI_RECOMMENDED // AI suggests advancement, admin confirms +} +``` + +**AdvancementRule configJson shapes:** + +```typescript +// AUTO_ADVANCE +{ trigger: "on_round_close" | "immediate" } + +// SCORE_THRESHOLD +{ minScore: 7.0, metric: "average_global" | "weighted_criteria" } + +// TOP_N +{ + perCategory: true, + counts: { STARTUP: 10, BUSINESS_CONCEPT: 10 }, + tieBreaker: "admin_decides" | "highest_individual" | "revote" +} + +// ADMIN_SELECTION +{ requireAIRecommendation: true, showRankings: true } + +// AI_RECOMMENDED +{ topN: 10, confidenceThreshold: 0.7, requireAdminApproval: true } +``` + +--- + +## 3. Jury System + +### JuryGroup + +```prisma +model JuryGroup { + id String @id @default(cuid()) + competitionId String + name String // "Jury 1", "Jury 2", "Jury 3", "Innovation Award Jury" + slug String // "jury-1", "jury-2" + description String? @db.Text + sortOrder Int @default(0) + + // Default assignment configuration for this jury + defaultMaxAssignments Int @default(20) + defaultCapMode CapMode @default(SOFT) + softCapBuffer Int @default(2) // Extra assignments above cap for load balancing + + // Default category quotas (per juror) + categoryQuotasEnabled Boolean @default(false) + defaultCategoryQuotas Json? @db.JsonB // { "STARTUP": { "min": 2, "max": 15 }, "BUSINESS_CONCEPT": { "min": 2, "max": 15 } } + + // Onboarding: can jurors adjust their own cap/ratio during onboarding? + allowJurorCapAdjustment Boolean @default(false) + allowJurorRatioAdjustment Boolean @default(false) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + members JuryGroupMember[] + rounds Round[] // Rounds this jury is assigned to + assignments Assignment[] // Assignments made through this jury group + + @@unique([competitionId, slug]) + @@index([competitionId]) +} + +enum CapMode { + HARD // Absolute maximum — AI/algorithm cannot exceed + SOFT // Target maximum — can exceed by softCapBuffer for load balancing + NONE // No cap — unlimited assignments +} +``` + +### JuryGroupMember + +```prisma +model JuryGroupMember { + id String @id @default(cuid()) + juryGroupId String + userId String + isLead Boolean @default(false) + joinedAt DateTime @default(now()) + + // Per-juror overrides (null = use group defaults) + maxAssignmentsOverride Int? + capModeOverride CapMode? + categoryQuotasOverride Json? @db.JsonB // Same shape as JuryGroup.defaultCategoryQuotas + + // Juror preferences (set during onboarding) + preferredStartupRatio Float? // 0.0 to 1.0 — desired % of startups (e.g., 0.6 = 60% startups) + availabilityNotes String? @db.Text + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + juryGroup JuryGroup @relation(fields: [juryGroupId], references: [id], onDelete: Cascade) + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + + @@unique([juryGroupId, userId]) + @@index([juryGroupId]) + @@index([userId]) +} +``` + +--- + +## 4. Multi-Round Submission System + +### SubmissionWindow + +```prisma +model SubmissionWindow { + id String @id @default(cuid()) + competitionId String + name String // "Round 1 Application Docs", "Semi-finalist Additional Docs" + slug String // "round-1-docs" + roundNumber Int // 1, 2, 3... (sequential) + sortOrder Int @default(0) + + // Window timing + windowOpenAt DateTime? + windowCloseAt DateTime? + + // Deadline behavior + deadlinePolicy DeadlinePolicy @default(FLAG) + graceHours Int? // Hours after windowCloseAt where late submissions accepted + + // Locking behavior + lockOnClose Boolean @default(true) // Applicants can't edit after window closes + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + fileRequirements SubmissionFileRequirement[] + projectFiles ProjectFile[] + rounds Round[] // Rounds that collect submissions for this window + visibility RoundSubmissionVisibility[] // Which evaluation rounds can see these docs + + @@unique([competitionId, slug]) + @@unique([competitionId, roundNumber]) + @@index([competitionId]) +} + +enum DeadlinePolicy { + HARD // Submissions rejected after close + FLAG // Submissions accepted but marked late + GRACE // Grace period after close, then hard cutoff +} +``` + +### SubmissionFileRequirement + +```prisma +model SubmissionFileRequirement { + id String @id @default(cuid()) + submissionWindowId String + name String // "Executive Summary", "Business Plan", "Video Pitch" + description String? @db.Text + acceptedMimeTypes String[] // ["application/pdf", "video/*"] + maxSizeMB Int? // Size limit + isRequired Boolean @default(true) + sortOrder Int @default(0) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + submissionWindow SubmissionWindow @relation(fields: [submissionWindowId], references: [id], onDelete: Cascade) + files ProjectFile[] // Files uploaded against this requirement + + @@index([submissionWindowId]) +} +``` + +### RoundSubmissionVisibility + +Controls which submission windows a jury evaluation round can see. + +```prisma +model RoundSubmissionVisibility { + id String @id @default(cuid()) + roundId String + submissionWindowId String + + canView Boolean @default(true) // Jury can see these docs + displayLabel String? // "Round 1 Docs", "Round 2 Docs" (shown to jury) + + // Relations + round Round @relation(fields: [roundId], references: [id], onDelete: Cascade) + submissionWindow SubmissionWindow @relation(fields: [submissionWindowId], references: [id], onDelete: Cascade) + + @@unique([roundId, submissionWindowId]) + @@index([roundId]) +} +``` + +**Example usage:** + +Jury 1 (Round 3) sees only Round 1 docs: +``` +RoundSubmissionVisibility { roundId: round-3, submissionWindowId: sw-1, canView: true, displayLabel: "Application Docs" } +``` + +Jury 2 (Round 5) sees Round 1 AND Round 2 docs: +``` +RoundSubmissionVisibility { roundId: round-5, submissionWindowId: sw-1, canView: true, displayLabel: "Round 1 Docs" } +RoundSubmissionVisibility { roundId: round-5, submissionWindowId: sw-2, canView: true, displayLabel: "Round 2 Docs" } +``` + +--- + +## 5. Mentoring Workspace + +### MentorFile + +```prisma +model MentorFile { + id String @id @default(cuid()) + mentorAssignmentId String + uploadedByUserId String + + fileName String + mimeType String + size Int + bucket String + objectKey String + description String? @db.Text + + // Promotion to official submission + isPromoted Boolean @default(false) + promotedToFileId String? @unique // Links to the ProjectFile created on promotion + promotedAt DateTime? + promotedByUserId String? + + createdAt DateTime @default(now()) + + // Relations + mentorAssignment MentorAssignment @relation(fields: [mentorAssignmentId], references: [id], onDelete: Cascade) + uploadedBy User @relation("MentorFileUploader", fields: [uploadedByUserId], references: [id]) + promotedBy User? @relation("MentorFilePromoter", fields: [promotedByUserId], references: [id]) + promotedFile ProjectFile? @relation("PromotedFromMentorFile", fields: [promotedToFileId], references: [id], onDelete: SetNull) + comments MentorFileComment[] + + @@index([mentorAssignmentId]) + @@index([uploadedByUserId]) +} +``` + +### MentorFileComment + +```prisma +model MentorFileComment { + id String @id @default(cuid()) + mentorFileId String + authorId String + content String @db.Text + + // Threading support + parentCommentId String? // null = top-level comment, non-null = reply + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + mentorFile MentorFile @relation(fields: [mentorFileId], references: [id], onDelete: Cascade) + author User @relation("MentorFileCommentAuthor", fields: [authorId], references: [id]) + parentComment MentorFileComment? @relation("CommentThread", fields: [parentCommentId], references: [id], onDelete: Cascade) + replies MentorFileComment[] @relation("CommentThread") + + @@index([mentorFileId]) + @@index([authorId]) + @@index([parentCommentId]) +} +``` + +### MentorAssignment Modifications + +```prisma +model MentorAssignment { + // ... existing fields preserved ... + id String @id @default(cuid()) + projectId String @unique + mentorId String + method AssignmentMethod @default(MANUAL) + assignedAt DateTime @default(now()) + assignedBy String? + aiConfidenceScore Float? + expertiseMatchScore Float? + aiReasoning String? @db.Text + completionStatus String @default("in_progress") + lastViewedAt DateTime? + + // NEW: Workspace activation + workspaceEnabled Boolean @default(false) // Activated when MENTORING round opens + workspaceOpenAt DateTime? // When mentoring files/chat becomes available + workspaceCloseAt DateTime? // When workspace access ends + + // Relations (existing + new) + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + mentor User @relation("MentorAssignment", fields: [mentorId], references: [id]) + notes MentorNote[] + milestoneCompletions MentorMilestoneCompletion[] + messages MentorMessage[] + files MentorFile[] // NEW: Workspace files +} +``` + +--- + +## 6. Winner Confirmation System + +### WinnerProposal + +```prisma +model WinnerProposal { + id String @id @default(cuid()) + competitionId String + category CompetitionCategory // STARTUP or BUSINESS_CONCEPT + + status WinnerProposalStatus @default(PENDING) + + // Proposed rankings (ordered list of project IDs) + rankedProjectIds String[] // ["proj-1st", "proj-2nd", "proj-3rd"] + + // Selection basis (evidence) + sourceRoundId String // Which round's scores/votes informed this + selectionBasis Json @db.JsonB // { method, scores, aiRecommendation, reasoning } + + // Proposer + proposedById String + proposedAt DateTime @default(now()) + + // Finalization + frozenAt DateTime? + frozenById String? + + // Admin override (if used) + overrideUsed Boolean @default(false) + overrideMode String? // "FORCE_MAJORITY" | "ADMIN_DECISION" + overrideReason String? @db.Text + overrideById String? + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + sourceRound Round @relation("WinnerProposalSource", fields: [sourceRoundId], references: [id]) + proposedBy User @relation("WinnerProposer", fields: [proposedById], references: [id]) + frozenBy User? @relation("WinnerFreezer", fields: [frozenById], references: [id]) + overrideBy User? @relation("WinnerOverrider", fields: [overrideById], references: [id]) + approvals WinnerApproval[] + + @@index([competitionId]) + @@index([status]) +} + +enum WinnerProposalStatus { + PENDING // Waiting for jury approvals + APPROVED // All required approvals received + REJECTED // At least one rejection + OVERRIDDEN // Admin used override + FROZEN // Locked — official results +} +``` + +### WinnerApproval + +```prisma +model WinnerApproval { + id String @id @default(cuid()) + winnerProposalId String + userId String + role WinnerApprovalRole + + // Response + approved Boolean? // null = not yet responded + comments String? @db.Text + respondedAt DateTime? + + createdAt DateTime @default(now()) + + // Relations + proposal WinnerProposal @relation(fields: [winnerProposalId], references: [id], onDelete: Cascade) + user User @relation("WinnerApprovalUser", fields: [userId], references: [id]) + + @@unique([winnerProposalId, userId]) + @@index([winnerProposalId]) + @@index([userId]) +} + +enum WinnerApprovalRole { + JURY_MEMBER // Must individually confirm + ADMIN // Final sign-off (or override) +} +``` + +--- + +## 7. Modified Existing Models + +### ProjectFile — Add Submission Window Link + +```prisma +model ProjectFile { + id String @id @default(cuid()) + projectId String + + // CHANGED: Link to SubmissionWindow instead of legacy roundId + submissionWindowId String? + requirementId String? // Links to SubmissionFileRequirement + + fileType FileType + fileName String + mimeType String + size Int + bucket String + objectKey String + + isLate Boolean @default(false) + version Int @default(1) + replacedById String? @unique + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + submissionWindow SubmissionWindow? @relation(fields: [submissionWindowId], references: [id], onDelete: SetNull) + requirement SubmissionFileRequirement? @relation(fields: [requirementId], references: [id], onDelete: SetNull) + replacedBy ProjectFile? @relation("FileVersion", fields: [replacedById], references: [id]) + previousVersion ProjectFile? @relation("FileVersion") + promotedFrom MentorFile? @relation("PromotedFromMentorFile") // NEW + + @@index([projectId]) + @@index([submissionWindowId]) + @@index([requirementId]) +} +``` + +### Assignment — Add JuryGroup Link + +```prisma +model Assignment { + // ... all existing fields preserved ... + id String @id @default(cuid()) + userId String + projectId String + roundId String // RENAMED from stageId + method AssignmentMethod @default(MANUAL) + isRequired Boolean @default(true) + isCompleted Boolean @default(false) + aiConfidenceScore Float? + expertiseMatchScore Float? + aiReasoning String? @db.Text + + // NEW: Link to jury group + juryGroupId String? + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + round Round @relation(fields: [roundId], references: [id], onDelete: Cascade) + juryGroup JuryGroup? @relation(fields: [juryGroupId], references: [id], onDelete: SetNull) + evaluation Evaluation? + coi ConflictOfInterest? + + @@unique([userId, projectId, roundId]) + @@index([userId]) + @@index([projectId]) + @@index([roundId]) + @@index([juryGroupId]) +} +``` + +### SpecialAward — Enhanced Standalone + +```prisma +model SpecialAward { + id String @id @default(cuid()) + competitionId String // CHANGED: Links to Competition, not Track + name String + description String? @db.Text + criteriaText String? @db.Text // For AI eligibility + + // Award mode + eligibilityMode AwardEligibilityMode @default(STAY_IN_MAIN) + + // Scoring/voting + scoringMode AwardScoringMode @default(PICK_WINNER) + maxRankedPicks Int? // For RANKED mode + + // Decision + decisionMode String @default("JURY_VOTE") // "JURY_VOTE" | "AWARD_MASTER_DECISION" | "ADMIN_DECISION" + + // Status + status AwardStatus @default(DRAFT) + + // Voting window + votingStartAt DateTime? + votingEndAt DateTime? + + // Runs alongside which evaluation round + evaluationRoundId String? // NEW: Which round this award runs during + + // Jury (can be its own group or share a competition jury group) + juryGroupId String? // NEW: Dedicated or shared jury group + + // Winner + winnerProjectId String? + winnerOverridden Boolean @default(false) + + // AI + useAiEligibility Boolean @default(false) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + evaluationRound Round? @relation("AwardEvaluationRound", fields: [evaluationRoundId], references: [id], onDelete: SetNull) + juryGroup JuryGroup? @relation("AwardJuryGroup", fields: [juryGroupId], references: [id], onDelete: SetNull) + winnerProject Project? @relation("AwardWinner", fields: [winnerProjectId], references: [id], onDelete: SetNull) + eligibilities AwardEligibility[] + jurors AwardJuror[] + votes AwardVote[] + + @@index([competitionId]) + @@index([status]) + @@index([evaluationRoundId]) +} + +enum AwardEligibilityMode { + SEPARATE_POOL // Projects pulled out of main flow into award-only track + STAY_IN_MAIN // Projects remain in main competition, flagged as award-eligible +} + +enum AwardStatus { + DRAFT + NOMINATIONS_OPEN + VOTING_OPEN + CLOSED + ARCHIVED +} + +enum AwardScoringMode { + PICK_WINNER + RANKED + SCORED +} +``` + +### Evaluation — Rename stageId to roundId + +```prisma +model Evaluation { + // All fields preserved, stageId references updated to roundId via Assignment.roundId + id String @id @default(cuid()) + assignmentId String @unique + status EvaluationStatus @default(NOT_STARTED) + criterionScoresJson Json? @db.JsonB + globalScore Int? + binaryDecision Boolean? + feedbackText String? @db.Text + submittedAt DateTime? + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + assignment Assignment @relation(fields: [assignmentId], references: [id], onDelete: Cascade) +} +``` + +### Project — Remove roundId, add competition link + +```prisma +model Project { + // ... existing fields ... + id String @id @default(cuid()) + programId String + competitionId String? // NEW: Direct link to competition + + // Remove legacy roundId field + // roundId String? -- REMOVED + + status ProjectStatus @default(SUBMITTED) + title String + teamName String? + description String? @db.Text + competitionCategory CompetitionCategory? + // ... all other existing fields preserved ... + + wantsMentorship Boolean @default(false) // Preserved — drives mentoring eligibility + + // Relations (updated) + program Program @relation(fields: [programId], references: [id], onDelete: Cascade) + competition Competition? @relation(fields: [competitionId], references: [id], onDelete: SetNull) + files ProjectFile[] + teamMembers TeamMember[] + projectRoundStates ProjectRoundState[] // RENAMED from projectStageStates + assignments Assignment[] + mentorAssignment MentorAssignment? + // ... other existing relations preserved ... + + @@index([programId]) + @@index([competitionId]) + @@index([status]) + @@index([competitionCategory]) +} +``` + +--- + +## 8. Round-Type Config Shapes (Zod-validated) + +Each round type has a specific config shape stored in `Round.configJson`. These replace the old generic `configJson` approach with documented, validated structures. + +### INTAKE Config + +```typescript +type IntakeConfig = { + // Submission behavior + allowDrafts: boolean // Allow saving drafts before submitting + draftExpiryDays: number // Auto-delete drafts after N days (default: 30) + + // What categories are accepted + acceptedCategories: ("STARTUP" | "BUSINESS_CONCEPT")[] + + // Public form settings + publicFormEnabled: boolean // Allow anonymous form access via slug + customFields: CustomFieldDef[] // Additional form fields beyond standard ones +} +``` + +### FILTERING Config + +```typescript +type FilteringConfig = { + // Rule engine + rules: FilterRuleDef[] // Field-based and document-check rules + + // AI screening + aiScreeningEnabled: boolean + aiCriteriaText: string // Plain-language criteria for AI + aiConfidenceThresholds: { + high: number // Above this = auto-pass (default: 0.85) + medium: number // Above this = flag for review (default: 0.6) + low: number // Below this = auto-reject (default: 0.4) + } + + // Manual queue + manualReviewEnabled: boolean // Flagged projects need admin review + + // Batch processing + batchSize: number // Projects per AI batch (default: 20) +} +``` + +### EVALUATION Config + +```typescript +type EvaluationConfig = { + // Assignment settings (work with JuryGroup) + requiredReviewsPerProject: number // How many jurors review each project (default: 3) + + // Assignment caps are now on JuryGroup and JuryGroupMember + // (no longer duplicated here) + + // Scoring + scoringMode: "criteria" | "global" | "binary" // How jurors score + requireFeedback: boolean // Must submit text feedback + + // COI + coiRequired: boolean // Must declare COI before evaluating (default: true) + + // Peer review + peerReviewEnabled: boolean // Allow jurors to see anonymized peer evaluations + anonymizationLevel: "fully_anonymous" | "show_initials" | "named" + + // AI features + aiSummaryEnabled: boolean // Generate AI evaluation summaries + + // Advancement (what happens after evaluation ends) + advancementMode: "auto_top_n" | "admin_selection" | "ai_recommended" + advancementConfig: { + perCategory: boolean + startupCount: number // How many startups advance + conceptCount: number // How many concepts advance + tieBreaker: "admin_decides" | "highest_individual" | "revote" + } +} +``` + +### SUBMISSION Config + +```typescript +type SubmissionConfig = { + // Who can submit (based on status from previous round) + eligibleStatuses: ProjectRoundStateValue[] // Usually ["PASSED"] + + // Notification + notifyEligibleTeams: boolean // Email teams when window opens + + // Previous rounds become read-only for applicants + lockPreviousWindows: boolean // Default: true +} +``` + +### MENTORING Config + +```typescript +type MentoringConfig = { + // Who gets mentoring + eligibility: "all_advancing" | "requested_only" // All finalists or only those who requested + + // Workspace features + chatEnabled: boolean + fileUploadEnabled: boolean + fileCommentsEnabled: boolean + filePromotionEnabled: boolean // Can promote files to official submissions + + // Target submission window for promotions + promotionTargetWindowId: string? // Which SubmissionWindow promoted files go to + + // Auto-assignment + autoAssignMentors: boolean // Use AI/algorithm to assign mentors +} +``` + +### LIVE_FINAL Config + +```typescript +type LiveFinalConfig = { + // Jury voting + juryVotingEnabled: boolean + votingMode: "simple" | "criteria" // Simple 1-10 or criteria-based + + // Audience voting + audienceVotingEnabled: boolean + audienceVoteWeight: number // 0.0 to 1.0 (weight vs jury vote) + audienceVotingMode: "per_project" | "per_category" | "favorites" + audienceMaxFavorites: number? // For "favorites" mode + audienceRequireIdentification: boolean + + // Deliberation + deliberationEnabled: boolean + deliberationDurationMinutes: number // Length of deliberation period + showAudienceVotesToJury: boolean // Jury sees audience results during deliberation + + // Presentation + presentationOrderMode: "manual" | "random" | "score_based" + + // Results reveal + revealPolicy: "immediate" | "delayed" | "ceremony" +} +``` + +### CONFIRMATION Config + +```typescript +type ConfirmationConfig = { + // Approval requirements + requireAllJuryApproval: boolean // All jury members must individually confirm (default: true) + juryGroupId: string? // Which jury group must approve (usually Jury 3 / finals jury) + + // Admin override + adminOverrideEnabled: boolean // Admin can force result (default: true) + overrideModes: ("FORCE_MAJORITY" | "ADMIN_DECISION")[] // Available override options + + // Freeze behavior + autoFreezeOnApproval: boolean // Lock results immediately when all approve (default: true) + + // Per-category confirmation + perCategory: boolean // Separate confirmation per STARTUP vs BUSINESS_CONCEPT +} +``` + +--- + +## 9. Models Preserved As-Is (rename stageId -> roundId only) + +These models are structurally unchanged. The only modification is renaming foreign keys from `stageId` to `roundId` and removing any `trackId` references: + +| Model | Change | +|-------|--------| +| `EvaluationForm` | `stageId` -> `roundId` | +| `Evaluation` | No direct roundId (via Assignment) | +| `ConflictOfInterest` | No change (via Assignment) | +| `GracePeriod` | `stageId` -> `roundId` | +| `EvaluationSummary` | `stageId` -> `roundId` | +| `EvaluationDiscussion` | `stageId` -> `roundId` | +| `DiscussionComment` | No change | +| `FilteringRule` | `stageId` -> `roundId` | +| `FilteringResult` | `stageId` -> `roundId` | +| `FilteringJob` | `stageId` -> `roundId` | +| `LiveVotingSession` | `stageId` -> `roundId` | +| `LiveVote` | No change (via Session) | +| `AudienceVoter` | No change (via Session) | +| `LiveProgressCursor` | `stageId` -> `roundId` | +| `Cohort` | `stageId` -> `roundId` | +| `CohortProject` | No change | +| `AwardEligibility` | No change | +| `AwardJuror` | No change | +| `AwardVote` | No change | +| `MentorMessage` | No change | +| `MentorNote` | No change | +| `MentorMilestone` | No change | +| `MentorMilestoneCompletion` | No change | +| `InAppNotification` | No change | +| `AuditLog` | No change | +| `DecisionAuditLog` | No change | +| `User` | Add `juryGroupMemberships` relation | +| `Program` | Add `competitions` relation (was `pipelines`) | + +--- + +## 10. User Model Additions + +```prisma +model User { + // ... all existing fields preserved ... + + // NEW relations + juryGroupMemberships JuryGroupMember[] + mentorFileUploads MentorFile[] @relation("MentorFileUploader") + mentorFilePromotions MentorFile[] @relation("MentorFilePromoter") + mentorFileComments MentorFileComment[] @relation("MentorFileCommentAuthor") + winnerProposals WinnerProposal[] @relation("WinnerProposer") + winnerFreezes WinnerProposal[] @relation("WinnerFreezer") + winnerOverrides WinnerProposal[] @relation("WinnerOverrider") + winnerApprovals WinnerApproval[] @relation("WinnerApprovalUser") +} +``` + +--- + +## 11. Entity Relationship Summary + +``` +Program (1) ──── (N) Competition +Competition (1) ──── (N) Round +Competition (1) ──── (N) JuryGroup +Competition (1) ──── (N) SubmissionWindow +Competition (1) ──── (N) SpecialAward +Competition (1) ──── (N) WinnerProposal + +Round (N) ──── (1) JuryGroup (optional — for EVALUATION and LIVE_FINAL rounds) +Round (N) ──── (1) SubmissionWindow (optional — for INTAKE and SUBMISSION rounds) +Round (1) ──── (N) RoundSubmissionVisibility ──── (N) SubmissionWindow + +JuryGroup (1) ──── (N) JuryGroupMember ──── (1) User +JuryGroup (1) ──── (N) Assignment + +SubmissionWindow (1) ──── (N) SubmissionFileRequirement +SubmissionWindow (1) ──── (N) ProjectFile + +Project (1) ──── (N) ProjectRoundState ──── (1) Round +Project (1) ──── (N) Assignment ──── (1) Evaluation +Project (1) ──── (N) ProjectFile +Project (1) ──── (0..1) MentorAssignment ──── (N) MentorFile ──── (N) MentorFileComment + +SpecialAward (N) ──── (1) JuryGroup (optional) +SpecialAward (N) ──── (1) Round (evaluationRound — runs alongside) + +WinnerProposal (1) ──── (N) WinnerApproval +``` + +--- + +## 12. Migration Strategy (High-Level) + +### Phase 1: Add new tables (non-breaking) +1. Create `Competition` table +2. Create `Round` table +3. Create `JuryGroup`, `JuryGroupMember` tables +4. Create `SubmissionWindow`, `SubmissionFileRequirement`, `RoundSubmissionVisibility` tables +5. Create `MentorFile`, `MentorFileComment` tables +6. Create `WinnerProposal`, `WinnerApproval` tables +7. Create `AdvancementRule` table +8. Create `ProjectRoundState` table +9. Add new columns to `Assignment` (juryGroupId), `ProjectFile` (submissionWindowId), `MentorAssignment` (workspace fields), `SpecialAward` (competitionId, eligibilityMode, juryGroupId, evaluationRoundId), `Project` (competitionId) + +### Phase 2: Data migration +1. For each Pipeline: Create a Competition record +2. For each Stage in the MAIN Track: Create a Round record (maintaining sortOrder) +3. For each ProjectStageState: Create a ProjectRoundState record (dropping trackId) +4. For each AWARD Track: Migrate to SpecialAward (link to Competition + evaluation round) +5. For existing FileRequirements: Create SubmissionWindow + SubmissionFileRequirement +6. For existing Assignments with stageId: Update roundId reference +7. Create default JuryGroups from existing assignments (group by stageId) + +### Phase 3: Code migration +1. Update all services (stageId -> roundId, remove trackId references) +2. Update all routers (rename, new endpoints) +3. Update all UI (new pages, enhanced existing pages) + +### Phase 4: Drop old tables (after verification) +1. Drop `Track` table +2. Drop `StageTransition` table +3. Drop `ProjectStageState` table (after verifying ProjectRoundState) +4. Drop `Stage` table (after verifying Round) +5. Drop `Pipeline` table (after verifying Competition) +6. Clean up old enums + +Detailed migration SQL will be in `21-migration-strategy.md`. diff --git a/docs/claude-architecture-redesign/04-round-intake.md b/docs/claude-architecture-redesign/04-round-intake.md new file mode 100644 index 0000000..cb95ddf --- /dev/null +++ b/docs/claude-architecture-redesign/04-round-intake.md @@ -0,0 +1,1539 @@ +# Round Type: INTAKE — Application Window + +## 1. Overview + +The **INTAKE round** is the first phase of any MOPC competition. It represents the application submission window where teams apply to participate by submitting their ocean conservation projects along with required documentation. + +### Purpose +- Collect project applications from teams worldwide +- Capture essential project information (title, description, team, ocean issue addressed) +- Receive required documentation (executive summaries, business plans, videos) +- Support draft/save-and-continue workflow for incomplete applications +- Enforce submission deadlines with configurable late submission policies +- Enable both authenticated (user login) and public (anonymous) application flows + +### Position in Competition Flow + +``` +Competition 2026 + └─ Round 1: "Application Window" ────── [INTAKE] + └─ Round 2: "AI Screening" ───────── [FILTERING] + └─ Round 3: "Jury Evaluation 1" ── [EVALUATION] + └─ Round 4: "Semi-finalist Docs" ── [SUBMISSION] + └─ ... +``` + +The intake round creates the initial pool of projects that flow through subsequent rounds. All projects begin here. + +--- + +## 2. Current System (Pipeline/Track/Stage) + +### How Intake Works Today + +In the current architecture, intake is implemented as a **Stage** with `StageType: INTAKE` inside the MAIN track. + +```typescript +// Current structure +Pipeline: "MOPC 2026" + └─ Track: "Main Competition" (kind: MAIN) + └─ Stage: "Intake" (stageType: INTAKE) + ├─ windowOpenAt: 2026-01-15T00:00:00Z + ├─ windowCloseAt: 2026-03-01T23:59:59Z + ├─ configJson: { + │ submissionWindowEnabled: true, + │ lateSubmissionPolicy: "flag", + │ lateGraceHours: 24, + │ fileRequirements: [...] + │ } + └─ FileRequirement records (linked to stageId) +``` + +### Current Config Fields (src/lib/pipeline-defaults.ts) + +```typescript +type IntakeConfig = { + submissionWindowEnabled: boolean // Whether submission is open + lateSubmissionPolicy: 'reject' | 'flag' | 'accept' + lateGraceHours: number // Hours after close for late submissions + fileRequirements: FileRequirementConfig[] +} + +type FileRequirementConfig = { + name: string // "Executive Summary" + description?: string // Help text + acceptedMimeTypes: string[] // ["application/pdf"] + maxSizeMB?: number // 50 + isRequired: boolean // true +} +``` + +### Current Applicant Flow + +1. **Access**: Applicant visits `/applicant/pipeline/{slug}` or receives invite link +2. **Auth**: User logs in (email magic link or password) or proceeds as guest +3. **Form**: Fills out project form (title, description, category, ocean issue, team info) +4. **Files**: Uploads required files (exec summary, business plan, video) +5. **Draft**: Can save as draft and return later +6. **Submit**: Final submission creates Project record with status "SUBMITTED" +7. **Email**: Confirmation email sent if configured + +### Current Admin Experience + +Admins configure the intake stage via the pipeline wizard: +- Set open/close dates +- Define file requirements (name, mime types, size limits, required/optional) +- Choose late submission policy (reject, flag, accept) +- Set grace period for late submissions + +### Current Database Schema + +```prisma +model Stage { + id String @id + trackId String + stageType StageType // INTAKE + name String + slug String + status StageStatus + configJson Json? // IntakeConfig stored here + windowOpenAt DateTime? + windowCloseAt DateTime? + ... +} + +model FileRequirement { + id String @id + stageId String // Links to intake stage + name String + acceptedMimeTypes String[] + maxSizeMB Int? + isRequired Boolean + sortOrder Int + ... +} + +model ProjectFile { + id String @id + projectId String + roundId String? // Legacy field + requirementId String? // FK to FileRequirement + fileType FileType + fileName String + mimeType String + size Int + bucket String + objectKey String + isLate Boolean @default(false) + version Int @default(1) + ... +} + +model Project { + id String @id + programId String + roundId String? // Legacy — which round project was submitted for + status ProjectStatus @default(SUBMITTED) + title String + teamName String? + description String? + competitionCategory CompetitionCategory? // STARTUP | BUSINESS_CONCEPT + oceanIssue OceanIssue? + country String? + wantsMentorship Boolean @default(false) + isDraft Boolean @default(false) + draftDataJson Json? // Form data for drafts + draftExpiresAt DateTime? + submissionSource SubmissionSource @default(MANUAL) + submittedByEmail String? + submittedAt DateTime? + submittedByUserId String? + ... +} +``` + +### Current Limitations + +| Issue | Impact | +|-------|--------| +| **Single submission window** | Can't require new docs from semi-finalists | +| **No form builder** | All fields hardcoded in application code | +| **No category quotas at intake** | Can't limit "first 50 startups, first 50 concepts" | +| **Generic configJson** | Unclear what fields exist for intake stages | +| **File requirements per stage** | Awkward: "intake stage" is the only stage with file requirements | +| **No dynamic forms** | Can't add custom questions per competition year | +| **No public form branding** | External applicants see generic MOPC form | + +--- + +## 3. Redesigned Intake Round + +### New Round Structure + +```typescript +// Redesigned +Competition: "MOPC 2026" + └─ Round 1: "Application Window" (roundType: INTAKE) + ├─ competitionId: competition-2026 + ├─ name: "Application Window" + ├─ slug: "application-window" + ├─ roundType: INTAKE + ├─ status: ROUND_ACTIVE + ├─ sortOrder: 0 + ├─ windowOpenAt: 2026-01-15T00:00:00Z + ├─ windowCloseAt: 2026-03-01T23:59:59Z + ├─ submissionWindowId: "sw-1" // NEW: Links to SubmissionWindow + ├─ configJson: IntakeConfig { // NEW: Typed, validated config + │ applicationFormId: "form-2026", + │ deadlinePolicy: "GRACE", + │ gracePeriodMinutes: 180, + │ allowDraftSubmissions: true, + │ requireTeamProfile: true, + │ maxTeamSize: 5, + │ minTeamSize: 1, + │ autoConfirmReceipt: true, + │ publicFormEnabled: true, + │ categoryQuotas: { STARTUP: 100, BUSINESS_CONCEPT: 100 } + │ } + └─ SubmissionWindow: "Round 1 Docs" + ├─ id: "sw-1" + ├─ competitionId: competition-2026 + ├─ name: "Round 1 Application Docs" + ├─ slug: "round-1-docs" + ├─ roundNumber: 1 + ├─ windowOpenAt: 2026-01-15T00:00:00Z + ├─ windowCloseAt: 2026-03-01T23:59:59Z + ├─ deadlinePolicy: GRACE + ├─ graceHours: 3 + └─ FileRequirements: [ + ├─ "Executive Summary" (PDF, required) + ├─ "Business Plan" (PDF, required) + └─ "Video Pitch" (video/*, optional) + ] +``` + +### IntakeConfig Type (Zod-validated) + +```typescript +type IntakeConfig = { + // Application Form + applicationFormId: string // Links to ApplicationForm template (future) + + // Submission Window (linked via Round.submissionWindowId) + submissionWindowId: string // Which SubmissionWindow to use + + // Deadline Behavior + deadlinePolicy: DeadlinePolicy // HARD | FLAG | GRACE + gracePeriodMinutes: number // For GRACE policy (e.g., 180 = 3 hours) + + // Draft System + allowDraftSubmissions: boolean // Save-and-continue enabled + draftExpiryDays: number // Auto-delete abandoned drafts after N days + + // Team Profile + requireTeamProfile: boolean // Require team member info + maxTeamSize: number // Max team members (including lead) + minTeamSize: number // Min team members (default: 1) + + // Notifications + autoConfirmReceipt: boolean // Email confirmation on submission + reminderEmailSchedule: number[] // Days before deadline: [7, 3, 1] + + // Public Access + publicFormEnabled: boolean // Allow external application link + publicFormSlug?: string // Custom slug for public URL + + // Category Quotas (STARTUP vs BUSINESS_CONCEPT) + categoryQuotasEnabled: boolean + categoryQuotas?: { + STARTUP: number // Max startups accepted + BUSINESS_CONCEPT: number // Max concepts accepted + } + quotaOverflowPolicy?: 'reject' | 'waitlist' // What happens when quota full + + // Custom Fields (future: dynamic form builder) + customFields?: CustomFieldDef[] // Additional form fields +} + +enum DeadlinePolicy { + HARD // Submissions blocked after deadline, no exceptions + FLAG // Submissions accepted but flagged as late + GRACE // Accept for N minutes after deadline with warning +} + +type CustomFieldDef = { + id: string + label: string + type: 'text' | 'textarea' | 'select' | 'multiselect' | 'date' | 'number' + required: boolean + options?: string[] // For select/multiselect + validation?: { + min?: number + max?: number + regex?: string + } +} +``` + +### Zod Schema for Validation + +```typescript +import { z } from 'zod' + +export const intakeConfigSchema = z.object({ + applicationFormId: z.string().cuid(), + submissionWindowId: z.string().cuid(), + + deadlinePolicy: z.enum(['HARD', 'FLAG', 'GRACE']), + gracePeriodMinutes: z.number().int().min(0).max(1440), // Max 24 hours + + allowDraftSubmissions: z.boolean().default(true), + draftExpiryDays: z.number().int().min(1).default(30), + + requireTeamProfile: z.boolean().default(true), + maxTeamSize: z.number().int().min(1).max(20).default(5), + minTeamSize: z.number().int().min(1).default(1), + + autoConfirmReceipt: z.boolean().default(true), + reminderEmailSchedule: z.array(z.number().int()).default([7, 3, 1]), + + publicFormEnabled: z.boolean().default(false), + publicFormSlug: z.string().optional(), + + categoryQuotasEnabled: z.boolean().default(false), + categoryQuotas: z.object({ + STARTUP: z.number().int().min(0), + BUSINESS_CONCEPT: z.number().int().min(0), + }).optional(), + quotaOverflowPolicy: z.enum(['reject', 'waitlist']).optional(), + + customFields: z.array(z.object({ + id: z.string(), + label: z.string().min(1).max(200), + type: z.enum(['text', 'textarea', 'select', 'multiselect', 'date', 'number']), + required: z.boolean(), + options: z.array(z.string()).optional(), + validation: z.object({ + min: z.number().optional(), + max: z.number().optional(), + regex: z.string().optional(), + }).optional(), + })).optional(), +}) + +export type IntakeConfig = z.infer +``` + +--- + +## 4. Application Form System + +### ApplicationForm Model (Future Enhancement) + +For now, the application form is hardcoded. In the future, a dynamic form builder will replace this. + +```prisma +model ApplicationForm { + id String @id @default(cuid()) + competitionId String + name String // "MOPC 2026 Application" + description String? + fieldsJson Json @db.JsonB // Array of field definitions + version Int @default(1) + isActive Boolean @default(true) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + + @@index([competitionId]) + @@index([isActive]) +} +``` + +### Standard Form Fields (Hardcoded for MVP) + +```typescript +type ApplicationFormData = { + // Project Info + title: string // Required, 1-500 chars + teamName?: string // Optional + description: string // Required, max 5000 chars + competitionCategory: 'STARTUP' | 'BUSINESS_CONCEPT' // Required + oceanIssue: OceanIssue // Required enum + + // Location + country: string // Required + geographicZone?: string // "Europe, France" + institution?: string // Required for BUSINESS_CONCEPT + + // Founding + foundedAt?: Date // When project/company started + + // Mentorship + wantsMentorship: boolean // Default: false + + // Referral + referralSource?: string // "LinkedIn", "Email", etc. + + // Team Members (if requireTeamProfile: true) + teamMembers?: TeamMemberInput[] + + // Custom Fields (future) + customFieldValues?: Record +} + +type TeamMemberInput = { + name: string + email: string + role: 'LEAD' | 'MEMBER' | 'ADVISOR' + title?: string // "CEO", "CTO" +} +``` + +### Field Validation Rules + +| Field | Validation | Error Message | +|-------|-----------|---------------| +| `title` | Required, 1-500 chars | "Project title is required" | +| `description` | Required, max 5000 chars | "Description must be under 5000 characters" | +| `competitionCategory` | Required enum | "Please select Startup or Business Concept" | +| `oceanIssue` | Required enum | "Please select an ocean issue" | +| `country` | Required string | "Country is required" | +| `institution` | Required if category = BUSINESS_CONCEPT | "Institution is required for student projects" | +| `teamMembers[].email` | Valid email format | "Invalid email address" | +| `teamMembers.length` | >= minTeamSize, <= maxTeamSize | "Team must have 1-5 members" | + +### Conditional Logic + +- **Institution field**: Only shown/required when `competitionCategory = BUSINESS_CONCEPT` +- **Team members section**: Only shown if `requireTeamProfile = true` in config +- **Mentorship checkbox**: Always shown, default unchecked + +--- + +## 5. Submission Window Integration + +### SubmissionWindow Model (from 03-data-model.md) + +```prisma +model SubmissionWindow { + id String @id @default(cuid()) + competitionId String + name String // "Round 1 Application Docs" + slug String // "round-1-docs" + roundNumber Int // 1 (first window), 2 (second window), etc. + sortOrder Int @default(0) + + windowOpenAt DateTime? + windowCloseAt DateTime? + + deadlinePolicy DeadlinePolicy @default(FLAG) + graceHours Int? // For GRACE policy + + lockOnClose Boolean @default(true) // Prevent edits after close + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + fileRequirements SubmissionFileRequirement[] + projectFiles ProjectFile[] + rounds Round[] // INTAKE rounds using this window + visibility RoundSubmissionVisibility[] + + @@unique([competitionId, slug]) + @@unique([competitionId, roundNumber]) + @@index([competitionId]) +} + +model SubmissionFileRequirement { + id String @id @default(cuid()) + submissionWindowId String + name String // "Executive Summary" + description String? @db.Text + acceptedMimeTypes String[] // ["application/pdf"] + maxSizeMB Int? + isRequired Boolean @default(true) + sortOrder Int @default(0) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + submissionWindow SubmissionWindow @relation(fields: [submissionWindowId], references: [id], onDelete: Cascade) + files ProjectFile[] + + @@index([submissionWindowId]) +} +``` + +### How Intake Round Links to SubmissionWindow + +```typescript +// Round creation +const round = await prisma.round.create({ + data: { + competitionId: competition.id, + name: "Application Window", + slug: "application-window", + roundType: "INTAKE", + sortOrder: 0, + windowOpenAt: new Date("2026-01-15T00:00:00Z"), + windowCloseAt: new Date("2026-03-01T23:59:59Z"), + submissionWindowId: submissionWindow.id, // Link to window + configJson: { + applicationFormId: "form-2026", + submissionWindowId: submissionWindow.id, // Redundant but explicit + deadlinePolicy: "GRACE", + gracePeriodMinutes: 180, + // ... rest of IntakeConfig + } + } +}) +``` + +### File Requirements for Intake + +Admin configures file requirements at the **SubmissionWindow** level, not the round level. + +```typescript +// Example: Create file requirements for Round 1 docs +const requirements = await prisma.submissionFileRequirement.createMany({ + data: [ + { + submissionWindowId: "sw-1", + name: "Executive Summary", + description: "A PDF executive summary of your project (max 2 pages)", + acceptedMimeTypes: ["application/pdf"], + maxSizeMB: 10, + isRequired: true, + sortOrder: 0, + }, + { + submissionWindowId: "sw-1", + name: "Business Plan", + description: "Full business plan or project proposal (PDF)", + acceptedMimeTypes: ["application/pdf"], + maxSizeMB: 50, + isRequired: true, + sortOrder: 1, + }, + { + submissionWindowId: "sw-1", + name: "Video Pitch", + description: "Optional video pitch (max 5 minutes, MP4 or MOV)", + acceptedMimeTypes: ["video/mp4", "video/quicktime"], + maxSizeMB: 500, + isRequired: false, + sortOrder: 2, + }, + ] +}) +``` + +### Deadline Enforcement + +When an applicant tries to upload a file or submit the form: + +```typescript +async function canSubmitToWindow(submissionWindow: SubmissionWindow): Promise<{ + canSubmit: boolean + reason?: string + isLate?: boolean +}> { + const now = new Date() + + // Not yet open + if (submissionWindow.windowOpenAt && now < submissionWindow.windowOpenAt) { + return { + canSubmit: false, + reason: `Window opens on ${submissionWindow.windowOpenAt.toLocaleDateString()}` + } + } + + // Window closed + if (submissionWindow.windowCloseAt && now > submissionWindow.windowCloseAt) { + const { deadlinePolicy, graceHours } = submissionWindow + + if (deadlinePolicy === 'HARD') { + return { + canSubmit: false, + reason: "Deadline has passed. Submissions are no longer accepted." + } + } + + if (deadlinePolicy === 'GRACE' && graceHours) { + const graceDeadline = new Date(submissionWindow.windowCloseAt.getTime() + graceHours * 60 * 60 * 1000) + if (now > graceDeadline) { + return { + canSubmit: false, + reason: `Grace period ended on ${graceDeadline.toLocaleString()}` + } + } + return { + canSubmit: true, + isLate: true + } + } + + if (deadlinePolicy === 'FLAG') { + return { + canSubmit: true, + isLate: true + } + } + } + + return { canSubmit: true } +} +``` + +--- + +## 6. Draft System + +### Auto-Save Behavior + +When `allowDraftSubmissions: true`, the form auto-saves every 30 seconds (or on field blur). + +```typescript +// Draft auto-save +const saveDraft = async (formData: Partial) => { + const project = await trpc.applicant.saveDraft.mutate({ + programId: programId, + projectId: existingProjectId, // null for new draft + draftData: formData, + }) + + return project +} + +// Draft expiry +const draftExpiresAt = new Date() +draftExpiresAt.setDate(draftExpiresAt.getDate() + config.draftExpiryDays) + +await prisma.project.upsert({ + where: { id: projectId }, + update: { + isDraft: true, + draftDataJson: formData, + draftExpiresAt: draftExpiresAt, + updatedAt: new Date(), + }, + create: { + programId, + isDraft: true, + draftDataJson: formData, + draftExpiresAt: draftExpiresAt, + status: 'SUBMITTED', // Will change to DRAFT status in redesign + submittedByUserId: userId, + submissionSource: 'PUBLIC_FORM', + } +}) +``` + +### Resume Draft Flow + +1. User returns to application page +2. System checks for existing draft: + ```typescript + const draft = await prisma.project.findFirst({ + where: { + programId, + submittedByUserId: userId, + isDraft: true, + draftExpiresAt: { gt: new Date() } // Not expired + } + }) + ``` +3. If found, pre-populate form with `draft.draftDataJson` +4. User can continue editing or discard draft + +### Validation States + +```typescript +type FormValidationState = { + isValid: boolean + canSaveDraft: boolean // Always true + canSubmit: boolean // All required fields filled + files uploaded + errors: Record + warnings: Record +} + +// Example states: +// 1. Empty form → isValid: false, canSaveDraft: true, canSubmit: false +// 2. Partial form → isValid: false, canSaveDraft: true, canSubmit: false +// 3. Complete form → isValid: true, canSaveDraft: true, canSubmit: true +``` + +--- + +## 7. Applicant Experience + +### Landing Page Flow + +``` +┌─────────────────────────────────────────────────────────────┐ +│ MOPC 2026 Application │ +│ ══════════════════════════════════════════════════════ │ +│ │ +│ Application Window: Jan 15 - Mar 1, 2026 │ +│ ⏱️ 23 days remaining │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 🌊 Ocean Conservation Innovation Challenge │ │ +│ │ │ │ +│ │ We're looking for breakthrough ocean projects │ │ +│ │ from startups and student teams worldwide. │ │ +│ │ │ │ +│ │ 📋 Requirements: │ │ +│ │ • Executive Summary (PDF) │ │ +│ │ • Business Plan (PDF) │ │ +│ │ • Video Pitch (optional) │ │ +│ │ │ │ +│ │ ⏱️ Application takes ~30 minutes │ │ +│ │ │ │ +│ │ [ Login to Start ] [ Apply as Guest ] │ │ +│ └────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Multi-Step Application Form + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Step 1 of 4: Project Information │ +│ ●───────○───────○───────○ [Save Draft] [Continue →] │ +│ │ +│ Project Title * │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Ocean Plastic Recycling Platform │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ Team Name │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ PlastiClean Solutions │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ Competition Category * │ +│ ○ Startup (existing company) │ +│ ● Business Concept (student/graduate project) │ +│ │ +│ Institution * (required for Business Concept) │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Stanford University │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ Ocean Issue Addressed * │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ 🔍 Pollution Reduction [Dropdown ▼] │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ Description * (max 5000 characters) │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ PlastiClean is an AI-powered sorting system... │ │ +│ │ │ │ +│ │ 247 / 5000 │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ Country * │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ 🌍 United States [Dropdown ▼] │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ Founding Date │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ 2024-06-01 [Date Picker] │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ☑ I'm interested in mentorship from industry experts │ +│ │ +│ [ ← Back ] [ Save Draft ] [ Continue → ] │ +└─────────────────────────────────────────────────────────────┘ +``` + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Step 2 of 4: Team Members │ +│ ○───────●───────○───────○ [Save Draft] [Continue →] │ +│ │ +│ Team Members (1-5 members) * │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 👤 Sarah Johnson (You) │ │ +│ │ sarah.johnson@stanford.edu │ │ +│ │ Role: Lead | Title: CEO │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 👤 Mark Chen [Remove ✕] │ │ +│ │ Name: ┌──────────────────────┐ │ │ +│ │ │ Mark Chen │ │ │ +│ │ └──────────────────────┘ │ │ +│ │ Email: ┌──────────────────────┐ │ │ +│ │ │ mark@stanford.edu │ │ │ +│ │ └──────────────────────┘ │ │ +│ │ Role: ● Member ○ Advisor │ │ +│ │ Title: ┌──────────────────────┐ │ │ +│ │ │ CTO │ │ │ +│ │ └──────────────────────┘ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ [ + Add Team Member ] │ +│ │ +│ ℹ️ Team members will receive an email invite to view │ +│ your project status. │ +│ │ +│ [ ← Back ] [ Save Draft ] [ Continue → ] │ +└─────────────────────────────────────────────────────────────┘ +``` + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Step 3 of 4: Document Upload │ +│ ○───────○───────●───────○ [Save Draft] [Continue →] │ +│ │ +│ Required Documents │ +│ │ +│ 📄 Executive Summary (PDF, max 10 MB) * │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ✓ PlastiClean_Executive_Summary.pdf │ │ +│ │ Uploaded 2 hours ago | 2.3 MB │ │ +│ │ [ View ] [ Replace ] [ Delete ] │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ 📄 Business Plan (PDF, max 50 MB) * │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 📎 Drag & drop or click to upload │ │ +│ │ │ │ +│ │ Accepted formats: PDF │ │ +│ │ Max size: 50 MB │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Optional Documents │ +│ │ +│ 🎥 Video Pitch (MP4/MOV, max 500 MB) │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ⚡ PlastiClean_Pitch.mp4 │ │ +│ │ Uploading... 67% complete │ │ +│ │ ▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░ │ │ +│ │ [ Cancel ] │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ ⚠️ Please upload all required documents before submitting. │ +│ │ +│ [ ← Back ] [ Save Draft ] [ Continue → ] │ +└─────────────────────────────────────────────────────────────┘ +``` + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Step 4 of 4: Review & Submit │ +│ ○───────○───────○───────● [Save Draft] [Submit] │ +│ │ +│ Review Your Application │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Project Information [Edit Step 1] │ │ +│ │ ───────────────────────────────────────────────── │ │ +│ │ Title: Ocean Plastic Recycling Platform │ │ +│ │ Team: PlastiClean Solutions │ │ +│ │ Category: Business Concept │ │ +│ │ Institution: Stanford University │ │ +│ │ Ocean Issue: Pollution Reduction │ │ +│ │ Country: United States │ │ +│ │ Founded: June 2024 │ │ +│ │ Mentorship: Yes │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Team Members [Edit Step 2] │ │ +│ │ ───────────────────────────────────────────────── │ │ +│ │ • Sarah Johnson (Lead) - sarah.johnson@stanford.edu│ │ +│ │ • Mark Chen (Member) - mark@stanford.edu │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Documents [Edit Step 3] │ │ +│ │ ───────────────────────────────────────────────── │ │ +│ │ ✓ Executive Summary (2.3 MB) │ │ +│ │ ✓ Business Plan (8.7 MB) │ │ +│ │ ✓ Video Pitch (124 MB) │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ ☑ I confirm that all information is accurate and that I │ +│ have the authority to submit this application. │ +│ │ +│ ☑ I agree to the MOPC Terms & Conditions │ +│ │ +│ ⏱️ Deadline: March 1, 2026 at 11:59 PM UTC │ +│ │ +│ [ ← Back ] [ Save Draft ] [ Submit ✓ ] │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Post-Submission Confirmation + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ✓ Application Submitted Successfully │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 🎉 Thank You! │ │ +│ │ │ │ +│ │ Your application has been submitted successfully. │ │ +│ │ │ │ +│ │ Confirmation #: MOPC-2026-00123 │ │ +│ │ Submitted: Feb 15, 2026 at 3:42 PM UTC │ │ +│ │ │ │ +│ │ ✉️ A confirmation email has been sent to: │ │ +│ │ sarah.johnson@stanford.edu │ │ +│ │ │ │ +│ │ What's Next? │ │ +│ │ ─────────────────────────────────────────── │ │ +│ │ 1. AI Screening (March 2-5) │ │ +│ │ 2. Jury Evaluation (March 10-31) │ │ +│ │ 3. Semi-finalist Notification (April 5) │ │ +│ │ │ │ +│ │ You'll receive email updates at each stage. │ │ +│ │ │ │ +│ │ [ View My Dashboard ] [ Download Receipt ] │ │ +│ │ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Applicant Dashboard (After Submission) + +``` +┌─────────────────────────────────────────────────────────────┐ +│ My Application sarah@stanford.edu│ +│ ══════════════════════════════════════════════════════ │ +│ │ +│ PlastiClean Solutions │ +│ Ocean Plastic Recycling Platform │ +│ Status: Under Review [🟡 In Progress] │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Application Progress │ │ +│ │ │ │ +│ │ ✓ Submitted Feb 15, 2026 │ │ +│ │ ─────────────────────────────────────────── │ │ +│ │ ⏳ AI Screening Expected: Mar 2-5 │ │ +│ │ ─────────────────────────────────────────── │ │ +│ │ ○ Jury Review Expected: Mar 10-31 │ │ +│ │ ─────────────────────────────────────────── │ │ +│ │ ○ Decision Expected: Apr 5 │ │ +│ │ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Deadline Countdown │ │ +│ │ 13 days remaining until March 1, 2026 │ │ +│ │ ▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Quick Actions │ +│ [ 📄 View Application ] [ 📎 Documents ] [ 👥 Team ] │ +│ │ +│ Recent Activity │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ✓ Application submitted Feb 15, 3:42 PM │ │ +│ │ ✓ Video pitch uploaded Feb 15, 3:38 PM │ │ +│ │ ✓ Business plan uploaded Feb 15, 2:15 PM │ │ +│ │ ✓ Executive summary uploaded Feb 15, 1:47 PM │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 8. Admin Experience + +### Intake Round Configuration Wizard + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Configure Round: Application Window │ +│ ══════════════════════════════════════════════════════ │ +│ │ +│ Basic Settings │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Round Name * │ │ +│ │ ┌──────────────────────────────────────────────┐ │ │ +│ │ │ Application Window │ │ │ +│ │ └──────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Submission Window * │ │ +│ │ ┌──────────────────────────────────────────────┐ │ │ +│ │ │ 🔍 Round 1 Docs [Select Window ▼] │ │ │ +│ │ └──────────────────────────────────────────────┘ │ │ +│ │ [ + Create New Window ] │ │ +│ │ │ │ +│ │ Open Date * │ │ +│ │ ┌──────────────────────────────────────────────┐ │ │ +│ │ │ 2026-01-15 00:00 UTC [Date Picker] │ │ │ +│ │ └──────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Close Date * │ │ +│ │ ┌──────────────────────────────────────────────┐ │ │ +│ │ │ 2026-03-01 23:59 UTC [Date Picker] │ │ │ +│ │ └──────────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────┘ │ +│ │ +│ Deadline Policy │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ○ Hard Deadline │ │ +│ │ Block submissions after close time │ │ +│ │ │ │ +│ │ ○ Flag Late Submissions │ │ +│ │ Accept but mark as late │ │ +│ │ │ │ +│ │ ● Grace Period │ │ +│ │ Accept for: ┌────┐ minutes after deadline │ │ +│ │ │ 180│ │ │ +│ │ └────┘ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Draft Settings │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ☑ Allow draft submissions (save & continue) │ │ +│ │ │ │ +│ │ Auto-delete drafts after: ┌────┐ days │ │ +│ │ │ 30 │ │ │ +│ │ └────┘ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Team Profile │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ☑ Require team member information │ │ +│ │ │ │ +│ │ Min team size: ┌───┐ Max team size: ┌───┐ │ │ +│ │ │ 1 │ │ 5 │ │ │ +│ │ └───┘ └───┘ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Notifications │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ☑ Send confirmation email on submission │ │ +│ │ │ │ +│ │ Send deadline reminders: │ │ +│ │ ☑ 7 days before ☑ 3 days before ☑ 1 day before│ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Category Quotas (Optional) │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ☐ Enable category quotas │ │ +│ │ │ │ +│ │ Max Startups: ┌─────┐ │ │ +│ │ │ 100 │ │ │ +│ │ └─────┘ │ │ +│ │ │ │ +│ │ Max Business Concepts: ┌─────┐ │ │ +│ │ │ 100 │ │ │ +│ │ └─────┘ │ │ +│ │ │ │ +│ │ When quota full: ○ Reject ● Add to waitlist │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ [ Cancel ] [ Save Round ] │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Submissions Dashboard + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Round: Application Window Admin Dashboard │ +│ ══════════════════════════════════════════════════════ │ +│ │ +│ Overview │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 123 Total Submissions │ │ +│ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │ +│ │ │ 68 │ 55 │ 12 │ 11 │ │ │ +│ │ │ Startups │ Concepts │ Drafts │ Late │ │ │ +│ │ └──────────┴──────────┴──────────┴──────────┘ │ │ +│ │ │ │ +│ │ Deadline: March 1, 2026 (13 days remaining) │ │ +│ │ ▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Filters: [ All ] [ Startups ] [ Concepts ] [ Late ] [ Drafts ]│ +│ Search: ┌─────────────────────────────────────┐ [Export ↓] │ +│ │ 🔍 Search by project or team... │ │ +│ └─────────────────────────────────────┘ │ +│ │ +│ Recent Submissions │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ PlastiClean Solutions │ │ +│ │ Ocean Plastic Recycling Platform │ │ +│ │ Business Concept | United States | Feb 15, 3:42 PM │ │ +│ │ [ View ] [ Edit ] [ Override Deadline ] │ │ +│ ├────────────────────────────────────────────────────┤ │ +│ │ AquaTech Innovations │ │ +│ │ Sustainable Aquaculture Monitoring │ │ +│ │ Startup | Norway | Feb 15, 2:18 PM │ │ +│ │ [ View ] [ Edit ] [ Override Deadline ] │ │ +│ ├────────────────────────────────────────────────────┤ │ +│ │ OceanSense Labs 🔴 LATE │ │ +│ │ AI-Powered Ocean Pollution Detection │ │ +│ │ Startup | Singapore | Mar 2, 1:15 AM (+3 hours) │ │ +│ │ [ View ] [ Edit ] [ Override Deadline ] │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ [ Previous ] Page 1 of 7 [ Next ] │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Override Deadline Modal + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Override Deadline: PlastiClean Solutions │ +│ ══════════════════════════════════════════════════════ │ +│ │ +│ Current Status: Submitted on time │ +│ Original Deadline: March 1, 2026 11:59 PM UTC │ +│ │ +│ Extend submission window for this applicant: │ +│ │ +│ New Deadline │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ 2026-03-08 23:59 UTC [Date Picker] │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ Reason for Override * │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ Technical issue during original submission │ │ +│ │ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ ⚠️ This will create a GracePeriod record and allow the │ +│ applicant to edit their submission until the new deadline│ +│ │ +│ [ Cancel ] [ Grant Extension ] │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 9. Deadline Behavior + +### Deadline Policy Comparison + +| Policy | Before Deadline | After Deadline | Grace Period | Flagged | +|--------|----------------|----------------|--------------|---------| +| **HARD** | ✅ Accept | ❌ Block | N/A | N/A | +| **FLAG** | ✅ Accept | ✅ Accept | N/A | ✅ Yes | +| **GRACE** | ✅ Accept | ✅ Accept (for N min) | ✅ Yes | ✅ Yes (after grace) | + +### HARD Policy Behavior + +**Configuration:** +```typescript +{ + deadlinePolicy: "HARD", + gracePeriodMinutes: null // Ignored +} +``` + +**User Experience:** +- **Before deadline**: Form is fully functional, all uploads allowed +- **At deadline**: Form locks immediately at `windowCloseAt` +- **After deadline**: Form displays: + ``` + ❌ Deadline Passed + + The application deadline was March 1, 2026 at 11:59 PM UTC. + Submissions are no longer accepted. + + Contact admin@monaco-opc.com for assistance. + ``` + +**Admin Override:** +- Admin can create a `GracePeriod` record for specific applicant +- This extends their personal deadline (doesn't affect global deadline) + +### FLAG Policy Behavior + +**Configuration:** +```typescript +{ + deadlinePolicy: "FLAG", + gracePeriodMinutes: null // Ignored +} +``` + +**User Experience:** +- **Before deadline**: Normal submission +- **After deadline**: Warning banner shown: + ``` + ⚠️ Late Submission + + The deadline was March 1, 2026. Your submission will be marked as late. + You can still submit, but late submissions may be deprioritized. + ``` +- Submission still works, but `ProjectFile.isLate` set to `true` + +**Database Effect:** +```typescript +await prisma.projectFile.create({ + data: { + projectId, + submissionWindowId, + requirementId, + fileName, + mimeType, + size, + bucket, + objectKey, + isLate: true, // Flagged + // ... + } +}) +``` + +### GRACE Policy Behavior + +**Configuration:** +```typescript +{ + deadlinePolicy: "GRACE", + gracePeriodMinutes: 180 // 3 hours +} +``` + +**User Experience:** +- **Before deadline**: Normal submission +- **0-3 hours after deadline**: Warning banner: + ``` + ⏱️ Grace Period Active + + Deadline: March 1, 2026 11:59 PM UTC (passed) + Grace period ends: March 2, 2026 2:59 AM UTC (1 hour 23 minutes remaining) + + Your submission will be marked as late. Please submit as soon as possible. + ``` +- **After grace period**: Hard block (same as HARD policy) + +**Grace Period Calculation:** +```typescript +const graceDeadline = new Date(windowCloseAt.getTime() + gracePeriodMinutes * 60 * 1000) + +if (now > windowCloseAt && now <= graceDeadline) { + // In grace period + return { + canSubmit: true, + isLate: true, + graceEndsAt: graceDeadline, + remainingMinutes: Math.floor((graceDeadline - now) / 60000) + } +} +``` + +--- + +## 10. Category Quotas + +### How Category Quotas Work + +When `categoryQuotasEnabled: true`, the system tracks submissions per category and enforces limits. + +**Configuration:** +```typescript +{ + categoryQuotasEnabled: true, + categoryQuotas: { + STARTUP: 100, + BUSINESS_CONCEPT: 100 + }, + quotaOverflowPolicy: "reject" // or "waitlist" +} +``` + +### Quota Enforcement Flow + +```typescript +async function canSubmitInCategory( + competitionId: string, + category: 'STARTUP' | 'BUSINESS_CONCEPT', + config: IntakeConfig +): Promise<{ canSubmit: boolean; reason?: string }> { + if (!config.categoryQuotasEnabled || !config.categoryQuotas) { + return { canSubmit: true } + } + + const quota = config.categoryQuotas[category] + if (!quota) { + return { canSubmit: true } + } + + const submittedCount = await prisma.project.count({ + where: { + competitionId, + competitionCategory: category, + isDraft: false, // Don't count drafts + } + }) + + if (submittedCount >= quota) { + if (config.quotaOverflowPolicy === 'waitlist') { + return { + canSubmit: true, + reason: `Quota full (${submittedCount}/${quota}). You're on the waitlist.` + } + } else { + return { + canSubmit: false, + reason: `Quota full (${submittedCount}/${quota}). No more ${category} applications accepted.` + } + } + } + + return { canSubmit: true } +} +``` + +### Quota Dashboard for Admins + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Category Quota Status │ +│ ══════════════════════════════════════════════════════ │ +│ │ +│ Startups │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 68 / 100 submissions │ │ +│ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░ 68% │ │ +│ │ │ │ +│ │ 32 slots remaining │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Business Concepts │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 55 / 100 submissions │ │ +│ │ ▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░ 55% │ │ +│ │ │ │ +│ │ 45 slots remaining │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Waitlist (if quota full) │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Startups: 0 on waitlist │ │ +│ │ Concepts: 0 on waitlist │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Overflow Handling + +**Reject Policy:** +- Form shows error: "Category quota reached. No more startups/concepts accepted." +- User cannot submit +- Draft is saved but cannot be finalized + +**Waitlist Policy:** +- Submission accepted, but `Project.status = WAITLISTED` (new status) +- User sees message: "You're on the waitlist (position #12). We'll notify you if a slot opens." +- If someone withdraws, next waitlist entry promoted to SUBMITTED + +--- + +## 11. Email Notifications + +### Receipt Confirmation Email + +**Trigger:** `autoConfirmReceipt: true` + project submitted + +**Template:** +``` +Subject: Application Received — MOPC 2026 + +Dear Sarah Johnson, + +Thank you for submitting your application to the Monaco Ocean Protection Challenge 2026. + +Application Details: +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Project: Ocean Plastic Recycling Platform +Team: PlastiClean Solutions +Category: Business Concept +Confirmation #: MOPC-2026-00123 +Submitted: February 15, 2026 at 3:42 PM UTC + +What's Next? +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +1. AI Screening: March 2-5, 2026 + Your application will be automatically screened for eligibility. + +2. Jury Evaluation: March 10-31, 2026 + Expert judges will review eligible projects. + +3. Semi-finalist Notification: April 5, 2026 + Selected teams will be invited to the next round. + +Track Your Progress: +View your application status anytime at: +https://monaco-opc.com/applicant/dashboard + +Questions? +Contact us at admin@monaco-opc.com + +Best regards, +MOPC Team +``` + +### Deadline Reminder Emails + +**Trigger:** Configured days before deadline (e.g., [7, 3, 1]) + +**7-Day Reminder:** +``` +Subject: MOPC 2026 Application Deadline — 7 Days Remaining + +Dear Applicant, + +This is a friendly reminder that the MOPC 2026 application deadline is approaching. + +Deadline: March 1, 2026 at 11:59 PM UTC +Time Remaining: 7 days + +Have you started your application? +☐ Draft saved +☐ Documents uploaded +☐ Final submission + +Complete your application: +https://monaco-opc.com/apply/mopc-2026 + +Need help? Contact admin@monaco-opc.com + +Best regards, +MOPC Team +``` + +**1-Day Reminder:** +``` +Subject: ⏰ MOPC 2026 Application Deadline — Tomorrow! + +Dear Applicant, + +The MOPC 2026 application deadline is tomorrow! + +Deadline: March 1, 2026 at 11:59 PM UTC +Time Remaining: 23 hours 17 minutes + +Don't miss out! Complete your application now: +https://monaco-opc.com/apply/mopc-2026 + +Best regards, +MOPC Team +``` + +--- + +## 12. API Changes (tRPC Procedures) + +### New/Modified Procedures + +All procedures are in `src/server/routers/` with these key changes: + +**applicant.getSubmissionBySlug** — Get intake round info by slug (for public access) +**applicant.getMySubmission** (enhanced) — Get current user's application (draft or submitted) +**applicant.saveDraft** (new) — Auto-save form data as draft +**applicant.submitApplication** (new) — Finalize draft and mark as submitted +**file.getUploadUrl** (enhanced) — Get pre-signed URL for file upload +**file.confirmUpload** (new) — Mark file upload as complete after successful S3 upload +**admin.getIntakeSubmissions** — Admin dashboard for intake round +**admin.extendDeadline** (new) — Create grace period for specific applicant + +--- + +## 13. Service Functions + +Key service functions in `src/server/services/intake-round.ts`: + +- `canSubmitToIntakeRound()` — Check if submission window is accepting +- `checkCategoryQuota()` — Validate category quota +- `validateApplicationData()` — Form validation +- `validateFileUpload()` — File requirement validation +- `checkRequiredFiles()` — Verify all required files uploaded + +--- + +## 14. Edge Cases + +| Edge Case | Behavior | Solution | +|-----------|----------|----------| +| **User starts draft, deadline passes** | Draft is preserved but cannot submit | Show banner: "Deadline passed. Contact admin if you need extension." Admin can grant GracePeriod. | +| **User submits at exact deadline second** | Accept if server time <= windowCloseAt | Use database server time for consistency | +| **Category quota reached mid-submission** | Check quota again on final submit | Race condition: if quota hit between form start and submit, show error "Quota just filled" | +| **File upload fails mid-submission** | ProjectFile record exists but no S3 object | Cleanup orphaned records via cron job; allow re-upload | +| **User replaces file after deadline** | Check deadline on upload, not just submit | Each file upload checks `canSubmitToWindow()` | +| **Team member email already registered** | Invite sent, user can claim | Email contains link: "Join team or login to existing account" | +| **Applicant deletes draft** | Hard delete or soft delete? | Soft delete: set `deletedAt` field, hide from UI but keep for audit | +| **Admin extends deadline globally** | Update Round.windowCloseAt | All applicants benefit; no GracePeriod records needed | +| **Duplicate submissions (same email)** | One email = one project per competition | Upsert logic: update existing project instead of creating new | +| **File version conflict** | User uploads same requirement twice | Create new ProjectFile, link to old via `replacedById` | +| **Draft expires while user editing** | Auto-save fails with "Draft expired" | Extend expiry on each auto-save (rolling window) | + +--- + +## 15. Integration Points + +### Connects to Filtering Round (Next Round) + +When intake round closes: + +1. Create ProjectRoundState records +2. Trigger filtering job + +### File System (MinIO) + +- All uploads go to MinIO bucket: `mopc-submissions` +- Object keys: `projects/{projectId}/submissions/{submissionWindowId}/{filename}_{timestamp}.{ext}` +- Pre-signed URLs expire after 1 hour (uploads) or 24 hours (downloads) + +### Notification System + +**Events emitted:** +- `INTAKE_SUBMISSION_RECEIVED` — confirmation email + in-app notification +- `INTAKE_DEADLINE_APPROACHING` — reminder emails (7d, 3d, 1d before) +- `INTAKE_LATE_SUBMISSION` — flag for admin review +- `INTAKE_QUOTA_REACHED` — notify admins + +### Audit Logging + +All actions logged in `DecisionAuditLog`: +- `intake.draft_saved` — auto-save triggered +- `intake.submission_finalized` — final submit +- `intake.file_uploaded` — file added +- `intake.file_replaced` — file updated +- `intake.deadline_extended` — admin override +- `intake.quota_reached` — category quota hit + +--- + +## Document Complete + +This specification defines the **INTAKE round type** for the redesigned MOPC architecture. Key takeaways: + +1. **Typed Config**: IntakeConfig replaces generic JSON with validated, documented fields +2. **SubmissionWindow**: Decouples file requirements from round, enables multi-round submissions +3. **Deadline Policies**: HARD, FLAG, GRACE with clear behavior differences +4. **Draft System**: Auto-save + expiry for incomplete applications +5. **Category Quotas**: Limit startups/concepts with overflow handling +6. **Email Automation**: Confirmation + reminders built-in +7. **Admin Controls**: Dashboard, deadline extensions, quota monitoring + +**Next documents:** +- 05-round-filtering.md — AI screening and eligibility +- 06-round-evaluation.md — Jury review with multi-jury support +- 07-round-submission.md — Additional docs from advancing teams diff --git a/docs/claude-architecture-redesign/05-round-filtering.md b/docs/claude-architecture-redesign/05-round-filtering.md new file mode 100644 index 0000000..5ed59cb --- /dev/null +++ b/docs/claude-architecture-redesign/05-round-filtering.md @@ -0,0 +1,1438 @@ +# Round Type: FILTERING — AI Screening & Eligibility + +## Overview + +The **FILTERING** round type (Round 2 in typical flow) performs automated screening of applications to identify eligible projects, detect duplicates, and flag edge cases for admin review. It replaces the current `FILTER` stage with enhanced features: rule-based filtering, AI-powered screening, duplicate detection, and a manual override system. + +### Purpose + +1. **Automated Eligibility Checks** — Field-based rules (age, category, country, etc.) and document checks (required files) +2. **AI Screening** — GPT-powered rubric evaluation with confidence banding +3. **Duplicate Detection** — Cross-application similarity checking to catch multiple submissions from same applicant +4. **Manual Review Queue** — Flagged projects go to admin dashboard for final decision +5. **Admin Override** — Any automated decision can be manually reversed with audit trail + +### Key Features + +| Feature | Description | +|---------|-------------| +| **Multi-Rule Engine** | Field-based, document-check, and AI rules run in sequence | +| **Confidence Banding** | AI results split into auto-pass (high), manual-review (medium), auto-reject (low) | +| **Duplicate Detection** | Built-in email-based duplicate check (always flags for review) | +| **Manual Override** | Admin can approve/reject any flagged project with reason | +| **Batch Processing** | AI screening runs in configurable batches for performance | +| **Progress Tracking** | FilteringJob model tracks long-running jobs | +| **Audit Trail** | All decisions logged in DecisionAuditLog | + +--- + +## Current System + +### Stage Model + +```prisma +model Stage { + id String @id + trackId String + stageType StageType // FILTER + name String + slug String + status StageStatus + sortOrder Int + configJson Json? // Generic blob — hard to know what's configurable + windowOpenAt DateTime? + windowCloseAt DateTime? + + filteringRules FilteringRule[] + filteringResults FilteringResult[] + filteringJobs FilteringJob[] +} + +enum StageType { + INTAKE + FILTER // <-- Current filtering stage + EVALUATION + SELECTION + LIVE_FINAL + RESULTS +} +``` + +### FilteringRule Model + +```prisma +model FilteringRule { + id String @id + stageId String + name String + ruleType FilteringRuleType + configJson Json @db.JsonB // Type-specific config + priority Int @default(0) + isActive Boolean @default(true) + + stage Stage @relation(fields: [stageId], references: [id], onDelete: Cascade) +} + +enum FilteringRuleType { + FIELD_BASED // Field checks (category, country, age, etc.) + DOCUMENT_CHECK // File existence/type checks + AI_SCREENING // GPT rubric evaluation +} +``` + +**Rule configJson shapes:** + +```typescript +// FIELD_BASED +{ + conditions: [ + { field: "competitionCategory", operator: "equals", value: "STARTUP" }, + { field: "foundedAt", operator: "older_than_years", value: 5 } + ], + logic: "AND" | "OR", + action: "PASS" | "REJECT" | "FLAG" +} + +// DOCUMENT_CHECK +{ + requiredFileTypes: ["pdf", "docx"], + minFileCount: 2, + action: "FLAG" +} + +// AI_SCREENING +{ + criteriaText: "Project must demonstrate clear ocean conservation impact", + action: "FLAG", + batchSize: 20, + parallelBatches: 1 +} +``` + +### FilteringResult Model + +```prisma +model FilteringResult { + id String @id + stageId String + projectId String + outcome FilteringOutcome // PASSED | FILTERED_OUT | FLAGGED + ruleResultsJson Json? @db.JsonB // Per-rule results + aiScreeningJson Json? @db.JsonB // AI screening details + + // Admin override + overriddenBy String? + overriddenAt DateTime? + overrideReason String? @db.Text + finalOutcome FilteringOutcome? + + stage Stage @relation(fields: [stageId], references: [id]) + project Project @relation(fields: [projectId], references: [id]) + overriddenByUser User? @relation("FilteringOverriddenBy", fields: [overriddenBy], references: [id]) + + @@unique([stageId, projectId]) +} + +enum FilteringOutcome { + PASSED // Auto-advance to next round + FILTERED_OUT // Auto-reject + FLAGGED // Manual review required +} +``` + +### FilteringJob Model + +```prisma +model FilteringJob { + id String @id + stageId String + status FilteringJobStatus @default(PENDING) + totalProjects Int @default(0) + totalBatches Int @default(0) + currentBatch Int @default(0) + processedCount Int @default(0) + passedCount Int @default(0) + filteredCount Int @default(0) + flaggedCount Int @default(0) + errorMessage String? @db.Text + startedAt DateTime? + completedAt DateTime? + + stage Stage @relation(fields: [stageId], references: [id]) +} + +enum FilteringJobStatus { + PENDING + RUNNING + COMPLETED + FAILED +} +``` + +### AI Screening Flow + +```typescript +// src/server/services/ai-filtering.ts +export async function executeAIScreening( + config: AIScreeningConfig, + projects: ProjectForFiltering[], + userId?: string, + entityId?: string, + onProgress?: ProgressCallback +): Promise> +``` + +**AI Screening Steps:** + +1. **Anonymization** — Strip PII before sending to OpenAI (see `anonymization.ts`) +2. **Batch Processing** — Group projects into configurable batch sizes (default 20) +3. **GPT Evaluation** — Send to OpenAI with rubric criteria +4. **Result Parsing** — Parse JSON response with confidence scores +5. **Confidence Banding** — Split into auto-pass/manual-review/auto-reject buckets +6. **Logging** — Track token usage in AIUsageLog + +**Confidence Thresholds:** + +```typescript +const AI_CONFIDENCE_THRESHOLD_PASS = 0.75 // Auto-pass if ≥ 0.75 and meetsAllCriteria +const AI_CONFIDENCE_THRESHOLD_REJECT = 0.25 // Auto-reject if ≤ 0.25 and !meetsAllCriteria +// Between 0.25-0.75 → FLAGGED for manual review +``` + +### Duplicate Detection + +```typescript +// Current implementation in stage-filtering.ts (lines 264-289) +// Groups projects by submittedByEmail to detect duplicates +// Duplicates are ALWAYS flagged (never auto-rejected) + +const duplicateProjectIds = new Set() +const emailToProjects = new Map>() + +for (const project of projects) { + const email = (project.submittedByEmail ?? '').toLowerCase().trim() + if (!email) continue + if (!emailToProjects.has(email)) emailToProjects.set(email, []) + emailToProjects.get(email)!.push({ id: project.id, title: project.title }) +} + +// If any email has > 1 project, all siblings are flagged +emailToProjects.forEach((group, _email) => { + if (group.length <= 1) return + for (const p of group) { + duplicateProjectIds.add(p.id) + } +}) +``` + +**Duplicate Metadata Stored:** + +```json +{ + "isDuplicate": true, + "siblingProjectIds": ["proj-2", "proj-3"], + "duplicateNote": "This project shares a submitter email with 2 other project(s)." +} +``` + +### Filtering Execution Flow + +```typescript +// src/server/services/stage-filtering.ts +export async function runStageFiltering( + stageId: string, + actorId: string, + prisma: PrismaClient +): Promise +``` + +**Execution Steps:** + +1. Load all projects in PENDING/IN_PROGRESS state for this stage +2. Create FilteringJob for progress tracking +3. Load active FilteringRule records (ordered by priority) +4. **Run duplicate detection** (built-in, always runs first) +5. **Run deterministic rules** (FIELD_BASED, DOCUMENT_CHECK) + - If any REJECT rule fails → outcome = FILTERED_OUT + - If any FLAG rule fails → outcome = FLAGGED +6. **Run AI screening** (if enabled and deterministic passed OR if duplicate) + - Batch process with configurable size + - Band by confidence + - Attach duplicate metadata +7. **Save FilteringResult** for each project +8. Update FilteringJob counts (passed/rejected/flagged) +9. Log decision audit + +--- + +## Redesigned Filtering Round + +### Round Model Changes + +```prisma +model Round { + id String @id @default(cuid()) + competitionId String + name String // "AI Screening & Eligibility Check" + slug String // "filtering" + roundType RoundType // FILTERING (renamed from FILTER) + status RoundStatus @default(ROUND_DRAFT) + sortOrder Int @default(0) + + // Time windows + windowOpenAt DateTime? + windowCloseAt DateTime? + + // Round-type-specific configuration (validated by Zod) + configJson Json? @db.JsonB + + // Relations + competition Competition @relation(fields: [competitionId], references: [id]) + projectRoundStates ProjectRoundState[] + filteringRules FilteringRule[] + filteringResults FilteringResult[] + filteringJobs FilteringJob[] + advancementRules AdvancementRule[] +} + +enum RoundType { + INTAKE + FILTERING // Renamed from FILTER for clarity + EVALUATION + SUBMISSION // New: multi-round submissions + MENTORING // New: mentor workspace + LIVE_FINAL + CONFIRMATION // New: winner agreement +} +``` + +### FilteringConfig Type (Zod-Validated) + +```typescript +// src/types/round-configs.ts +export type FilteringConfig = { + // Rule engine + rules: FilterRuleDef[] // Configured rules (can be empty to skip deterministic filtering) + + // AI screening + aiScreeningEnabled: boolean + aiRubricPrompt: string // Custom rubric for AI (plain-language criteria) + aiConfidenceThresholds: { + high: number // Above this = auto-pass (default: 0.85) + medium: number // Above this = flag for review (default: 0.6) + low: number // Below this = auto-reject (default: 0.4) + } + aiBatchSize: number // Projects per AI batch (default: 20, max: 50) + aiParallelBatches: number // Concurrent batches (default: 1, max: 10) + + // Duplicate detection + duplicateDetectionEnabled: boolean + duplicateThreshold: number // Email similarity threshold (0-1, default: 1.0 = exact match) + duplicateAction: 'FLAG' | 'AUTO_REJECT' // Default: FLAG (always recommend FLAG) + + // Advancement behavior + autoAdvancePassingProjects: boolean // Auto-advance PASSED projects to next round + manualReviewRequired: boolean // All results require admin approval before advance + + // Eligibility criteria (structured) + eligibilityCriteria: EligibilityCriteria[] + + // Category-specific rules + categorySpecificRules: { + STARTUP?: CategoryRuleSet + BUSINESS_CONCEPT?: CategoryRuleSet + } +} + +export type FilterRuleDef = { + id?: string // Optional — for editing existing rules + name: string + ruleType: 'FIELD_CHECK' | 'DOCUMENT_CHECK' | 'AI_SCORE' | 'DUPLICATE' | 'CUSTOM' + config: FilterRuleConfig + priority: number // Lower = run first + isActive: boolean + action: 'PASS' | 'REJECT' | 'FLAG' +} + +export type FilterRuleConfig = + | FieldCheckConfig + | DocumentCheckConfig + | AIScoreConfig + | CustomConfig + +export type FieldCheckConfig = { + conditions: FieldCondition[] + logic: 'AND' | 'OR' +} + +export type FieldCondition = { + field: 'competitionCategory' | 'foundedAt' | 'country' | 'geographicZone' | 'tags' | 'oceanIssue' | 'wantsMentorship' | 'institution' + operator: 'equals' | 'not_equals' | 'contains' | 'in' | 'not_in' | 'is_empty' | 'greater_than' | 'less_than' | 'older_than_years' | 'newer_than_years' + value: string | number | string[] | boolean +} + +export type DocumentCheckConfig = { + requiredFileTypes?: string[] // e.g., ['pdf', 'docx'] + minFileCount?: number + maxFileCount?: number + minTotalSizeMB?: number + maxTotalSizeMB?: number +} + +export type AIScoreConfig = { + criteriaText: string // Plain-language rubric + minScore: number // Minimum AI score to pass (0-10) + weightInOverall: number // Weight if combining multiple AI rules (0-1) +} + +export type CustomConfig = { + // For future extension — custom JS/Python evaluation + scriptUrl?: string + functionName?: string + parameters?: Record +} + +export type EligibilityCriteria = { + name: string + description: string + required: boolean + checkType: 'field' | 'document' | 'ai' | 'custom' + checkConfig: FilterRuleConfig +} + +export type CategoryRuleSet = { + minAge?: number // Years since founded + maxAge?: number + requiredTags?: string[] + excludedCountries?: string[] + requiredDocuments?: string[] +} +``` + +### Zod Schema for FilteringConfig + +```typescript +// src/lib/round-config-schemas.ts +import { z } from 'zod' + +export const FieldConditionSchema = z.object({ + field: z.enum([ + 'competitionCategory', + 'foundedAt', + 'country', + 'geographicZone', + 'tags', + 'oceanIssue', + 'wantsMentorship', + 'institution' + ]), + operator: z.enum([ + 'equals', + 'not_equals', + 'contains', + 'in', + 'not_in', + 'is_empty', + 'greater_than', + 'less_than', + 'older_than_years', + 'newer_than_years' + ]), + value: z.union([ + z.string(), + z.number(), + z.array(z.string()), + z.boolean() + ]) +}) + +export const FieldCheckConfigSchema = z.object({ + conditions: z.array(FieldConditionSchema), + logic: z.enum(['AND', 'OR']) +}) + +export const DocumentCheckConfigSchema = z.object({ + requiredFileTypes: z.array(z.string()).optional(), + minFileCount: z.number().int().min(0).optional(), + maxFileCount: z.number().int().min(0).optional(), + minTotalSizeMB: z.number().min(0).optional(), + maxTotalSizeMB: z.number().min(0).optional() +}) + +export const AIScoreConfigSchema = z.object({ + criteriaText: z.string().min(10).max(5000), + minScore: z.number().min(0).max(10), + weightInOverall: z.number().min(0).max(1).default(1.0) +}) + +export const CustomConfigSchema = z.object({ + scriptUrl: z.string().url().optional(), + functionName: z.string().optional(), + parameters: z.record(z.unknown()).optional() +}) + +export const FilterRuleDefSchema = z.object({ + id: z.string().optional(), + name: z.string().min(1).max(255), + ruleType: z.enum(['FIELD_CHECK', 'DOCUMENT_CHECK', 'AI_SCORE', 'DUPLICATE', 'CUSTOM']), + config: z.union([ + FieldCheckConfigSchema, + DocumentCheckConfigSchema, + AIScoreConfigSchema, + CustomConfigSchema + ]), + priority: z.number().int().min(0).default(0), + isActive: z.boolean().default(true), + action: z.enum(['PASS', 'REJECT', 'FLAG']) +}) + +export const CategoryRuleSetSchema = z.object({ + minAge: z.number().int().min(0).optional(), + maxAge: z.number().int().min(0).optional(), + requiredTags: z.array(z.string()).optional(), + excludedCountries: z.array(z.string()).optional(), + requiredDocuments: z.array(z.string()).optional() +}) + +export const FilteringConfigSchema = z.object({ + rules: z.array(FilterRuleDefSchema).default([]), + + aiScreeningEnabled: z.boolean().default(false), + aiRubricPrompt: z.string().min(0).max(10000).default(''), + aiConfidenceThresholds: z.object({ + high: z.number().min(0).max(1).default(0.85), + medium: z.number().min(0).max(1).default(0.6), + low: z.number().min(0).max(1).default(0.4) + }).default({ high: 0.85, medium: 0.6, low: 0.4 }), + aiBatchSize: z.number().int().min(1).max(50).default(20), + aiParallelBatches: z.number().int().min(1).max(10).default(1), + + duplicateDetectionEnabled: z.boolean().default(true), + duplicateThreshold: z.number().min(0).max(1).default(1.0), + duplicateAction: z.enum(['FLAG', 'AUTO_REJECT']).default('FLAG'), + + autoAdvancePassingProjects: z.boolean().default(false), + manualReviewRequired: z.boolean().default(true), + + eligibilityCriteria: z.array(z.object({ + name: z.string(), + description: z.string(), + required: z.boolean(), + checkType: z.enum(['field', 'document', 'ai', 'custom']), + checkConfig: z.union([ + FieldCheckConfigSchema, + DocumentCheckConfigSchema, + AIScoreConfigSchema, + CustomConfigSchema + ]) + })).default([]), + + categorySpecificRules: z.object({ + STARTUP: CategoryRuleSetSchema.optional(), + BUSINESS_CONCEPT: CategoryRuleSetSchema.optional() + }).default({}) +}) + +export type FilteringConfig = z.infer +``` + +--- + +## Filtering Rule Engine + +### Rule Evaluation Order + +``` +1. Built-in Duplicate Detection (if enabled) + ↓ +2. FIELD_CHECK rules (sorted by priority ascending) + ↓ +3. DOCUMENT_CHECK rules (sorted by priority ascending) + ↓ +4. AI_SCORE rules (if aiScreeningEnabled) — batch processed + ↓ +5. CUSTOM rules (future extension) + ↓ +6. Determine final outcome: PASSED | FILTERED_OUT | FLAGGED +``` + +### Rule Types in Detail + +#### 1. FIELD_CHECK + +**Purpose:** Validate project metadata fields against conditions. + +**Operators:** + +| Operator | Description | Example | +|----------|-------------|---------| +| `equals` | Field equals value | `competitionCategory equals "STARTUP"` | +| `not_equals` | Field does not equal value | `country not_equals "France"` | +| `contains` | Field contains substring (case-insensitive) | `tags contains "conservation"` | +| `in` | Field value is in array | `country in ["Monaco", "France", "Italy"]` | +| `not_in` | Field value not in array | `oceanIssue not_in ["OTHER"]` | +| `is_empty` | Field is null, empty string, or empty array | `institution is_empty` | +| `greater_than` | Numeric comparison | `teamMemberCount greater_than 2` | +| `less_than` | Numeric comparison | `fundingGoal less_than 100000` | +| `older_than_years` | Date comparison (foundedAt) | `foundedAt older_than_years 5` | +| `newer_than_years` | Date comparison (foundedAt) | `foundedAt newer_than_years 2` | + +**Example Rule:** + +```json +{ + "name": "Startups Must Be < 5 Years Old", + "ruleType": "FIELD_CHECK", + "config": { + "conditions": [ + { "field": "competitionCategory", "operator": "equals", "value": "STARTUP" }, + { "field": "foundedAt", "operator": "newer_than_years", "value": 5 } + ], + "logic": "AND" + }, + "priority": 10, + "isActive": true, + "action": "REJECT" +} +``` + +**Logic:** +- `AND`: All conditions must be true +- `OR`: At least one condition must be true + +**Action:** +- `PASS`: If conditions met, mark as passed (continue to next rule) +- `REJECT`: If conditions met, auto-reject (short-circuit) +- `FLAG`: If conditions met, flag for manual review + +#### 2. DOCUMENT_CHECK + +**Purpose:** Verify file uploads meet requirements. + +**Checks:** + +```typescript +type DocumentCheckConfig = { + requiredFileTypes?: string[] // e.g., ['pdf', 'docx'] — must have at least one of each + minFileCount?: number // Minimum number of files + maxFileCount?: number // Maximum number of files + minTotalSizeMB?: number // Minimum total upload size + maxTotalSizeMB?: number // Maximum total upload size +} +``` + +**Example Rule:** + +```json +{ + "name": "Must Upload Executive Summary + Business Plan", + "ruleType": "DOCUMENT_CHECK", + "config": { + "requiredFileTypes": ["pdf"], + "minFileCount": 2 + }, + "priority": 20, + "isActive": true, + "action": "FLAG" +} +``` + +#### 3. AI_SCORE + +**Purpose:** GPT-powered rubric evaluation. + +**Config:** + +```typescript +type AIScoreConfig = { + criteriaText: string // Plain-language rubric + minScore: number // Minimum score to pass (0-10) + weightInOverall: number // Weight if combining multiple AI rules +} +``` + +**Example Rule:** + +```json +{ + "name": "AI: Ocean Impact Assessment", + "ruleType": "AI_SCORE", + "config": { + "criteriaText": "Project must demonstrate measurable ocean conservation impact with clear metrics and realistic timeline. Reject spam or unrelated projects.", + "minScore": 6.0, + "weightInOverall": 1.0 + }, + "priority": 30, + "isActive": true, + "action": "FLAG" +} +``` + +**AI Evaluation Flow:** + +1. Anonymize project data (strip PII) +2. Batch projects (configurable batch size) +3. Send to OpenAI with rubric +4. Parse response: + ```json + { + "projects": [ + { + "project_id": "anon-123", + "meets_criteria": true, + "confidence": 0.82, + "reasoning": "Clear ocean conservation focus, realistic metrics", + "quality_score": 7, + "spam_risk": false + } + ] + } + ``` +5. Band by confidence thresholds +6. Store in `aiScreeningJson` on FilteringResult + +#### 4. DUPLICATE + +**Purpose:** Detect multiple submissions from same applicant. + +**Built-in Rule:** +- Always runs first if `duplicateDetectionEnabled: true` +- Groups projects by `submittedByEmail` +- Flags all projects in duplicate groups +- Never auto-rejects duplicates (admin must decide which to keep) + +**Duplicate Metadata:** + +```json +{ + "isDuplicate": true, + "siblingProjectIds": ["proj-2", "proj-3"], + "duplicateNote": "This project shares a submitter email with 2 other project(s). Admin must review and decide which to keep.", + "similarityScore": 1.0 +} +``` + +**Future Enhancement: Semantic Similarity** + +```typescript +duplicateThreshold: number // 0-1 (e.g., 0.8 = 80% similar text triggers duplicate flag) +``` + +Use text embeddings to detect duplicates beyond exact email match (compare titles, descriptions). + +#### 5. CUSTOM (Future Extension) + +**Purpose:** Run custom evaluation scripts (JS/Python). + +**Config:** + +```typescript +type CustomConfig = { + scriptUrl?: string // URL to hosted script + functionName?: string // Function to call + parameters?: Record +} +``` + +**Example Use Case:** +- External API call to verify company registration +- Custom formula combining multiple fields +- Integration with third-party data sources + +--- + +## Rule Combination Logic + +### How Rules Are Combined + +```typescript +// Pseudocode for rule evaluation +let finalOutcome: 'PASSED' | 'FILTERED_OUT' | 'FLAGGED' = 'PASSED' +let hasFailed = false +let hasFlagged = false + +// Run rules in priority order +for (const rule of rules.sort((a, b) => a.priority - b.priority)) { + const result = evaluateRule(rule, project) + + if (!result.passed) { + if (rule.action === 'REJECT') { + hasFailed = true + break // Short-circuit — no need to run remaining rules + } else if (rule.action === 'FLAG') { + hasFlagged = true + // Continue to next rule + } + } +} + +// Determine final outcome +if (hasFailed) { + finalOutcome = 'FILTERED_OUT' +} else if (hasFlagged) { + finalOutcome = 'FLAGGED' +} else { + finalOutcome = 'PASSED' +} + +// Override: Duplicates always flagged (never auto-rejected) +if (isDuplicate && finalOutcome === 'FILTERED_OUT') { + finalOutcome = 'FLAGGED' +} +``` + +### Weighted Scoring (Advanced) + +For multiple AI rules or field checks, admins can configure weighted scoring: + +```typescript +type WeightedScoringConfig = { + enabled: boolean + rules: Array<{ + ruleId: string + weight: number // 0-1 + }> + passingThreshold: number // Combined weighted score needed to pass (0-10) +} +``` + +**Example:** + +```json +{ + "enabled": true, + "rules": [ + { "ruleId": "ai-ocean-impact", "weight": 0.6 }, + { "ruleId": "ai-innovation-score", "weight": 0.4 } + ], + "passingThreshold": 7.0 +} +``` + +Combined score = (7.5 × 0.6) + (8.0 × 0.4) = 4.5 + 3.2 = 7.7 → PASSED + +--- + +## AI Screening Pipeline + +### Step-by-Step Flow + +``` +1. Load Projects + ↓ +2. Anonymize Data (strip PII) + ↓ +3. Batch Projects (configurable size: 1-50, default 20) + ↓ +4. Parallel Processing (configurable: 1-10 concurrent batches) + ↓ +5. OpenAI API Call (GPT-4o or configured model) + ↓ +6. Parse JSON Response + ↓ +7. Map Anonymous IDs → Real Project IDs + ↓ +8. Band by Confidence Threshold + ↓ +9. Store Results in FilteringResult + ↓ +10. Log Token Usage (AIUsageLog) +``` + +### Anonymization + +```typescript +// src/server/services/anonymization.ts +export function anonymizeProjectsForAI( + projects: ProjectWithRelations[], + purpose: 'FILTERING' | 'ASSIGNMENT' | 'SUMMARY' +): { anonymized: AnonymizedProjectForAI[]; mappings: ProjectAIMapping[] } +``` + +**What's Stripped:** +- Team member names +- Submitter email +- Submitter name +- Personal identifiers in metadata +- File paths (only file types retained) + +**What's Kept:** +- Project title (if generic) +- Description +- Category (STARTUP/BUSINESS_CONCEPT) +- Country +- Tags +- Ocean issue +- Founded date (year only) + +**Validation:** + +```typescript +export function validateAnonymizedProjects( + anonymized: AnonymizedProjectForAI[] +): boolean +``` + +Checks for PII patterns: +- Email addresses (`/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i`) +- Phone numbers +- Full names (heuristic) +- URLs with query params + +**GDPR Compliance:** +- All AI calls must pass `validateAnonymizedProjects()` check +- Fails if PII detected → throws error, logs, flags all projects for manual review + +### OpenAI Prompt Structure + +**System Prompt:** + +``` +Project screening assistant. Evaluate against criteria, return JSON. +Format: {"projects": [{project_id, meets_criteria: bool, confidence: 0-1, reasoning: str, quality_score: 1-10, spam_risk: bool}]} +Be objective. Base evaluation only on provided data. No personal identifiers in reasoning. +``` + +**User Prompt:** + +``` +CRITERIA: {aiRubricPrompt} +PROJECTS: [{project_id, title, description, category, tags, ...}] +Evaluate and return JSON. +``` + +**Response Format:** + +```json +{ + "projects": [ + { + "project_id": "anon-001", + "meets_criteria": true, + "confidence": 0.82, + "reasoning": "Clear ocean conservation focus with measurable impact metrics. Realistic timeline. Strong innovation.", + "quality_score": 8, + "spam_risk": false + }, + { + "project_id": "anon-002", + "meets_criteria": false, + "confidence": 0.91, + "reasoning": "Generic description, no specific ocean impact. Appears to be spam or off-topic.", + "quality_score": 2, + "spam_risk": true + } + ] +} +``` + +### Confidence Banding + +```typescript +function bandByConfidence( + aiScreeningData: { confidence: number; meetsAllCriteria: boolean } +): { outcome: 'PASSED' | 'FILTERED_OUT' | 'FLAGGED'; confidence: number } +``` + +**Default Thresholds:** + +| Confidence | Meets Criteria | Outcome | Action | +|------------|----------------|---------|--------| +| ≥ 0.85 | true | PASSED | Auto-advance | +| 0.60-0.84 | true | FLAGGED | Manual review | +| 0.40-0.59 | any | FLAGGED | Manual review | +| ≤ 0.39 | false | FILTERED_OUT | Auto-reject | + +**Admin Override:** + +Admins can customize thresholds in `FilteringConfig.aiConfidenceThresholds`. + +--- + +## Duplicate Detection + +### Current Implementation + +```typescript +// Built-in email-based duplicate detection +const emailToProjects = new Map>() + +for (const project of projects) { + const email = (project.submittedByEmail ?? '').toLowerCase().trim() + if (!email) continue + if (!emailToProjects.has(email)) emailToProjects.set(email, []) + emailToProjects.get(email)!.push({ id: project.id, title: project.title }) +} + +// Flag all projects in groups of size > 1 +emailToProjects.forEach((group) => { + if (group.length <= 1) return + for (const p of group) { + duplicateProjectIds.add(p.id) + } +}) +``` + +### Enhanced Detection (Future) + +**Text Similarity:** + +```typescript +import { cosineSimilarity } from '@/lib/text-similarity' + +function detectDuplicatesByText( + projects: Project[], + threshold: number = 0.8 +): Set +``` + +**Algorithm:** +1. Generate text embeddings for title + description +2. Compute pairwise cosine similarity +3. Flag projects with similarity ≥ threshold +4. Group into duplicate clusters + +**Example:** + +Project A: "Ocean cleanup robot using AI" +Project B: "AI-powered ocean cleaning robot" +Similarity: 0.92 → Flagged as duplicates + +### Duplicate Metadata + +```json +{ + "isDuplicate": true, + "siblingProjectIds": ["proj-2", "proj-3"], + "duplicateNote": "This project shares a submitter email with 2 other project(s). Admin must review and decide which to keep.", + "similarityScore": 1.0, + "detectionMethod": "email" | "text_similarity" +} +``` + +### Admin Duplicate Review UI + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Duplicate Group: applicant@example.com │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Project 1: "Ocean Cleanup Robot" │ │ +│ │ Submitted: 2026-02-01 10:30 AM │ │ +│ │ Category: STARTUP │ │ +│ │ AI Score: 7.5/10 │ │ +│ │ │ │ +│ │ [✓ Keep This] [✗ Reject] [View Details] │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Project 2: "AI-Powered Ocean Cleaner" │ │ +│ │ Submitted: 2026-02-05 2:15 PM │ │ +│ │ Category: STARTUP │ │ +│ │ AI Score: 6.8/10 │ │ +│ │ │ │ +│ │ [✓ Keep This] [✗ Reject] [View Details] │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ Recommendation: Keep Project 1 (higher AI score, earlier │ +│ submission) │ +│ │ +│ [Approve Recommendation] [Manual Decision] │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Admin Experience + +### Filtering Dashboard + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ Round 2: AI Screening & Eligibility Check │ +│ │ +│ Status: Completed ● Last Run: 2026-02-10 3:45 PM │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Results Summary │ │ +│ │ │ │ +│ │ ✓ Passed: 142 projects (auto-advance enabled) │ │ +│ │ ✗ Filtered Out: 28 projects │ │ +│ │ ⚠ Flagged: 15 projects (manual review required) │ │ +│ │ ──────────────────────────────────────────────────────── │ │ +│ │ Total: 185 projects processed │ │ +│ │ │ │ +│ │ AI Usage: 12,450 tokens ($0.15) │ │ +│ │ Processing Time: 2m 34s │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Manual Review Queue (15) [Sort ▼] │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ ⚠ Ocean Cleanup Initiative │ │ │ +│ │ │ Category: STARTUP │ │ │ +│ │ │ Reason: Duplicate submission (2 projects) │ │ │ +│ │ │ AI Score: 7.2/10 (confidence: 0.65) │ │ │ +│ │ │ │ │ │ +│ │ │ Failed Rules: │ │ │ +│ │ │ • Duplicate Detection: EMAIL_MATCH │ │ │ +│ │ │ │ │ │ +│ │ │ [View Details] [✓ Approve] [✗ Reject] │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ ⚠ Blue Carbon Project │ │ │ +│ │ │ Category: BUSINESS_CONCEPT │ │ │ +│ │ │ Reason: AI confidence medium (0.58) │ │ │ +│ │ │ AI Score: 5.5/10 │ │ │ +│ │ │ │ │ │ +│ │ │ AI Reasoning: "Project description is vague and │ │ │ +│ │ │ lacks specific impact metrics. Needs clarification." │ │ │ +│ │ │ │ │ │ +│ │ │ [View Details] [✓ Approve] [✗ Reject] │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ... 13 more flagged projects │ │ +│ │ │ │ +│ │ [Batch Approve All] [Export Queue] │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ [Re-run Filtering] [Configure Rules] [View Logs] │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### Rule Configuration UI + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ Filtering Rules Configuration │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Active Rules (5) [+ Add Rule] │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ ≡ Rule 1: Startups Must Be < 5 Years Old │ │ │ +│ │ │ Type: FIELD_CHECK │ │ │ +│ │ │ Action: REJECT │ │ │ +│ │ │ Priority: 10 [Edit] [✗] │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ ≡ Rule 2: Must Upload Executive Summary │ │ │ +│ │ │ Type: DOCUMENT_CHECK │ │ │ +│ │ │ Action: FLAG │ │ │ +│ │ │ Priority: 20 [Edit] [✗] │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ ≡ Rule 3: AI Ocean Impact Assessment │ │ │ +│ │ │ Type: AI_SCORE │ │ │ +│ │ │ Action: FLAG │ │ │ +│ │ │ Priority: 30 [Edit] [✗] │ │ │ +│ │ │ Rubric: "Project must demonstrate measurable..." │ │ │ +│ │ │ Min Score: 6.0/10 │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ... 2 more rules │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ AI Settings │ │ +│ │ │ │ +│ │ AI Screening: [✓ Enabled] │ │ +│ │ Batch Size: [20] projects (1-50) │ │ +│ │ Parallel Batches: [2] (1-10) │ │ +│ │ │ │ +│ │ Confidence Thresholds: │ │ +│ │ High (auto-pass): [0.85] │ │ +│ │ Medium (review): [0.60] │ │ +│ │ Low (auto-reject): [0.40] │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Duplicate Detection │ │ +│ │ │ │ +│ │ Email-based: [✓ Enabled] │ │ +│ │ Text similarity: [ ] Disabled (future) │ │ +│ │ Similarity threshold: [0.80] (0-1) │ │ +│ │ Action on duplicates: [FLAG] (recommended) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ [Save Configuration] [Test Rules] [Cancel] │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### Manual Override Controls + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ Manual Override: Ocean Cleanup Initiative │ +│ │ +│ Current Outcome: ⚠ FLAGGED │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Project Details │ │ +│ │ │ │ +│ │ Title: Ocean Cleanup Initiative │ │ +│ │ Category: STARTUP │ │ +│ │ Submitted: 2026-02-01 10:30 AM │ │ +│ │ Applicant: applicant@example.com │ │ +│ │ │ │ +│ │ Description: [View Full Description] │ │ +│ │ Files: executive-summary.pdf, business-plan.docx │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Filtering Results │ │ +│ │ │ │ +│ │ ✓ Rule 1: Startups < 5 Years Old PASSED │ │ +│ │ ✓ Rule 2: Upload Executive Summary PASSED │ │ +│ │ ✗ Rule 3: Duplicate Detection FLAGGED │ │ +│ │ → Reason: 2 projects from applicant@example.com │ │ +│ │ → Sibling: "AI-Powered Ocean Cleaner" (proj-2) │ │ +│ │ ⚠ Rule 4: AI Ocean Impact FLAGGED │ │ +│ │ → AI Score: 7.2/10 │ │ +│ │ → Confidence: 0.65 (medium) │ │ +│ │ → Reasoning: "Clear ocean focus but needs more specific │ │ +│ │ impact metrics. Potential duplicate." │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Override Decision │ │ +│ │ │ │ +│ │ New Outcome: ○ Approve (PASSED) ○ Reject (FILTERED_OUT) │ │ +│ │ │ │ +│ │ Reason (required): │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ Reviewed duplicate group — this is the stronger │ │ │ +│ │ │ submission. AI score above threshold. Approved to │ │ │ +│ │ │ advance. │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [Submit Override] [Cancel] │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +└───────────────────────────────────────────────────────────────────┘ +``` + +--- + +## API Changes + +### New tRPC Procedures + +```typescript +// src/server/routers/filtering.ts +export const filteringRouter = router({ + // Run filtering for a round + runFiltering: adminProcedure + .input(z.object({ roundId: z.string() })) + .mutation(async ({ ctx, input }) => { + return runStageFiltering(input.roundId, ctx.user.id, ctx.prisma) + }), + + // Get filtering job status + getJob: adminProcedure + .input(z.object({ jobId: z.string() })) + .query(async ({ ctx, input }) => { + return ctx.prisma.filteringJob.findUnique({ + where: { id: input.jobId }, + include: { round: { select: { name: true } } } + }) + }), + + // Get manual review queue + getManualQueue: adminProcedure + .input(z.object({ roundId: z.string() })) + .query(async ({ ctx, input }) => { + return getManualQueue(input.roundId, ctx.prisma) + }), + + // Resolve manual decision + resolveDecision: adminProcedure + .input(z.object({ + filteringResultId: z.string(), + outcome: z.enum(['PASSED', 'FILTERED_OUT']), + reason: z.string().min(10).max(1000) + })) + .mutation(async ({ ctx, input }) => { + return resolveManualDecision( + input.filteringResultId, + input.outcome, + input.reason, + ctx.user.id, + ctx.prisma + ) + }), + + // Batch override + batchResolve: adminProcedure + .input(z.object({ + filteringResultIds: z.array(z.string()), + outcome: z.enum(['PASSED', 'FILTERED_OUT']), + reason: z.string().min(10).max(1000) + })) + .mutation(async ({ ctx, input }) => { + for (const id of input.filteringResultIds) { + await resolveManualDecision(id, input.outcome, input.reason, ctx.user.id, ctx.prisma) + } + }), + + // Export results + exportResults: adminProcedure + .input(z.object({ roundId: z.string() })) + .query(async ({ ctx, input }) => { + // Return CSV-ready data + }), + + // Configure filtering rules + configureRules: adminProcedure + .input(z.object({ + roundId: z.string(), + rules: z.array(FilterRuleDefSchema) + })) + .mutation(async ({ ctx, input }) => { + // Delete existing rules, create new ones + }), + + // Update round config + updateConfig: adminProcedure + .input(z.object({ + roundId: z.string(), + config: FilteringConfigSchema + })) + .mutation(async ({ ctx, input }) => { + await ctx.prisma.round.update({ + where: { id: input.roundId }, + data: { configJson: input.config as any } + }) + }) +}) +``` + +--- + +## Service Functions + +### Core Service Signatures + +```typescript +// src/server/services/round-filtering.ts + +export async function runRoundFiltering( + roundId: string, + actorId: string, + prisma: PrismaClient +): Promise + +export async function getManualQueue( + roundId: string, + prisma: PrismaClient +): Promise + +export async function resolveManualDecision( + filteringResultId: string, + outcome: 'PASSED' | 'FILTERED_OUT', + reason: string, + actorId: string, + prisma: PrismaClient +): Promise + +export async function advanceFromFilteringRound( + roundId: string, + actorId: string, + prisma: PrismaClient +): Promise + +type FilteringJobResult = { + jobId: string + total: number + passed: number + rejected: number + flagged: number + tokensUsed: number + processingTime: number +} + +type ManualQueueItem = { + filteringResultId: string + projectId: string + projectTitle: string + outcome: string + ruleResults: RuleResult[] + aiScreeningJson: Record | null + createdAt: Date +} + +type AdvancementResult = { + advancedCount: number + targetRoundId: string + targetRoundName: string + notificationsSent: number +} +``` + +--- + +## Edge Cases + +| Edge Case | Handling | +|-----------|----------| +| **No projects to filter** | FilteringJob completes immediately with 0 processed | +| **AI API failure** | Flag all projects for manual review, log error, continue | +| **Duplicate with different outcomes** | Always flag duplicates (never auto-reject) | +| **Admin overrides auto-rejected project** | Allowed — finalOutcome overrides outcome | +| **Project withdrawn during filtering** | Skip in filtering, mark WITHDRAWN in ProjectRoundState | +| **Rule misconfiguration** | Validate config on save, throw error if invalid | +| **All projects flagged** | Valid scenario — requires manual review for all | +| **All projects auto-rejected** | Valid scenario — no advancement | +| **Advancement before manual review** | Blocked if `manualReviewRequired: true` | +| **Re-run filtering** | Deletes previous FilteringResult records, runs fresh | +| **AI response parse error** | Flag affected projects, log error, continue | +| **Duplicate groups > 10 projects** | Flag all, recommend batch review in UI | +| **Missing submittedByEmail** | Skip duplicate detection for this project | +| **Empty rule set** | All projects auto-pass (useful for testing) | + +--- + +## Integration Points + +### Connects To: INTAKE Round (Input) + +- **Input:** Projects in PENDING/IN_PROGRESS state from INTAKE round +- **Data:** Project metadata, submitted files, team member data +- **Trigger:** Admin manually runs filtering after INTAKE window closes + +### Connects To: EVALUATION Round (Output) + +- **Output:** Passing projects advance to EVALUATION round +- **Data:** FilteringResult metadata attached to projects (AI scores, flags) +- **Trigger:** Auto-advance if `autoAdvancePassingProjects: true`, else manual + +### Connects To: AI Services + +- **Service:** `src/server/services/ai-filtering.ts` +- **Purpose:** GPT-powered rubric evaluation +- **Data Flow:** Anonymized project data → OpenAI → parsed results → confidence banding + +### Connects To: Audit System + +- **Tables:** `DecisionAuditLog`, `OverrideAction`, `AuditLog`, `AIUsageLog` +- **Events:** `filtering.completed`, `filtering.manual_decision`, `filtering.auto_advanced` + +--- + +## Summary + +The redesigned FILTERING round provides: + +1. **Flexible Rule Engine** — Field checks, document checks, AI scoring, duplicates, custom scripts +2. **AI-Powered Screening** — GPT rubric evaluation with confidence banding +3. **Built-in Duplicate Detection** — Email-based (future: text similarity) +4. **Manual Review Queue** — Admin override system with full audit trail +5. **Batch Processing** — Configurable batch sizes for performance +6. **Progress Tracking** — FilteringJob model for long-running operations +7. **Auto-Advancement** — Passing projects can auto-advance to next round +8. **Full Auditability** — All decisions logged in DecisionAuditLog + OverrideAction + +This replaces the current `FILTER` stage with a fully-featured, production-ready filtering system that balances automation with human oversight. diff --git a/docs/claude-architecture-redesign/06-round-evaluation.md b/docs/claude-architecture-redesign/06-round-evaluation.md new file mode 100644 index 0000000..b965f9a --- /dev/null +++ b/docs/claude-architecture-redesign/06-round-evaluation.md @@ -0,0 +1,698 @@ +# Round: Evaluation (Jury 1 & Jury 2) + +## 1. Purpose & Position in Flow + +The EVALUATION round is the core judging mechanism of the competition. It appears **twice** in the standard flow: + +| Instance | Name | Position | Jury | Purpose | Output | +|----------|------|----------|------|---------|--------| +| Round 3 | "Jury 1 — Semi-finalist Selection" | After FILTERING | Jury 1 | Score projects, select semi-finalists | Semi-finalists per category | +| Round 5 | "Jury 2 — Finalist Selection" | After SUBMISSION Round 2 | Jury 2 | Score semi-finalists, select finalists + awards | Finalists per category | + +Both instances use the same `RoundType.EVALUATION` but are configured independently with: +- Different jury groups (Jury 1 vs Jury 2) +- Different evaluation forms/rubrics +- Different visible submission windows (Jury 1 sees Window 1 only; Jury 2 sees Windows 1+2) +- Different advancement counts + +--- + +## 2. Data Model + +### Round Record + +``` +Round { + id: "round-jury-1" + competitionId: "comp-2026" + name: "Jury 1 — Semi-finalist Selection" + roundType: EVALUATION + status: ROUND_DRAFT → ROUND_ACTIVE → ROUND_CLOSED + sortOrder: 2 + windowOpenAt: "2026-04-01" // Evaluation window start + windowCloseAt: "2026-04-30" // Evaluation window end + juryGroupId: "jury-group-1" // Links to Jury 1 + submissionWindowId: null // EVALUATION rounds don't collect submissions + configJson: { ...EvaluationConfig } +} +``` + +### EvaluationConfig + +```typescript +type EvaluationConfig = { + // --- Assignment Settings --- + requiredReviewsPerProject: number // How many jurors review each project (default: 3) + + // --- Scoring Mode --- + scoringMode: "criteria" | "global" | "binary" + // criteria: Score per criterion + weighted total + // global: Single 1-10 score + // binary: Yes/No decision (semi-finalist worthy?) + requireFeedback: boolean // Must provide text feedback (default: true) + + // --- COI --- + coiRequired: boolean // Must declare COI before evaluating (default: true) + + // --- Peer Review --- + peerReviewEnabled: boolean // Jurors can see anonymized peer evaluations after submission + anonymizationLevel: "fully_anonymous" | "show_initials" | "named" + + // --- AI Features --- + aiSummaryEnabled: boolean // Generate AI-powered evaluation summaries + aiAssignmentEnabled: boolean // Allow AI-suggested jury-project matching + + // --- Advancement --- + advancementMode: "auto_top_n" | "admin_selection" | "ai_recommended" + advancementConfig: { + perCategory: boolean // Separate counts per STARTUP / BUSINESS_CONCEPT + startupCount: number // How many startups advance (default: 10 for Jury 1, 3 for Jury 2) + conceptCount: number // How many concepts advance + tieBreaker: "admin_decides" | "highest_individual" | "revote" + } +} +``` + +### Related Models + +| Model | Role | +|-------|------| +| `JuryGroup` | Named jury entity linked to this round | +| `JuryGroupMember` | Members of the jury with per-juror overrides | +| `Assignment` | Juror-project pairing for this round, linked to JuryGroup | +| `Evaluation` | Score/feedback submitted by a juror for one project | +| `EvaluationForm` | Rubric/criteria definition for this round | +| `ConflictOfInterest` | COI declaration per assignment | +| `GracePeriod` | Per-juror deadline extension | +| `EvaluationSummary` | AI-generated insights per project per round | +| `EvaluationDiscussion` | Peer review discussion threads | +| `RoundSubmissionVisibility` | Which submission windows' docs jury can see | +| `AdvancementRule` | How projects advance after evaluation | +| `ProjectRoundState` | Per-project state in this round | + +--- + +## 3. Setup Phase (Before Window Opens) + +### 3.1 Admin Creates the Evaluation Round + +Admin uses the competition wizard or round management UI to: + +1. **Create the Round** with type EVALUATION +2. **Link a JuryGroup** — select "Jury 1" (or create a new jury group) +3. **Set the evaluation window** — start and end dates +4. **Configure the evaluation form** — scoring criteria, weights, scales +5. **Set visibility** — which submission windows jury can see (via RoundSubmissionVisibility) +6. **Configure advancement rules** — how many advance per category + +### 3.2 Jury Group Configuration + +The linked JuryGroup has: + +``` +JuryGroup { + name: "Jury 1" + defaultMaxAssignments: 20 // Default cap per juror + defaultCapMode: SOFT // HARD | SOFT | NONE + softCapBuffer: 2 // Can exceed by 2 for load balancing + categoryQuotasEnabled: true + defaultCategoryQuotas: { + "STARTUP": { "min": 3, "max": 15 }, + "BUSINESS_CONCEPT": { "min": 3, "max": 15 } + } + allowJurorCapAdjustment: true // Jurors can adjust their cap during onboarding + allowJurorRatioAdjustment: true // Jurors can adjust their category preference +} +``` + +### 3.3 Per-Juror Overrides + +Each `JuryGroupMember` can override group defaults: + +``` +JuryGroupMember { + juryGroupId: "jury-group-1" + userId: "judge-alice" + maxAssignmentsOverride: 25 // Alice wants more projects + capModeOverride: HARD // Alice: hard cap, no exceptions + categoryQuotasOverride: { + "STARTUP": { "min": 5, "max": 20 }, // Alice prefers startups + "BUSINESS_CONCEPT": { "min": 0, "max": 5 } + } + preferredStartupRatio: 0.8 // 80% startups +} +``` + +### 3.4 Juror Onboarding (Optional) + +If `allowJurorCapAdjustment` or `allowJurorRatioAdjustment` is true: + +1. When a juror first opens their jury dashboard after being added to the group +2. A one-time onboarding dialog appears: + - "Your default maximum is 20 projects. Would you like to adjust?" (slider) + - "Your default startup/concept ratio is 50/50. Would you like to adjust?" (slider) +3. Juror saves preferences → stored in `JuryGroupMember.maxAssignmentsOverride` and `preferredStartupRatio` +4. Dialog doesn't appear again (tracked via `JuryGroupMember.updatedAt` or a flag) + +--- + +## 4. Assignment System (Enhanced) + +### 4.1 Assignment Algorithm — Jury-Group-Aware + +The current `stage-assignment.ts` algorithm is enhanced to: + +1. **Filter jury pool by JuryGroup** — only members of the linked jury group are considered +2. **Apply hard/soft cap logic** per juror +3. **Apply category quotas** per juror +4. **Score candidates** using existing expertise matching + workload balancing + geo-diversity + +#### Effective Limits Resolution + +```typescript +function getEffectiveLimits(member: JuryGroupMember, group: JuryGroup): EffectiveLimits { + return { + maxAssignments: member.maxAssignmentsOverride ?? group.defaultMaxAssignments, + capMode: member.capModeOverride ?? group.defaultCapMode, + softCapBuffer: group.softCapBuffer, // Group-level only (not per-juror) + categoryQuotas: member.categoryQuotasOverride ?? group.defaultCategoryQuotas, + categoryQuotasEnabled: group.categoryQuotasEnabled, + preferredStartupRatio: member.preferredStartupRatio, + } +} +``` + +#### Cap Enforcement Logic + +```typescript +function canAssignMore( + jurorId: string, + projectCategory: CompetitionCategory, + currentLoad: LoadTracker, + limits: EffectiveLimits +): { allowed: boolean; penalty: number; reason?: string } { + const total = currentLoad.total(jurorId) + const catLoad = currentLoad.byCategory(jurorId, projectCategory) + + // 1. HARD cap check + if (limits.capMode === "HARD" && total >= limits.maxAssignments) { + return { allowed: false, penalty: 0, reason: "Hard cap reached" } + } + + // 2. SOFT cap check (can exceed by buffer) + let overflowPenalty = 0 + if (limits.capMode === "SOFT") { + if (total >= limits.maxAssignments + limits.softCapBuffer) { + return { allowed: false, penalty: 0, reason: "Soft cap + buffer exceeded" } + } + if (total >= limits.maxAssignments) { + // In buffer zone — apply increasing penalty + overflowPenalty = (total - limits.maxAssignments + 1) * 15 + } + } + + // 3. Category quota check + if (limits.categoryQuotasEnabled && limits.categoryQuotas) { + const quota = limits.categoryQuotas[projectCategory] + if (quota) { + if (catLoad >= quota.max) { + return { allowed: false, penalty: 0, reason: `Category ${projectCategory} max reached (${quota.max})` } + } + // Bonus for under-min + if (catLoad < quota.min) { + overflowPenalty -= 15 // Negative penalty = bonus + } + } + } + + // 4. Ratio preference alignment + if (limits.preferredStartupRatio != null && total > 0) { + const currentStartupRatio = currentLoad.byCategory(jurorId, "STARTUP") / total + const isStartup = projectCategory === "STARTUP" + const wantMore = isStartup + ? currentStartupRatio < limits.preferredStartupRatio + : currentStartupRatio > limits.preferredStartupRatio + if (wantMore) overflowPenalty -= 10 // Bonus for aligning with preference + else overflowPenalty += 10 // Penalty for diverging + } + + return { allowed: true, penalty: overflowPenalty } +} +``` + +### 4.2 Assignment Flow + +``` +1. Admin opens Assignment panel for Round 3 (Jury 1) +2. System loads: + - Projects with ProjectRoundState PENDING/IN_PROGRESS in this round + - JuryGroup members (with effective limits) + - Existing assignments (to avoid duplicates) + - COI records (to skip conflicted pairs) +3. Admin clicks "Generate Suggestions" +4. Algorithm runs: + a. For each project (sorted by fewest current assignments): + - Score each eligible juror (tag matching + workload + geo + cap/quota penalties) + - Select top N jurors (N = requiredReviewsPerProject - existing reviews) + - Track load in jurorLoadMap + b. Report unassigned projects (jurors at capacity) +5. Admin reviews preview: + - Assignment matrix (juror × project grid) + - Load distribution chart + - Unassigned projects list + - Category distribution per juror +6. Admin can: + - Accept all suggestions + - Modify individual assignments (drag-drop or manual add/remove) + - Re-run with different parameters +7. Admin clicks "Apply Assignments" +8. System creates Assignment records with juryGroupId set +9. Notifications sent to jurors +``` + +### 4.3 AI-Powered Assignment (Optional) + +If `aiAssignmentEnabled` is true in config: + +1. Admin clicks "AI Assignment Suggestions" +2. System calls `ai-assignment.ts`: + - Anonymizes juror profiles and project descriptions + - Sends to GPT with matching instructions + - Returns confidence scores and reasoning +3. AI suggestions shown alongside algorithm suggestions +4. Admin picks which to use or mixes both + +### 4.4 Handling Unassigned Projects + +When all jurors with SOFT cap reach cap+buffer: +1. Remaining projects become "unassigned" +2. Admin dashboard highlights these prominently +3. Admin can: + - Manually assign to specific jurors (bypasses cap — manual override) + - Increase a juror's cap + - Add more jurors to the jury group + - Reduce `requiredReviewsPerProject` for remaining projects + +--- + +## 5. Jury Evaluation Experience + +### 5.1 Jury Dashboard + +When a Jury 1 member opens their dashboard: + +``` +┌─────────────────────────────────────────────────────┐ +│ JURY 1 — Semi-finalist Selection │ +│ ─────────────────────────────────────────────────── │ +│ Evaluation Window: April 1 – April 30 │ +│ ⏱ 12 days remaining │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ +│ │ 15 │ │ 8 │ │ 2 │ │ 5 │ │ +│ │ Total │ │ Complete │ │ In Draft │ │ Pending│ │ +│ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ +│ │ +│ [Continue Next Evaluation →] │ +│ │ +│ Recent Assignments │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ OceanClean AI │ Startup │ ✅ Done │ View │ │ +│ │ Blue Carbon Hub │ Concept │ ⏳ Draft │ Cont │ │ +│ │ SeaWatch Monitor │ Startup │ ⬜ Pending│ Start│ │ +│ │ ... │ │ +│ └──────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────┘ +``` + +Key elements: +- **Deadline countdown** — prominent timer showing days/hours remaining +- **Progress stats** — total, completed, in-draft, pending +- **Quick action CTA** — jump to next unevaluated project +- **Assignment list** — sorted by status (pending first, then drafts, then done) + +### 5.2 COI Declaration (Blocking) + +Before evaluating any project, the juror MUST declare COI: + +``` +┌───────────────────────────────────────────┐ +│ Conflict of Interest Declaration │ +│ │ +│ Do you have a conflict of interest with │ +│ "OceanClean AI" (Startup)? │ +│ │ +│ ○ No conflict — I can evaluate fairly │ +│ ○ Yes, I have a conflict: │ +│ Type: [Financial ▾] │ +│ Description: [________________] │ +│ │ +│ [Submit Declaration] │ +└───────────────────────────────────────────┘ +``` + +- If **No conflict**: Proceed to evaluation form +- If **Yes**: Assignment flagged, admin notified, juror may be reassigned +- COI declaration is logged in `ConflictOfInterest` model +- Admin can review and take action (cleared / reassigned / noted) + +### 5.3 Evaluation Form + +The form adapts to the `scoringMode`: + +#### Criteria Mode (default for Jury 1 and Jury 2) + +``` +┌───────────────────────────────────────────────────┐ +│ Evaluating: OceanClean AI (Startup) │ +│ ──────────────────────────────────────────────── │ +│ │ +│ [📄 Documents] [📊 Scoring] [💬 Feedback] │ +│ │ +│ ── DOCUMENTS TAB ── │ +│ ┌─ Round 1 Application Docs ─────────────────┐ │ +│ │ 📄 Executive Summary.pdf [Download] │ │ +│ │ 📄 Business Plan.pdf [Download] │ │ +│ └─────────────────────────────────────────────┘ │ +│ │ +│ (Jury 2 also sees:) │ +│ ┌─ Round 2 Semi-finalist Docs ────────────────┐ │ +│ │ 📄 Updated Business Plan.pdf [Download] │ │ +│ │ 🎥 Video Pitch.mp4 [Play] │ │ +│ └─────────────────────────────────────────────┘ │ +│ │ +│ ── SCORING TAB ── │ +│ Innovation & Impact [1] [2] [3] [4] [5] (w:30%)│ +│ Feasibility [1] [2] [3] [4] [5] (w:25%)│ +│ Team & Execution [1] [2] [3] [4] [5] (w:25%)│ +│ Ocean Relevance [1] [2] [3] [4] [5] (w:20%)│ +│ │ +│ Overall Score: 3.8 / 5.0 (auto-calculated) │ +│ │ +│ ── FEEDBACK TAB ── │ +│ Feedback: [________________________________] │ +│ │ +│ [💾 Save Draft] [✅ Submit Evaluation] │ +│ (Auto-saves every 30s) │ +└───────────────────────────────────────────────────┘ +``` + +#### Binary Mode (optional for quick screening) + +``` +Should this project advance to the semi-finals? +[✅ Yes] [❌ No] + +Justification (required): [________________] +``` + +#### Global Score Mode + +``` +Overall Score: [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] + +Feedback (required): [________________] +``` + +### 5.4 Document Visibility (Cross-Round) + +Controlled by `RoundSubmissionVisibility`: + +| Round | Sees Window 1 ("Application Docs") | Sees Window 2 ("Semi-finalist Docs") | +|-------|------------------------------------|-----------------------------------------| +| Jury 1 (Round 3) | Yes | No (doesn't exist yet) | +| Jury 2 (Round 5) | Yes | Yes | +| Jury 3 (Round 7) | Yes | Yes | + +In the evaluation UI: +- Documents are grouped by submission window +- Each group has a label (from `RoundSubmissionVisibility.displayLabel`) +- Clear visual separation (tabs, accordion sections, or side panels) + +### 5.5 Auto-Save and Submission + +- **Auto-save**: Client debounces and calls `evaluation.autosave` every 30 seconds while draft is open +- **Draft status**: Evaluation starts as NOT_STARTED → DRAFT on first save → SUBMITTED on explicit submit +- **Submission validation**: + - All required criteria scored (if criteria mode) + - Global score provided (if global mode) + - Binary decision selected (if binary mode) + - Feedback text provided (if `requireFeedback`) + - Window is open (or juror has grace period) +- **After submission**: Evaluation becomes read-only for juror (status = SUBMITTED) +- **Admin can lock**: Set status to LOCKED to prevent any further changes + +### 5.6 Grace Periods + +``` +GracePeriod { + roundId: "round-jury-1" + userId: "judge-alice" + projectId: null // Applies to ALL Alice's assignments in this round + extendedUntil: "2026-05-02" // 2 days after official close + reason: "Travel conflict" + grantedById: "admin-1" +} +``` + +- Admin can grant per-juror or per-juror-per-project grace periods +- Evaluation submission checks grace period before rejecting past-window submissions +- Dashboard shows "(Grace period: 2 extra days)" badge for affected jurors + +--- + +## 6. End of Evaluation — Results & Advancement + +### 6.1 Results Visualization + +When the evaluation window closes, the admin sees: + +``` +┌──────────────────────────────────────────────────────────────┐ +│ Jury 1 Results │ +│ ─────────────────────────────────────────────────────────── │ +│ │ +│ Completion: 142/150 evaluations submitted (94.7%) │ +│ Outstanding: 8 (3 jurors have pending evaluations) │ +│ │ +│ ┌─ STARTUPS (Top 10) ──────────────────────────────────────┐│ +│ │ # Project Avg Score Consensus Reviews Status ││ +│ │ 1 OceanClean AI 4.6/5 0.92 3/3 ✅ ││ +│ │ 2 SeaWatch 4.3/5 0.85 3/3 ✅ ││ +│ │ 3 BlueCarbon 4.1/5 0.78 3/3 ✅ ││ +│ │ ... ││ +│ │ 10 TidalEnergy 3.2/5 0.65 3/3 ✅ ││ +│ │ ── cutoff line ────────────────────────────────────────── ││ +│ │ 11 WavePower 3.1/5 0.71 3/3 ⬜ ││ +│ │ 12 CoralGuard 2.9/5 0.55 2/3 ⚠️ ││ +│ └──────────────────────────────────────────────────────────┘│ +│ │ +│ ┌─ CONCEPTS (Top 10) ──────────────────────────────────────┐│ +│ │ (same layout) ││ +│ └──────────────────────────────────────────────────────────┘│ +│ │ +│ [🤖 AI Recommendation] [📊 Score Distribution] [Export] │ +│ │ +│ [✅ Approve Shortlist] [✏️ Edit Shortlist] │ +└──────────────────────────────────────────────────────────────┘ +``` + +**Metrics shown:** +- Average global score (or weighted criteria average) +- Consensus score (1 - normalized stddev, where 1.0 = full agreement) +- Review count / required +- Per-criterion averages (expandable) + +### 6.2 AI Recommendation + +When admin clicks "AI Recommendation": + +1. System calls `ai-evaluation-summary.ts` for each project in bulk +2. AI generates: + - Ranked shortlist per category based on scores + feedback analysis + - Strengths, weaknesses, themes per project + - Recommendation: "Advance" / "Borderline" / "Do not advance" +3. Admin sees AI recommendation alongside actual scores +4. AI recommendations are suggestions only — admin has final say + +### 6.3 Advancement Decision + +``` +Advancement Mode: admin_selection (with AI recommendation) + +1. System shows ranked list per category +2. AI highlights recommended top N per category +3. Admin can: + - Accept AI recommendation + - Drag projects to reorder + - Add/remove projects from advancement list + - Set custom cutoff line +4. Admin clicks "Confirm Advancement" +5. System: + a. Sets ProjectRoundState to PASSED for advancing projects + b. Sets ProjectRoundState to REJECTED for non-advancing projects + c. Updates Project.status to SEMIFINALIST (Jury 1) or FINALIST (Jury 2) + d. Logs all decisions in DecisionAuditLog + e. Sends notifications to all teams (advanced / not selected) +``` + +### 6.4 Advancement Modes + +| Mode | Behavior | +|------|----------| +| `auto_top_n` | Top N per category automatically advance when window closes | +| `admin_selection` | Admin manually selects who advances (with AI/score guidance) | +| `ai_recommended` | AI proposes list, admin must approve/modify | + +--- + +## 7. Special Awards Integration (Jury 2 Only) + +During the Jury 2 evaluation round, special awards can run alongside: + +### 7.1 How It Works + +``` +Round 5: "Jury 2 — Finalist Selection" + ├── Main evaluation (all semi-finalists scored by Jury 2) + └── Special Awards (run in parallel): + ├── "Innovation Award" — STAY_IN_MAIN mode + │ Projects remain in main eval, flagged as eligible + │ Award jury (subset of Jury 2 or separate) votes + └── "Impact Award" — SEPARATE_POOL mode + AI filters eligible projects into award pool + Dedicated jury evaluates and votes +``` + +### 7.2 SpecialAward.evaluationRoundId + +Each award links to the evaluation round it runs alongside: +``` +SpecialAward { + evaluationRoundId: "round-jury-2" // Runs during Jury 2 + eligibilityMode: STAY_IN_MAIN + juryGroupId: "jury-group-innovation" // Can be same or different jury +} +``` + +### 7.3 Award Evaluation Flow + +1. Before Jury 2 window opens: Admin runs award eligibility (AI or manual) +2. During Jury 2 window: Award jury members see their award assignments alongside regular evaluations +3. Award jury submits award votes (PICK_WINNER, RANKED, or SCORED) +4. After Jury 2 closes: Award results finalized alongside main results + +--- + +## 8. Differences Between Jury 1 and Jury 2 + +| Aspect | Jury 1 (Round 3) | Jury 2 (Round 5) | +|--------|-------------------|-------------------| +| Input projects | All eligible (post-filtering) | Semi-finalists only | +| Visible docs | Window 1 only | Window 1 + Window 2 | +| Output | Semi-finalists | Finalists | +| Project.status update | → SEMIFINALIST | → FINALIST | +| Special awards | No | Yes (alongside) | +| Jury group | Jury 1 | Jury 2 (different members, possible overlap) | +| Typical project count | 50-100+ | 10-20 | +| Required reviews | 3 (more projects, less depth) | 3-5 (fewer projects, more depth) | + +--- + +## 9. API Changes + +### Preserved Procedures (renamed stageId → roundId) + +| Procedure | Change | +|-----------|--------| +| `evaluation.get` | roundId via assignment | +| `evaluation.start` | No change | +| `evaluation.autosave` | No change | +| `evaluation.submit` | Window check uses round.windowCloseAt + grace periods | +| `evaluation.declareCOI` | No change | +| `evaluation.getCOIStatus` | No change | +| `evaluation.getProjectStats` | No change | +| `evaluation.listByRound` | Renamed from listByStage | +| `evaluation.generateSummary` | roundId instead of stageId | +| `evaluation.generateBulkSummaries` | roundId instead of stageId | + +### New Procedures + +| Procedure | Purpose | +|-----------|---------| +| `assignment.previewWithJuryGroup` | Preview assignments filtered by jury group with cap/quota logic | +| `assignment.getJuryGroupStats` | Per-member stats: load, category distribution, cap utilization | +| `evaluation.getResultsOverview` | Rankings, scores, consensus, AI recommendations per category | +| `evaluation.confirmAdvancement` | Admin confirms which projects advance | +| `evaluation.getAdvancementPreview` | Preview advancement impact before confirming | + +### Modified Procedures + +| Procedure | Modification | +|-----------|-------------| +| `assignment.getSuggestions` | Now filters by JuryGroup, applies hard/soft caps, category quotas | +| `assignment.create` | Now sets `juryGroupId` on Assignment | +| `assignment.bulkCreate` | Now validates against jury group caps | +| `file.listByProjectForRound` | Uses RoundSubmissionVisibility to filter docs | + +--- + +## 10. Service Layer Changes + +### `stage-assignment.ts` → `round-assignment.ts` + +Key changes to `previewStageAssignment` → `previewRoundAssignment`: + +1. **Load jury pool from JuryGroup** instead of all JURY_MEMBER users: +```typescript +const juryGroup = await prisma.juryGroup.findUnique({ + where: { id: round.juryGroupId }, + include: { members: { include: { user: true } } } +}) +const jurors = juryGroup.members.map(m => ({ + ...m.user, + effectiveLimits: getEffectiveLimits(m, juryGroup), +})) +``` + +2. **Replace simple max check** with cap mode logic (hard/soft/none) +3. **Add category quota tracking** per juror +4. **Add ratio preference scoring** in candidate ranking +5. **Report overflow** — projects that couldn't be assigned because all jurors hit caps + +### `stage-engine.ts` → `round-engine.ts` + +Simplified: +- Remove trackId from all transitions +- `executeTransition` now takes `fromRoundId` + `toRoundId` (or auto-advance to next sortOrder) +- `validateTransition` simplified — no StageTransition lookup, just checks next round exists and is active +- Guard evaluation simplified — AdvancementRule.configJson replaces arbitrary guardJson + +--- + +## 11. Edge Cases + +### More projects than jurors can handle +- Algorithm assigns up to hard/soft cap for all jurors +- Remaining projects flagged as "unassigned" in admin dashboard +- Admin must: add jurors, increase caps, or manually assign + +### Juror doesn't complete by deadline +- Dashboard shows overdue assignments prominently +- Admin can: extend via GracePeriod, reassign to another juror, or mark as incomplete + +### Tie in scores at cutoff +- Depending on `tieBreaker` config: + - `admin_decides`: Admin manually picks from tied projects + - `highest_individual`: Project with highest single-evaluator score wins + - `revote`: Tied projects sent back for quick re-evaluation + +### Category imbalance +- If one category has far more projects, quotas ensure jurors still get a mix +- If quotas can't be satisfied (not enough of one category), system relaxes quota for that category + +### Juror in multiple jury groups +- Juror Alice is in Jury 1 and Jury 2 +- Her assignments for each round are independent +- Her caps are per-jury-group (20 for Jury 1, 15 for Jury 2) +- No cross-round cap — each round manages its own workload diff --git a/docs/claude-architecture-redesign/07-round-submission.md b/docs/claude-architecture-redesign/07-round-submission.md new file mode 100644 index 0000000..f7189cb --- /dev/null +++ b/docs/claude-architecture-redesign/07-round-submission.md @@ -0,0 +1,2053 @@ +# 07: SUBMISSION Round — Multi-Window Document Collection System + +**Document Version**: 2.0 +**Last Updated**: 2026-02-15 +**Status**: Architecture Design (Redesign) + +--- + +## Table of Contents + +1. [Purpose & Position in Flow](#1-purpose--position-in-flow) +2. [Multi-Round Submission Architecture](#2-multi-round-submission-architecture) +3. [SubmissionConfig Shape](#3-submissionconfig-shape) +4. [Applicant Experience (Detailed)](#4-applicant-experience-detailed) +5. [Jury Cross-Round Visibility (Detailed)](#5-jury-cross-round-visibility-detailed) +6. [Admin Experience](#6-admin-experience) +7. [API Changes](#7-api-changes) +8. [File Promotion from Mentoring](#8-file-promotion-from-mentoring) +9. [Edge Cases](#9-edge-cases) +10. [Implementation Checklist](#10-implementation-checklist) + +--- + +## 1. Purpose & Position in Flow + +### 1.1 Core Problem Statement + +**Current System Gap**: The MOPC platform currently only supports **one** submission window tied to the INTAKE round. There is no mechanism to: + +1. Request **additional documents** from advancing teams mid-competition +2. **Lock previous submissions** as read-only while collecting new materials +3. Keep **Round 1 documents intact** while teams submit Round 2 materials +4. Control which **jury rounds see which documents** + +**Real-World Impact**: +- Semi-finalists can't be asked for updated pitch decks without replacing Round 1 materials +- Finalists can't submit presentation materials separately from initial applications +- If teams update files, original submissions are lost (no audit trail) +- Organizers resort to email-based document collection (breaks platform integrity) + +### 1.2 SUBMISSION Round Solution + +The **SUBMISSION** round is a NEW round type that: + +1. **Opens a second (or subsequent) submission window** for advancing projects +2. **Locks previous windows to read-only** for applicants (admin retains full control) +3. **Collects different file requirements** per competition stage +4. **Controls jury visibility** via RoundSubmissionVisibility records +5. **Maintains complete audit trail** across all submission phases + +### 1.3 Position in Competition Flow + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ FULL COMPETITION FLOW │ +└──────────────────────────────────────────────────────────────────┘ + +Round 1: INTAKE +├─ Creates SubmissionWindow 1: "Application Documents" +├─ Projects submit: Pitch Deck, Budget, Team CV +├─ Window State: OPEN (Feb 1 - Mar 1) +└─ All applicants participate (150 projects) + +Round 2: FILTERING +├─ Admin/AI screens applications using Window 1 documents +├─ 50 projects advance with status = PASSED +└─ Window 1 remains OPEN (teams can still edit) + +Round 3: EVALUATION (Jury 1) +├─ Jury evaluates 50 projects using Window 1 documents +├─ Visibility: Window 1 ONLY +├─ 20 projects advance with status = PASSED +└─ Window 1 remains OPEN + +Round 4: SUBMISSION ◄──── THIS IS THE NEW ROUND TYPE +├─ Creates SubmissionWindow 2: "Semi-finalist Materials" +├─ When Round 4 starts: +│ ├─ Window 1 LOCKS automatically (read-only for applicants) +│ ├─ Window 2 OPENS (Apr 1 - Apr 15) +│ ├─ Only 20 PASSED projects from Round 3 can submit +│ └─ Email notifications sent to eligible teams +├─ New requirements: +│ ├─ Updated Pitch Deck (required) +│ ├─ Video Pitch (required, max 100MB) +│ ├─ Financial Projections (required) +│ └─ Team Photos (optional) +└─ Deadline policy: GRACE (48 hours after Apr 15) + +Round 5: EVALUATION (Jury 2) +├─ Jury evaluates 20 projects using BOTH Window 1 + Window 2 +├─ Visibility: Window 1 AND Window 2 +├─ UI shows two tabs: "Round 1 Docs" | "Round 2 Docs" +├─ 10 projects advance with status = PASSED +└─ Window 2 LOCKS when Round 5 starts + +Round 6: SUBMISSION (Optional Third Window) +├─ Creates SubmissionWindow 3: "Finalist Presentations" +├─ Only 10 PASSED projects from Round 5 can submit +├─ New requirements: +│ ├─ Final Pitch Deck (required) +│ ├─ 3-Minute Video (required) +│ └─ Impact Report (required) +└─ Window 1 + 2 remain LOCKED, Window 3 OPEN + +Round 7: LIVE_FINAL +└─ Top 10 present live using Window 3 materials +``` + +**Key Characteristics**: + +| Feature | Behavior | +|---------|----------| +| **Multiple Windows** | Each SUBMISSION round creates exactly ONE new SubmissionWindow | +| **Sequential Locking** | When Window N opens, Window N-1 locks for applicants | +| **Eligibility Filtering** | Only projects with specific statuses from previous round can submit | +| **Independent Requirements** | Each window has its own file requirements (not shared) | +| **Cumulative Visibility** | Later EVALUATION rounds can see multiple windows simultaneously | +| **Admin Override** | Admins always have full control regardless of lock state | + +### 1.4 When to Use SUBMISSION Rounds + +| Scenario | Use SUBMISSION? | Explanation | +|----------|----------------|-------------| +| **Single-round competition** (one evaluation) | ❌ No | One INTAKE window is sufficient | +| **Two-stage competition** (semi-final + final) | ✅ Yes | INTAKE → EVALUATION → **SUBMISSION** → EVALUATION | +| **Three-stage competition** (screening + semi + final) | ✅ Yes (2x) | INTAKE → EVAL → **SUBMISSION** → EVAL → **SUBMISSION** → EVAL | +| **Requesting updated docs from same pool** | ❌ Maybe | Consider MENTORING with file promotion instead | +| **Post-award deliverables** (winner docs) | ✅ Yes | Create SUBMISSION round after awards announced | +| **Mid-competition clarifications** | ❌ No | Use comments or mentoring workspace | + +### 1.5 Relationship to Other Round Types + +**SUBMISSION vs INTAKE**: +- **INTAKE** = First submission window (all applicants, competition start) +- **SUBMISSION** = Subsequent submission windows (filtered subset, mid-competition) +- **Both create SubmissionWindow records** (INTAKE creates Window 1, SUBMISSION creates Window 2+) + +**SUBMISSION vs EVALUATION**: +- **SUBMISSION** = Document collection phase (no scoring, just uploads) +- **EVALUATION** = Assessment phase (jury scores projects using submitted docs) +- **EVALUATION rounds declare which windows they can see** via RoundSubmissionVisibility + +**SUBMISSION vs MENTORING**: +- **MENTORING** = Collaborative workspace (mentor + team iterate on documents) +- **SUBMISSION** = Official competition documents (locked after deadline) +- **Files can be promoted** from MENTORING → SUBMISSION (see Section 8) + +**SUBMISSION vs FILTERING**: +- **FILTERING** = Automated screening using existing documents +- **SUBMISSION** = New document collection opportunity +- **FILTERING typically comes BEFORE** SUBMISSION (screen first, then request more docs) + +--- + +## 2. Multi-Round Submission Architecture + +### 2.1 Data Model Overview + +```prisma +// NEW: SubmissionWindow model +model SubmissionWindow { + id String @id @default(cuid()) + competitionId String + roundId String @unique // Each round creates max ONE window + name String // "Application Docs", "Semi-finalist Materials" + description String? @db.Text + + // Timing + openDate DateTime + closeDate DateTime + + // Deadline policy + latePolicy LateSubmissionPolicy // HARD | FLAG | GRACE + gracePeriodHours Int? // If latePolicy = GRACE + + // Locking + lockDate DateTime? // When window becomes read-only for applicants + isLocked Boolean @default(false) + + // Relations + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + round Round @relation(fields: [roundId], references: [id], onDelete: Cascade) + + fileRequirements SubmissionFileRequirement[] + projectFiles ProjectFile[] + visibleToRounds RoundSubmissionVisibility[] + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([competitionId, roundId]) + @@index([competitionId]) + @@index([openDate]) + @@index([closeDate]) +} + +enum LateSubmissionPolicy { + HARD // Reject submissions after closeDate + FLAG // Accept late submissions but mark as late + GRACE // Allow submissions during grace period, then hard reject +} + +// NEW: SubmissionFileRequirement model +model SubmissionFileRequirement { + id String @id @default(cuid()) + submissionWindowId String + label String // "Pitch Deck", "Budget Spreadsheet" + description String? @db.Text + isRequired Boolean @default(true) + allowedFileTypes String[] // ["pdf", "pptx", "docx"] + maxSizeMB Int @default(10) + displayOrder Int + + submissionWindow SubmissionWindow @relation(fields: [submissionWindowId], references: [id], onDelete: Cascade) + projectFiles ProjectFile[] + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@index([submissionWindowId]) + @@index([displayOrder]) +} + +// NEW: RoundSubmissionVisibility model +model RoundSubmissionVisibility { + id String @id @default(cuid()) + evaluationRoundId String // Which EVALUATION round can see docs + submissionWindowId String // Which SubmissionWindow's docs + displayLabel String // "Round 1 Documents", "Semi-final Submissions" + displayOrder Int + + evaluationRound Round @relation("EvaluationRoundVisibility", fields: [evaluationRoundId], references: [id], onDelete: Cascade) + submissionWindow SubmissionWindow @relation(fields: [submissionWindowId], references: [id], onDelete: Cascade) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([evaluationRoundId, submissionWindowId]) + @@index([evaluationRoundId]) + @@index([submissionWindowId]) +} + +// UPDATED: ProjectFile model (add submissionWindowId) +model ProjectFile { + id String @id @default(cuid()) + projectId String + submissionWindowId String // NEW: Links to SubmissionWindow + requirementId String? // NEW: Links to SubmissionFileRequirement + + filename String + mimeType String + sizeBytes BigInt + storagePath String + uploadedBy String + uploadedAt DateTime @default(now()) + + isLate Boolean @default(false) + + // Versioning + supersededBy String? // Points to newer version of this file + supersededAt DateTime? + + // Promotion from mentoring + promotedFrom String? // Points to MentorFile.id + promotedAt DateTime? + + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + submissionWindow SubmissionWindow @relation(fields: [submissionWindowId], references: [id], onDelete: Cascade) + requirement SubmissionFileRequirement? @relation(fields: [requirementId], references: [id], onDelete: SetNull) + uploadedByUser User @relation(fields: [uploadedBy], references: [id]) + + @@index([projectId]) + @@index([submissionWindowId]) + @@index([requirementId]) + @@index([uploadedBy]) +} + +// UPDATED: Round model (add submissionWindowId) +model Round { + id String @id @default(cuid()) + competitionId String + type RoundType + name String + description String? @db.Text + displayOrder Int + + // For SUBMISSION rounds + submissionWindowId String? @unique // Links to SubmissionWindow + + configJson Json? @db.JsonB // Stores SubmissionConfig for SUBMISSION rounds + + // ... other fields ... + + submissionWindow SubmissionWindow? + visibleWindows RoundSubmissionVisibility[] @relation("EvaluationRoundVisibility") +} +``` + +### 2.2 Window Lifecycle States + +Each SubmissionWindow progresses through these states: + +``` +┌─────────────┐ +│ PENDING │ Created but openDate not reached +│ │ - Not visible to applicants +│ │ - Admin can edit requirements freely +│ │ - isLocked = false, lockDate = null +└──────┬──────┘ + │ openDate arrives (Round transitions to ACTIVE) + ▼ +┌─────────────┐ +│ OPEN │ Accepting submissions +│ │ - Applicants can upload/replace/delete files +│ │ - Admin can edit requirements (with warnings if teams already submitted) +│ │ - Previous windows may be locked +│ │ - isLocked = false +└──────┬──────┘ + │ closeDate arrives + ▼ +┌─────────────┐ +│ CLOSED │ Past deadline (policy-dependent) +│ │ - latePolicy = HARD: No uploads allowed +│ │ - latePolicy = FLAG: Uploads allowed, marked as late +│ │ - latePolicy = GRACE: Uploads allowed until lockDate +│ │ - isLocked = depends on policy +└──────┬──────┘ + │ lockDate arrives (if GRACE) OR admin manually locks + ▼ +┌─────────────┐ +│ LOCKED │ Read-only for applicants, full control for admins +│ │ - Applicants: view/download only, no uploads/deletes +│ │ - Admins: can still upload/replace/delete on behalf +│ │ - Juries: view-only (if visibility configured) +│ │ - isLocked = true +└─────────────┘ +``` + +**State Transitions**: + +| From | To | Trigger | Side Effects | +|------|----|---------| -------------| +| PENDING | OPEN | `openDate` reached | Lock previous windows (if config), notify eligible teams | +| OPEN | CLOSED | `closeDate` reached | Start grace period (if GRACE policy) | +| CLOSED | LOCKED | `lockDate` reached OR admin action | Final state, no more applicant changes | + +### 2.3 Multi-Window Coordination Example + +**Scenario**: MOPC 2026 with 3 evaluation rounds + +``` +Competition: MOPC 2026 +├─ Round 1: INTAKE +│ └─ SubmissionWindow 1: "Application Documents" +│ ├─ Open: Jan 1 - Feb 1 +│ ├─ Close: Feb 1 +│ ├─ Late Policy: GRACE (72 hours → lock Feb 4) +│ ├─ Requirements: +│ │ ├─ Pitch Deck (PDF, required, max 10MB) +│ │ ├─ Budget (XLSX/PDF, required, max 5MB) +│ │ └─ Team CV (PDF, optional, max 5MB) +│ └─ Status: OPEN (150 projects submit) +│ +├─ Round 2: FILTERING +│ └─ Screens 150 applications → 50 advance (status = PASSED) +│ +├─ Round 3: EVALUATION (Jury 1) +│ ├─ Visibility: Window 1 ONLY +│ ├─ Jury sees: +│ │ └─ Tab: "Application Documents" (Pitch, Budget, CV) +│ └─ 20 projects advance (status = PASSED) +│ +├─ Round 4: SUBMISSION ◄──── NEW ROUND TYPE +│ └─ SubmissionWindow 2: "Semi-finalist Materials" +│ ├─ Opens: Mar 1 (Window 1 auto-locks at this moment) +│ ├─ Close: Mar 15 +│ ├─ Late Policy: HARD (no late submissions) +│ ├─ Eligible: 20 projects with status=PASSED from Round 3 +│ ├─ Requirements: +│ │ ├─ Updated Pitch Deck (PDF, required, max 15MB) +│ │ ├─ Video Pitch (MP4/MOV, required, max 100MB) +│ │ ├─ Financial Projections (XLSX/PDF, required, max 10MB) +│ │ └─ Team Photos (JPG/PNG, optional, max 5MB each) +│ └─ Status: OPEN (20 eligible projects can submit) +│ +├─ Round 5: EVALUATION (Jury 2) +│ ├─ Visibility: Window 1 AND Window 2 +│ ├─ Jury sees: +│ │ ├─ Tab 1: "Round 1 Application" (Pitch, Budget, CV from Jan) +│ │ └─ Tab 2: "Semi-final Materials" (Updated Pitch, Video, Financials from Mar) +│ └─ 10 projects advance (status = PASSED) +│ +├─ Round 6: SUBMISSION ◄──── SECOND SUBMISSION ROUND +│ └─ SubmissionWindow 3: "Finalist Presentations" +│ ├─ Opens: Apr 1 (Window 2 auto-locks) +│ ├─ Close: Apr 10 +│ ├─ Late Policy: FLAG (late submissions marked) +│ ├─ Eligible: 10 projects with status=PASSED from Round 5 +│ ├─ Requirements: +│ │ ├─ Final Pitch Deck (PDF/PPTX, required, max 20MB) +│ │ ├─ 3-Minute Video (MP4, required, max 150MB) +│ │ └─ Impact Report (PDF/DOCX, required, max 10MB) +│ └─ Status: OPEN (10 eligible projects can submit) +│ +└─ Round 7: LIVE_FINAL + ├─ Visibility: Window 1, Window 2, AND Window 3 + ├─ Jury sees: + │ ├─ Tab 1: "Original Application" (Jan docs) + │ ├─ Tab 2: "Semi-final Submission" (Mar docs) + │ └─ Tab 3: "Finalist Presentation" (Apr docs) + └─ 3 winners selected +``` + +**Key Rules**: + +1. **One Window Per Round**: Each SUBMISSION/INTAKE round creates exactly ONE SubmissionWindow +2. **Never Delete Windows**: Windows persist forever (audit trail), only lock/unlock +3. **Applicant Access: One-Way Lock**: Can only go from READ-WRITE → READ-ONLY (never reverses) +4. **Admin Access: Always Full**: Admins can upload/delete in any window regardless of lock state +5. **Jury Visibility: Explicit Declaration**: Must create RoundSubmissionVisibility records + +### 2.4 Locking Mechanism Implementation + +**When a new SubmissionWindow opens**: + +```typescript +async function openSubmissionWindow(windowId: string, ctx: Context) { + const window = await ctx.prisma.submissionWindow.findUnique({ + where: { id: windowId }, + include: { + round: { + select: { + configJson: true, + competitionId: true + } + } + } + }); + + if (!window) throw new Error("Window not found"); + + const config = window.round.configJson as SubmissionConfig; + + // Step 1: Set this window's openDate to now + await ctx.prisma.submissionWindow.update({ + where: { id: windowId }, + data: { openDate: new Date() } + }); + + // Step 2: Lock previous windows if config says so + if (config.lockPreviousWindows) { + const allWindows = await ctx.prisma.submissionWindow.findMany({ + where: { + competitionId: window.competitionId, + openDate: { lt: new Date() } // Opened before now + }, + select: { id: true, isLocked: true } + }); + + for (const prevWindow of allWindows) { + if (!prevWindow.isLocked) { + await ctx.prisma.submissionWindow.update({ + where: { id: prevWindow.id }, + data: { + isLocked: true, + lockDate: new Date() + } + }); + } + } + } + + // Step 3: Notify eligible teams + if (config.notifyEligibleTeams) { + await notifyEligibleTeams(windowId, ctx); + } + + // Step 4: Audit log + await ctx.prisma.decisionAuditLog.create({ + data: { + action: "SUBMISSION_WINDOW_OPENED", + userId: ctx.session.user.id, + entityType: "SubmissionWindow", + entityId: windowId, + metadata: { + windowName: window.name, + openDate: new Date(), + previousWindowsLocked: config.lockPreviousWindows + } + } + }); +} +``` + +**Upload Permission Check**: + +```typescript +async function checkUploadPermission( + projectId: string, + windowId: string, + userId: string, + ctx: Context +): Promise<{ allowed: boolean; reason?: string }> { + const user = await ctx.prisma.user.findUnique({ + where: { id: userId }, + select: { role: true } + }); + + // Admins bypass all checks + if (user?.role === "SUPER_ADMIN" || user?.role === "PROGRAM_ADMIN") { + return { allowed: true }; + } + + // Check 1: User is applicant for this project? + const project = await ctx.prisma.project.findFirst({ + where: { + id: projectId, + applicantId: userId + } + }); + + if (!project) { + return { allowed: false, reason: "Unauthorized: You do not own this project" }; + } + + // Check 2: Fetch window + const window = await ctx.prisma.submissionWindow.findUnique({ + where: { id: windowId } + }); + + if (!window) { + return { allowed: false, reason: "Submission window not found" }; + } + + // Check 3: Window locked? + if (window.isLocked) { + return { allowed: false, reason: "This submission window is now closed." }; + } + + const now = new Date(); + + // Check 4: Window not yet open? + if (now < window.openDate) { + return { allowed: false, reason: "Submission window has not opened yet." }; + } + + // Check 5: Deadline enforcement + if (now > window.closeDate) { + switch (window.latePolicy) { + case "HARD": + return { allowed: false, reason: "Submission deadline has passed. No late submissions allowed." }; + + case "FLAG": + // Allow upload, will be marked as late + return { allowed: true }; + + case "GRACE": + if (window.lockDate && now > window.lockDate) { + return { allowed: false, reason: "Grace period has ended. Submissions are now closed." }; + } + // Within grace period + return { allowed: true }; + } + } + + // All checks passed + return { allowed: true }; +} +``` + +### 2.5 File Organization by Window + +**Database Structure**: + +```typescript +// Project: proj_abc123 +// Competition with 3 submission windows + +// Window 1: Application Documents (Jan) +ProjectFile { + id: "file_001" + projectId: "proj_abc123" + submissionWindowId: "window_1" + requirementId: "req_pitch_deck_w1" + filename: "OceanCleanup_Pitch.pdf" + uploadedAt: "2026-01-25T14:30:00Z" + uploadedBy: "applicant_user_id" + isLate: false +} + +ProjectFile { + id: "file_002" + projectId: "proj_abc123" + submissionWindowId: "window_1" + requirementId: "req_budget_w1" + filename: "Budget_2026.xlsx" + uploadedAt: "2026-02-01T09:15:00Z" + uploadedBy: "applicant_user_id" + isLate: false +} + +// Window 2: Semi-finalist Materials (Mar) +ProjectFile { + id: "file_003" + projectId: "proj_abc123" + submissionWindowId: "window_2" + requirementId: "req_video_w2" + filename: "Pitch_Video.mp4" + uploadedAt: "2026-03-10T16:45:00Z" + uploadedBy: "applicant_user_id" + isLate: false +} + +ProjectFile { + id: "file_004" + projectId: "proj_abc123" + submissionWindowId: "window_2" + requirementId: "req_updated_deck_w2" + filename: "OceanCleanup_Pitch_v2.pdf" + uploadedAt: "2026-03-15T23:59:00Z" + uploadedBy: "admin_user_id" // Admin uploaded on behalf + isLate: false +} + +// Window 3: Finalist Presentation (Apr) +ProjectFile { + id: "file_005" + projectId: "proj_abc123" + submissionWindowId: "window_3" + requirementId: "req_final_deck_w3" + filename: "OceanCleanup_Final.pdf" + uploadedAt: "2026-04-09T18:20:00Z" + uploadedBy: "applicant_user_id" + isLate: false +} + +ProjectFile { + id: "file_006" + projectId: "proj_abc123" + submissionWindowId: "window_3" + requirementId: "req_impact_report_w3" + filename: "Impact_Report.pdf" + uploadedAt: "2026-04-11T10:30:00Z" // After deadline (Apr 10) + uploadedBy: "applicant_user_id" + isLate: true // Marked late (FLAG policy) +} +``` + +**Query Pattern for Jury View** (EVALUATION Round 2): + +```typescript +// Fetch all visible files for a project in an evaluation round +const visibleWindows = await ctx.prisma.roundSubmissionVisibility.findMany({ + where: { evaluationRoundId: "eval_round_2" }, + include: { + submissionWindow: { + include: { + fileRequirements: { + orderBy: { displayOrder: "asc" } + } + } + } + }, + orderBy: { displayOrder: "asc" } +}); + +// Returns: +// [ +// { +// id: "vis_1", +// submissionWindow: { +// id: "window_1", +// name: "Application Documents", +// fileRequirements: [...] +// }, +// displayLabel: "Round 1 Application", +// displayOrder: 1 +// }, +// { +// id: "vis_2", +// submissionWindow: { +// id: "window_2", +// name: "Semi-finalist Materials", +// fileRequirements: [...] +// }, +// displayLabel: "Semi-final Submissions", +// displayOrder: 2 +// } +// ] + +const windowIds = visibleWindows.map(v => v.submissionWindowId); + +const files = await ctx.prisma.projectFile.findMany({ + where: { + projectId: "proj_abc123", + submissionWindowId: { in: windowIds }, + supersededBy: null // Only current versions + }, + include: { + requirement: true, + submissionWindow: true, + uploadedByUser: { + select: { name: true, role: true } + } + } +}); + +// Group by window +const filesByWindow = visibleWindows.map(vis => ({ + windowId: vis.submissionWindowId, + windowName: vis.displayLabel, + displayOrder: vis.displayOrder, + files: files.filter(f => f.submissionWindowId === vis.submissionWindowId) +})); +``` + +--- + +## 3. SubmissionConfig Shape + +### 3.1 Type Definition + +```typescript +/** + * Configuration for SUBMISSION round type + * Stored in Round.configJson for rounds with type = "SUBMISSION" + */ +type SubmissionConfig = { + /** + * Which project statuses from the PREVIOUS round are eligible to submit + * + * Common values: + * - ["PASSED"] → Only projects that passed previous evaluation + * - ["PASSED", "CONDITIONAL"] → Passed + conditionally advanced + * - ["WINNER", "FINALIST"] → For post-award deliverables + * + * Default: ["PASSED"] + */ + eligibleStatuses: ProjectRoundStateValue[]; + + /** + * Send email + in-app notifications when submission window opens + * + * If true: + * - Sends to all eligible project applicants + * - Includes deadline, requirements list, upload link + * - Uses template from notificationTemplate if provided + * + * Default: true + */ + notifyEligibleTeams: boolean; + + /** + * Lock all previous submission windows when this round starts + * + * If true: + * - All windows with openDate < current window's openDate + * - Set isLocked = true, lockDate = now + * - Applicants can no longer upload/delete (read-only) + * - Admins retain full control + * + * Default: true + */ + lockPreviousWindows: boolean; + + /** + * Optional: Custom email template for notifications + * + * Variables available: + * - {projectName}, {teamName}, {deadline}, {windowName} + * - {requirementsList}, {uploadUrl} + */ + notificationTemplate?: { + subject: string; + bodyHtml: string; + variables: Record; + }; + + /** + * Optional: Submission window configuration + * (Can also be set separately via SubmissionWindow model) + */ + windowConfig?: { + name: string; + description: string; + openDate: string; // ISO 8601 + closeDate: string; // ISO 8601 + latePolicy: "HARD" | "FLAG" | "GRACE"; + gracePeriodHours?: number; + }; + + /** + * Optional: File requirements + * (Can also be set separately via SubmissionFileRequirement model) + */ + fileRequirements?: Array<{ + label: string; + description?: string; + isRequired: boolean; + allowedFileTypes: string[]; // ["pdf", "docx", "mp4"] + maxSizeMB: number; + displayOrder: number; + }>; +}; +``` + +### 3.2 Example Configurations + +**Example 1: Simple Semi-Finalist Submission** + +```json +{ + "eligibleStatuses": ["PASSED"], + "notifyEligibleTeams": true, + "lockPreviousWindows": true, + "windowConfig": { + "name": "Semi-Finalist Documents", + "description": "Congratulations on advancing! Please submit the following materials.", + "openDate": "2026-03-01T00:00:00Z", + "closeDate": "2026-03-15T23:59:59Z", + "latePolicy": "HARD" + }, + "fileRequirements": [ + { + "label": "3-Minute Video Pitch", + "description": "MP4 format, max 100MB. Introduce your team and demonstrate your solution.", + "isRequired": true, + "allowedFileTypes": ["mp4", "mov"], + "maxSizeMB": 100, + "displayOrder": 1 + }, + { + "label": "Updated Pitch Deck", + "description": "PDF format. Include any updates since your initial application.", + "isRequired": true, + "allowedFileTypes": ["pdf"], + "maxSizeMB": 10, + "displayOrder": 2 + }, + { + "label": "Financial Projections", + "description": "Excel or PDF. 3-year revenue and cost forecast with assumptions.", + "isRequired": true, + "allowedFileTypes": ["xlsx", "pdf"], + "maxSizeMB": 5, + "displayOrder": 3 + } + ] +} +``` + +**Example 2: Flexible Finalist Submission with Grace Period** + +```json +{ + "eligibleStatuses": ["PASSED", "CONDITIONAL"], + "notifyEligibleTeams": true, + "lockPreviousWindows": true, + "windowConfig": { + "name": "Finalist Presentation Materials", + "description": "Final round submissions for live presentations.", + "openDate": "2026-04-01T00:00:00Z", + "closeDate": "2026-04-10T23:59:59Z", + "latePolicy": "GRACE", + "gracePeriodHours": 48 + }, + "fileRequirements": [ + { + "label": "Final Pitch Deck", + "description": "PDF or PowerPoint, max 20 slides", + "isRequired": true, + "allowedFileTypes": ["pdf", "pptx"], + "maxSizeMB": 15, + "displayOrder": 1 + }, + { + "label": "Impact Report", + "description": "Summary of expected environmental impact (PDF or Word)", + "isRequired": true, + "allowedFileTypes": ["pdf", "docx"], + "maxSizeMB": 10, + "displayOrder": 2 + }, + { + "label": "Team Photo", + "description": "High-resolution team photo for program materials (optional)", + "isRequired": false, + "allowedFileTypes": ["jpg", "png"], + "maxSizeMB": 5, + "displayOrder": 3 + } + ], + "notificationTemplate": { + "subject": "🎉 You're a Finalist! Submit Your Final Materials", + "bodyHtml": "

Dear {teamName},

Congratulations on reaching the finals!

Please submit your materials by {deadline}.

", + "variables": { + "teamName": "project.name", + "deadline": "window.closeDate" + } + } +} +``` + +**Example 3: Post-Award Deliverables (Don't Lock Previous Windows)** + +```json +{ + "eligibleStatuses": ["WINNER", "FINALIST"], + "notifyEligibleTeams": true, + "lockPreviousWindows": false, + "windowConfig": { + "name": "Winner Deliverables", + "description": "Required documentation for prize disbursement and program promotion.", + "openDate": "2026-06-01T00:00:00Z", + "closeDate": "2026-06-30T23:59:59Z", + "latePolicy": "FLAG" + }, + "fileRequirements": [ + { + "label": "W-9 Tax Form", + "description": "Required for prize payment (US teams only)", + "isRequired": true, + "allowedFileTypes": ["pdf"], + "maxSizeMB": 2, + "displayOrder": 1 + }, + { + "label": "High-Res Logo", + "description": "Vector format (SVG preferred) or high-res PNG (min 2000px width)", + "isRequired": true, + "allowedFileTypes": ["svg", "png", "ai"], + "maxSizeMB": 10, + "displayOrder": 2 + }, + { + "label": "Success Story", + "description": "500-word story about your project for our website and press releases", + "isRequired": true, + "allowedFileTypes": ["pdf", "docx"], + "maxSizeMB": 2, + "displayOrder": 3 + }, + { + "label": "Promotional Video", + "description": "Optional: 1-2 minute video for social media", + "isRequired": false, + "allowedFileTypes": ["mp4", "mov"], + "maxSizeMB": 200, + "displayOrder": 4 + } + ] +} +``` + +### 3.3 Validation Schema + +```typescript +import { z } from "zod"; + +const submissionConfigSchema = z.object({ + eligibleStatuses: z.array( + z.enum([ + "DRAFT", + "SUBMITTED", + "UNDER_REVIEW", + "PASSED", + "FAILED", + "CONDITIONAL", + "WITHDRAWN", + "WINNER", + "FINALIST" + ]) + ).min(1, "Must specify at least one eligible status"), + + notifyEligibleTeams: z.boolean(), + + lockPreviousWindows: z.boolean(), + + notificationTemplate: z.object({ + subject: z.string().min(1).max(200), + bodyHtml: z.string().min(1), + variables: z.record(z.string()) + }).optional(), + + windowConfig: z.object({ + name: z.string().min(1).max(100), + description: z.string().max(1000).optional(), + openDate: z.string().datetime(), + closeDate: z.string().datetime(), + latePolicy: z.enum(["HARD", "FLAG", "GRACE"]), + gracePeriodHours: z.number().int().min(1).max(168).optional() + }).refine( + (data) => new Date(data.closeDate) > new Date(data.openDate), + { message: "closeDate must be after openDate" } + ).refine( + (data) => data.latePolicy !== "GRACE" || data.gracePeriodHours !== undefined, + { message: "gracePeriodHours required when latePolicy is GRACE" } + ).optional(), + + fileRequirements: z.array( + z.object({ + label: z.string().min(1).max(100), + description: z.string().max(500).optional(), + isRequired: z.boolean(), + allowedFileTypes: z.array(z.string()).min(1), + maxSizeMB: z.number().int().min(1).max(500), + displayOrder: z.number().int().min(0) + }) + ).optional() +}); + +type SubmissionConfig = z.infer; +``` + +--- + +## 4. Applicant Experience (Detailed) + +### 4.1 Dashboard Before SUBMISSION Round Opens + +**Applicant sees (after advancing from Round 1)**: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Monaco Ocean Protection Challenge 2026 │ +│ │ +│ Project: OceanCleanup AI │ +│ Status: 🎉 Semi-Finalist (Advancing to Round 2) │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ 📄 Round 1: Application Documents (Submitted) │ +│ │ +│ ✅ Pitch Deck │ +│ Filename: OceanCleanup_Pitch.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ [View] [Download] [Replace] ← Can still edit │ +│ │ +│ ✅ Budget │ +│ Filename: Budget_2026.xlsx │ +│ Uploaded: Feb 1, 2026 at 9:15 AM │ +│ [View] [Download] [Replace] │ +│ │ +│ ✅ Team CV │ +│ Filename: Team_Bios.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ [View] [Download] [Replace] │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ ⏳ Next Steps │ +│ │ +│ Congratulations on advancing to the semi-finals! │ +│ │ +│ Additional submission requirements will be announced soon. │ +│ You will receive an email notification when the next │ +│ submission window opens. │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Notes**: +- All Round 1 documents are **still editable** (window not locked yet) +- No indication of upcoming requirements +- "Semi-Finalist" badge visible in project status +- Replace buttons are active + +### 4.2 Dashboard After SUBMISSION Round Opens + +**When Window 2 opens (March 1, 2026), applicant sees**: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Monaco Ocean Protection Challenge 2026 │ +│ │ +│ Project: OceanCleanup AI │ +│ Status: 🎉 Semi-Finalist (Round 2 Submission Open) │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ 🔒 Round 1: Application Documents (Locked) │ +│ │ +│ These documents were submitted for Round 1 and are now │ +│ locked. You can view and download them, but cannot make │ +│ changes. Admins retain the ability to manage these files │ +│ on your behalf if needed. │ +│ │ +│ ✅ Pitch Deck │ +│ Filename: OceanCleanup_Pitch.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ [View] [Download] ← No Replace button │ +│ │ +│ ✅ Budget │ +│ Filename: Budget_2026.xlsx │ +│ Uploaded: Feb 1, 2026 at 9:15 AM │ +│ [View] [Download] │ +│ │ +│ ✅ Team CV │ +│ Filename: Team_Bios.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ [View] [Download] │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ 📤 Round 2: Semi-Finalist Materials │ +│ Deadline: March 15, 2026 at 11:59 PM CET │ +│ ⏰ 14 days, 15 hours remaining │ +│ │ +│ Progress: 0 of 3 required files submitted │ +│ [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0% │ +│ │ +│ Congratulations on advancing! Please submit the following │ +│ materials by March 15. │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ❌ 3-Minute Video Pitch (Required) │ +│ MP4 format, max 100MB. Introduce your team and │ +│ demonstrate your solution. │ +│ │ +│ Not uploaded │ +│ [Choose File] or Drag & Drop Here │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ❌ Updated Pitch Deck (Required) │ +│ PDF format. Include any updates since your initial │ +│ application. │ +│ │ +│ Not uploaded │ +│ [Choose File] or Drag & Drop Here │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ❌ Financial Projections (Required) │ +│ Excel or PDF. 3-year revenue and cost forecast with │ +│ assumptions. │ +│ │ +│ Not uploaded │ +│ [Choose File] or Drag & Drop Here │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**UI Changes**: +1. Round 1 section shows **🔒 lock icon** in header +2. All **Replace/Delete buttons removed** for Window 1 files +3. **New Round 2 section appears** with upload slots +4. **Countdown timer** shows time remaining +5. **Progress bar** shows completion status +6. Red **❌ indicators** for missing required files + +### 4.3 File Upload Flow (Detailed) + +**Step 1: User clicks "Choose File" for a requirement** + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Upload: 3-Minute Video Pitch │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ Requirements: │ +│ • Accepted file types: MP4, MOV │ +│ • Maximum file size: 100 MB │ +│ • This file is REQUIRED │ +│ │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Drag and drop your file here │ │ +│ │ or │ │ +│ │ Click to Browse │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ │ +│ Description: │ +│ Introduce your team and demonstrate your solution. Show │ +│ how your technology works and its potential impact. │ +│ │ +│ [Cancel] [Upload] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Step 2: File selected, validation in progress** + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Upload: 3-Minute Video Pitch │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ✅ File selected: Pitch_Video.mp4 │ +│ Size: 85.2 MB (within 100 MB limit) │ +│ Type: video/mp4 ✓ │ +│ │ +│ Validating... │ +│ │ +│ [████████████████████░░░░] 88% Uploading │ +│ │ +│ [Cancel Upload] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Step 3: Upload complete** + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📤 Round 2: Semi-Finalist Materials │ +│ Deadline: March 15, 2026 at 11:59 PM CET │ +│ ⏰ 14 days, 14 hours remaining │ +│ │ +│ Progress: 1 of 3 required files submitted │ +│ [██████████░░░░░░░░░░░░░░░░░░░░░░░] 33% │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ✅ 3-Minute Video Pitch (Required) │ +│ MP4 format, max 100MB │ +│ │ +│ Filename: Pitch_Video.mp4 │ +│ Size: 85.2 MB │ +│ Uploaded: Mar 1, 2026 at 10:30 AM │ +│ [View] [Download] [Replace] [Delete] │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ❌ Updated Pitch Deck (Required) │ +│ PDF format │ +│ [Choose File] or Drag & Drop Here │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ❌ Financial Projections (Required) │ +│ Excel or PDF │ +│ [Choose File] or Drag & Drop Here │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Validation Error Example** (file too large): + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ❌ Upload Failed │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ File: Pitch_Video_HD.mp4 │ +│ Size: 152.8 MB │ +│ │ +│ Error: File size exceeds the maximum limit of 100 MB. │ +│ │ +│ Please compress your video or upload a smaller version. │ +│ │ +│ Tip: You can use free tools like HandBrake to compress │ +│ video files while maintaining quality. │ +│ │ +│ [OK] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Validation Error Example** (wrong file type): + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ❌ Upload Failed │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ File: Budget_Report.docx │ +│ Type: application/vnd.openxmlformats-officedocument... │ +│ │ +│ Error: File type not accepted for this requirement. │ +│ │ +│ Accepted types: PDF, Excel (XLSX) │ +│ │ +│ Please convert your document to PDF or Excel format and │ +│ try again. │ +│ │ +│ [OK] │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 4.4 Deadline Countdown UI States + +**14 days before deadline (Normal)**: +``` +⏰ 14 days, 15 hours remaining +``` + +**7 days before deadline (Normal)**: +``` +⏰ 7 days remaining +``` + +**3 days before deadline (Warning)**: +``` +⚠️ 3 days remaining — Please submit soon! +[Highlighted in yellow] +``` + +**24 hours before deadline (Urgent)**: +``` +🚨 URGENT: Less than 1 day remaining + Deadline: Tomorrow at 11:59 PM +[Highlighted in orange] +``` + +**6 hours before deadline (Critical)**: +``` +🚨 CRITICAL: 6 hours remaining + Deadline: Today at 11:59 PM +[Highlighted in red, pulsing animation] +``` + +**After deadline (HARD policy)**: +``` +❌ Deadline passed: March 15, 2026 at 11:59 PM + Submissions are no longer accepted. + + If you believe this is an error, please contact the + program administrator. + + [Contact Admin] +``` + +**After deadline (FLAG policy)**: +``` +⚠️ Deadline passed: March 15, 2026 at 11:59 PM + Late submissions will be flagged and may impact your + evaluation. + + You can still submit, but your files will be marked as + late and the jury will be notified. + + [Upload File] (Late submission) +``` + +**After deadline, within grace period (GRACE policy)**: +``` +⏳ Grace Period Active + Deadline was: March 15, 2026 at 11:59 PM + Grace period ends: March 17, 2026 at 11:59 PM + + ⏰ 1 day, 23 hours remaining in grace period + + You can still submit without penalty during this time. + + [Upload File] +``` + +**After grace period ends (GRACE policy)**: +``` +❌ Grace period ended: March 17, 2026 at 11:59 PM + Submissions are now closed. + + If you have extenuating circumstances, please contact + the program administrator to request an extension. + + [Contact Admin] +``` + +### 4.5 Completion Status Indicators + +**Incomplete (missing required files)**: +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📤 Round 2: Semi-Finalist Materials │ +│ Deadline: March 15, 2026 at 11:59 PM CET │ +│ │ +│ Status: ⚠️ INCOMPLETE │ +│ 1 of 3 required files submitted │ +│ │ +│ [██████████░░░░░░░░░░░░░░░░░░░░░░░] 33% │ +│ │ +│ You still need to submit: │ +│ • Updated Pitch Deck (required) │ +│ • Financial Projections (required) │ +│ │ +│ ⏰ 12 days remaining │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Complete (all required files submitted)**: +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📤 Round 2: Semi-Finalist Materials │ +│ Deadline: March 15, 2026 at 11:59 PM CET │ +│ │ +│ Status: ✅ COMPLETE │ +│ 3 of 3 required files submitted │ +│ │ +│ [██████████████████████████████████████] 100% │ +│ │ +│ All required files have been submitted. You can still │ +│ update or replace files until the deadline. │ +│ │ +│ ⏰ 12 days remaining │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Complete with late submissions**: +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📤 Round 2: Semi-Finalist Materials │ +│ Deadline: March 15, 2026 at 11:59 PM CET (PASSED) │ +│ │ +│ Status: ⚠️ COMPLETE (1 file submitted late) │ +│ 3 of 3 required files submitted │ +│ │ +│ [██████████████████████████████████████] 100% │ +│ │ +│ All files submitted, but the Financial Projections file │ +│ was submitted after the deadline. This has been flagged │ +│ and the jury will be notified during evaluation. │ +│ │ +│ Submitted late: │ +│ • Financial Projections (submitted Mar 16 at 2:15 PM) │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Complete with optional files missing**: +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📤 Round 2: Semi-Finalist Materials │ +│ Deadline: March 15, 2026 at 11:59 PM CET │ +│ │ +│ Status: ✅ COMPLETE │ +│ 3 of 3 required files submitted │ +│ 0 of 1 optional files submitted │ +│ │ +│ All required files submitted. Optional: │ +│ ○ Team Photos (optional, not submitted) │ +│ │ +│ ⏰ 12 days remaining │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 4.6 Email Notifications + +**Email 1: Window Opening Notification** + +``` +From: Monaco Ocean Protection Challenge +To: team@oceancleanup.ai +Subject: 🎉 You're a Semi-Finalist! Submit Your Round 2 Materials +Date: March 1, 2026 at 9:00 AM + +─────────────────────────────────────────────────────────── + +Dear OceanCleanup AI Team, + +Congratulations on advancing to the semi-finals of the Monaco +Ocean Protection Challenge 2026! + +You have been selected from 150 applicants to advance to the +next round. We were impressed by your innovative approach to +ocean conservation. + +NEXT STEPS: SUBMIT ROUND 2 MATERIALS + +To continue in the competition, please submit the following +documents by: + + 📅 DEADLINE: March 15, 2026 at 11:59 PM CET + +Required Materials: +✓ 3-Minute Video Pitch (MP4, max 100MB) + Introduce your team and demonstrate your solution + +✓ Updated Pitch Deck (PDF, max 10MB) + Include any updates since your initial application + +✓ Financial Projections (Excel or PDF, max 5MB) + 3-year revenue and cost forecast with assumptions + +────────────────────────────────────────────────────────── + +[Upload Documents →] + +────────────────────────────────────────────────────────── + +IMPORTANT NOTES: + +• Your Round 1 application documents are now locked and + cannot be edited. They will remain available for viewing. + +• You have 14 days to submit your materials. + +• All required files must be submitted by the deadline. + +• You can update or replace files at any time before the + deadline. + +If you have any questions or encounter technical difficulties, +please contact us at support@monaco-opc.com. + +Best regards, +Monaco Ocean Protection Challenge Team + +─────────────────────────────────────────────────────────── +``` + +**Email 2: Reminder (7 days before)** + +``` +From: Monaco Ocean Protection Challenge +To: team@oceancleanup.ai +Subject: ⏰ Reminder: Semi-Finalist Materials Due in 7 Days +Date: March 8, 2026 at 9:00 AM + +─────────────────────────────────────────────────────────── + +Dear OceanCleanup AI Team, + +This is a friendly reminder that your semi-finalist materials +are due in 7 days. + +DEADLINE: March 15, 2026 at 11:59 PM CET + +Current Status: 1 of 3 required files submitted ⚠️ + +Missing Files: +❌ Updated Pitch Deck (PDF, required) +❌ Financial Projections (Excel/PDF, required) + +────────────────────────────────────────────────────────── + +[Complete Your Submission →] + +────────────────────────────────────────────────────────── + +Don't wait until the last minute! Upload your remaining +documents now to ensure you don't miss the deadline. + +Best regards, +Monaco Ocean Protection Challenge Team +``` + +**Email 3: Urgent Reminder (24 hours before)** + +``` +From: Monaco Ocean Protection Challenge +To: team@oceancleanup.ai +Subject: 🚨 URGENT: Semi-Finalist Materials Due Tomorrow +Date: March 14, 2026 at 9:00 AM + +─────────────────────────────────────────────────────────── + +Dear OceanCleanup AI Team, + +URGENT: Your semi-finalist materials are due TOMORROW +(March 15) at 11:59 PM CET. + +Current Status: 2 of 3 required files submitted ⚠️ + +Missing Files: +❌ Financial Projections (Excel/PDF, REQUIRED) + +────────────────────────────────────────────────────────── + +[Upload Missing File Now →] + +────────────────────────────────────────────────────────── + +PLEASE ACT IMMEDIATELY. Incomplete submissions may result +in disqualification from the competition. + +If you are experiencing technical difficulties, contact us +immediately at support@monaco-opc.com or call +377 XXX XXX. + +Best regards, +Monaco Ocean Protection Challenge Team +``` + +**Email 4: Late Submission Warning (FLAG policy)** + +``` +From: Monaco Ocean Protection Challenge +To: team@oceancleanup.ai +Subject: ⚠️ Late Submission Notice +Date: March 16, 2026 at 10:15 AM + +─────────────────────────────────────────────────────────── + +Dear OceanCleanup AI Team, + +We received your Financial Projections file on March 16 at +2:15 PM, which was after the deadline of March 15 at 11:59 PM. + +Your submission has been marked as LATE and flagged in our +system. The jury will be notified of the late submission +during evaluation, which may impact your score. + +While we understand that unexpected circumstances can arise, +please be mindful of deadlines in future rounds. + +Your submission is now complete. Good luck in the next round! + +Best regards, +Monaco Ocean Protection Challenge Team +``` + +--- + +## 5. Jury Cross-Round Visibility (Detailed) + +### 5.1 RoundSubmissionVisibility Configuration + +**Purpose**: Control which EVALUATION rounds can see which SubmissionWindows. + +**Configuration Example**: + +```typescript +// Evaluation Round 1: Jury Screening (sees only Window 1) +await prisma.roundSubmissionVisibility.create({ + data: { + evaluationRoundId: "eval_round_1", + submissionWindowId: "window_1", + displayLabel: "Application Documents", + displayOrder: 1 + } +}); + +// Evaluation Round 2: Jury Semi-Finals (sees Window 1 + Window 2) +await prisma.roundSubmissionVisibility.createMany({ + data: [ + { + evaluationRoundId: "eval_round_2", + submissionWindowId: "window_1", + displayLabel: "Round 1 Application", + displayOrder: 1 + }, + { + evaluationRoundId: "eval_round_2", + submissionWindowId: "window_2", + displayLabel: "Semi-Final Materials", + displayOrder: 2 + } + ] +}); + +// Evaluation Round 3: Jury Finals (sees all three windows) +await prisma.roundSubmissionVisibility.createMany({ + data: [ + { + evaluationRoundId: "eval_round_3", + submissionWindowId: "window_1", + displayLabel: "Original Application (Jan)", + displayOrder: 1 + }, + { + evaluationRoundId: "eval_round_3", + submissionWindowId: "window_2", + displayLabel: "Semi-Final Submission (Mar)", + displayOrder: 2 + }, + { + evaluationRoundId: "eval_round_3", + submissionWindowId: "window_3", + displayLabel: "Finalist Presentation (Apr)", + displayOrder: 3 + } + ] +}); +``` + +### 5.2 Jury Evaluation View (Round 1 - Single Window) + +**Jury sees ONLY Window 1**: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Evaluating: OceanCleanup AI │ +│ Round: Jury Screening (Round 1) │ +│ Assigned: Feb 10, 2026 │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ 📄 Application Documents │ +│ │ +│ Pitch Deck │ +│ Filename: OceanCleanup_Pitch.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ Size: 2.4 MB │ +│ [View] [Download] │ +│ │ +│ Budget │ +│ Filename: Budget_2026.xlsx │ +│ Uploaded: Feb 1, 2026 at 9:15 AM │ +│ Size: 850 KB │ +│ [View] [Download] │ +│ │ +│ Team CV │ +│ Filename: Team_Bios.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ Size: 1.2 MB │ +│ [View] [Download] │ +│ │ +│ [Download All Files (ZIP)] │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ Your Evaluation │ +│ │ +│ Impact Score (1-10): [_____] │ +│ Feasibility Score (1-10): [_____] │ +│ Innovation Score (1-10): [_____] │ +│ │ +│ Comments: │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ │ +│ Recommendation: │ +│ ( ) Pass ( ) Fail ( ) Conditional │ +│ │ +│ [Save Draft] [Submit Evaluation] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Notes**: +- Jury does NOT see that Window 2 exists +- No indication of future submission rounds +- Clean, focused evaluation on Round 1 materials only +- UI is simple and uncluttered + +### 5.3 Jury Evaluation View (Round 2 - Multi-Window) + +**Jury sees BOTH Window 1 and Window 2**: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Evaluating: OceanCleanup AI │ +│ Round: Semi-Final Evaluation (Round 2) │ +│ Assigned: Mar 20, 2026 │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ 📂 Project Documents │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ [ Round 1 Application ] [ Semi-Final Materials ] │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ ▲ Active tab │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ Tab 1 Active: "Round 1 Application" │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 📄 Round 1 Application │ +│ │ +│ These documents were submitted during the initial │ +│ application phase (January 2026). │ +│ │ +│ Pitch Deck │ +│ Filename: OceanCleanup_Pitch.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ Size: 2.4 MB │ +│ [View] [Download] │ +│ │ +│ Budget │ +│ Filename: Budget_2026.xlsx │ +│ Uploaded: Feb 1, 2026 at 9:15 AM │ +│ Size: 850 KB │ +│ [View] [Download] │ +│ │ +│ Team CV │ +│ Filename: Team_Bios.pdf │ +│ Uploaded: Jan 25, 2026 at 2:30 PM │ +│ Size: 1.2 MB │ +│ [View] [Download] │ +│ │ +│ [Download All Round 1 Files (ZIP)] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Click "Semi-Final Materials" tab**: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📂 Project Documents │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ [ Round 1 Application ] [ Semi-Final Materials ] │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ ▲ Active tab │ +└─────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────┐ +│ Tab 2 Active: "Semi-Final Materials" │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 📄 Semi-Final Materials │ +│ │ +│ These documents were submitted for the semi-final │ +│ evaluation round (March 2026). │ +│ │ +│ 3-Minute Video Pitch │ +│ Filename: Pitch_Video.mp4 │ +│ Uploaded: Mar 1, 2026 at 10:30 AM │ +│ Size: 85.2 MB │ +│ [View] [Download] │ +│ │ +│ Updated Pitch Deck │ +│ Filename: OceanCleanup_Pitch_v2.pdf │ +│ Uploaded: Mar 10, 2026 at 4:20 PM │ +│ Size: 3.1 MB │ +│ [View] [Download] │ +│ │ +│ Financial Projections │ +│ Filename: Financials_2026.xlsx │ +│ Uploaded: Mar 16, 2026 at 2:15 PM ⚠️ LATE SUBMISSION │ +│ Size: 1.5 MB │ +│ [View] [Download] │ +│ ⚠️ This file was submitted after the deadline of Mar 15 │ +│ │ +│ [Download All Round 2 Files (ZIP)] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Evaluation Form (Below Documents)**: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Your Evaluation │ +│ │ +│ ℹ️ Please evaluate based on ALL submitted materials │ +│ (both Round 1 and Round 2 documents). │ +│ │ +│ Business Model Score (1-10): [_____] │ +│ Team Strength Score (1-10): [_____] │ +│ Presentation Quality (1-10): [_____] │ +│ Financial Viability (1-10): [_____] │ +│ │ +│ Comments: │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ │ +│ Recommendation: │ +│ ( ) Pass ( ) Fail ( ) Conditional │ +│ │ +│ ⚠️ Note: Financial Projections was submitted late. │ +│ │ +│ [Save Draft] [Submit Evaluation] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**UI Enhancements**: +1. **Tab Navigation**: Clear separation between submission windows +2. **Context Labels**: Each tab shows description and submission date range +3. **Late Indicators**: Flagged submissions clearly visible +4. **Download Options**: Bulk download per window or all files +5. **Submission Metadata**: Upload dates, file sizes, uploaders visible +6. **Badge Indicators**: Late submissions have ⚠️ warning badge + +### 5.4 Query Implementation for Jury View + +```typescript +// src/server/routers/evaluation.ts + +export const evaluationRouter = router({ + /** + * Get all visible files for a project in an evaluation round + */ + getVisibleFilesForProject: juryProcedure + .input(z.object({ + projectId: z.string().cuid(), + evaluationRoundId: z.string().cuid() + })) + .query(async ({ input, ctx }) => { + // Step 1: Get visible windows for this evaluation round + const visibleWindows = await ctx.prisma.roundSubmissionVisibility.findMany({ + where: { evaluationRoundId: input.evaluationRoundId }, + include: { + submissionWindow: { + include: { + fileRequirements: { + orderBy: { displayOrder: "asc" } + } + } + } + }, + orderBy: { displayOrder: "asc" } + }); + + if (visibleWindows.length === 0) { + throw new TRPCError({ + code: "NOT_FOUND", + message: "No submission windows configured for this evaluation round" + }); + } + + // Step 2: Fetch files for each visible window + const filesByWindow = await Promise.all( + visibleWindows.map(async (visibility) => { + const files = await ctx.prisma.projectFile.findMany({ + where: { + projectId: input.projectId, + submissionWindowId: visibility.submissionWindowId, + supersededBy: null // Only current versions + }, + include: { + requirement: true, + uploadedByUser: { + select: { + name: true, + email: true, + role: true + } + } + }, + orderBy: { requirement: { displayOrder: "asc" } } + }); + + // Generate download URLs + const filesWithUrls = await Promise.all( + files.map(async (file) => ({ + id: file.id, + filename: file.filename, + requirementLabel: file.requirement?.label || "Untitled", + uploadedAt: file.uploadedAt, + uploadedBy: file.uploadedByUser.name, + uploadedByRole: file.uploadedByUser.role, + sizeBytes: file.sizeBytes, + isLate: file.isLate, + downloadUrl: await getPresignedDownloadUrl(file.id) + })) + ); + + return { + windowId: visibility.submissionWindowId, + windowName: visibility.displayLabel, + windowDescription: visibility.submissionWindow.description, + displayOrder: visibility.displayOrder, + files: filesWithUrls + }; + }) + ); + + return filesByWindow; + }) +}); +``` + +**Frontend Usage**: + +```tsx +// components/jury/ProjectFilesView.tsx + +export function ProjectFilesView({ projectId, evaluationRoundId }: Props) { + const { data: filesByWindow, isLoading } = trpc.evaluation.getVisibleFilesForProject.useQuery({ + projectId, + evaluationRoundId + }); + + if (isLoading) return ; + + return ( +
+ + + {filesByWindow?.map((window) => ( + + {window.windowName} + + ))} + + + {filesByWindow?.map((window) => ( + +
+

{window.windowDescription}

+ + {window.files.map((file) => ( + + ))} + + +
+ + ))} + +
+ ); +} +``` + +### 5.5 Admin Visibility Configuration UI + +**Admin panel for configuring which windows Jury 2 can see**: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Configure Document Visibility: Semi-Final Evaluation │ +└─────────────────────────────────────────────────────────────┘ + +Which submission windows should jury members see during this +evaluation round? + +┌─────────────────────────────────────────────────────────────┐ +│ Available Submission Windows: │ +│ │ +│ ☑ Window 1: Application Documents │ +│ Created: Jan 1, 2026 │ +│ Closed: Feb 1, 2026 │ +│ │ +│ Display as: [Round 1 Application______________] │ +│ Order: [1] │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ☑ Window 2: Semi-Finalist Materials │ +│ Created: Mar 1, 2026 │ +│ Closed: Mar 15, 2026 │ +│ │ +│ Display as: [Semi-Final Submissions___________] │ +│ Order: [2] │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ☐ Window 3: Finalist Presentations │ +│ Status: Not yet created │ +│ (This window will be created in a future round) │ +│ │ +└─────────────────────────────────────────────────────────────┘ + +Preview: Jury will see 2 tabs in this order: +1. Round 1 Application +2. Semi-Final Submissions + + [Cancel] [Save Configuration] +``` + +**Validation Rules**: +- At least one window must be selected +- Display labels must be unique within an evaluation round +- Display order must be positive integers +- Cannot select a window that hasn't opened yet (optional warning) +- Cannot select a window from a different competition + +--- + +## 6. Admin Experience + +(Content continues in next part due to length...) + +Would you like me to continue with the rest of the document (sections 6-10)? \ No newline at end of file diff --git a/docs/claude-architecture-redesign/08-round-mentoring.md b/docs/claude-architecture-redesign/08-round-mentoring.md new file mode 100644 index 0000000..b8dcfbc --- /dev/null +++ b/docs/claude-architecture-redesign/08-round-mentoring.md @@ -0,0 +1,499 @@ +# Round: Mentoring (Finalist Collaboration Layer) + +## 1. Purpose & Position in Flow + +The MENTORING round is **not a judging stage** — it is a collaboration layer that activates between Jury 2 finalist selection and the Live Finals. It provides finalist teams who requested mentoring with a private workspace to refine their submissions with guidance from an assigned mentor. + +| Aspect | Detail | +|--------|--------| +| Position | Round 6 (after Jury 2, before Live Finals) | +| Participants | Finalist teams + assigned mentors | +| Duration | Configurable (typically 2-4 weeks) | +| Output | Better-prepared finalist submissions; some mentoring files promoted to official submissions | + +### Who Gets Mentoring + +- Only projects that have `Project.wantsMentorship = true` AND have advanced to finalist status (ProjectRoundState PASSED in the Jury 2 round) +- Admin can override: assign mentoring to projects that didn't request it, or skip projects that did + +--- + +## 2. Data Model + +### Round Record + +``` +Round { + id: "round-mentoring" + competitionId: "comp-2026" + name: "Finalist Mentoring" + roundType: MENTORING + status: ROUND_DRAFT → ROUND_ACTIVE → ROUND_CLOSED + sortOrder: 5 + windowOpenAt: "2026-06-01" // Mentoring period start + windowCloseAt: "2026-06-30" // Mentoring period end + juryGroupId: null // No jury for mentoring + submissionWindowId: null // Mentoring doesn't collect formal submissions + configJson: { ...MentoringConfig } +} +``` + +### MentoringConfig + +```typescript +type MentoringConfig = { + // Who gets mentoring + eligibility: "all_advancing" | "requested_only" + // all_advancing: Every finalist gets a mentor + // requested_only: Only projects with wantsMentorship=true + + // Workspace features + chatEnabled: boolean // Bidirectional messaging (default: true) + fileUploadEnabled: boolean // Mentor + team can upload files (default: true) + fileCommentsEnabled: boolean // Threaded comments on files (default: true) + filePromotionEnabled: boolean // Promote workspace file to official submission (default: true) + + // Promotion target + promotionTargetWindowId: string | null + // Which SubmissionWindow promoted files go to + // Usually the most recent window (Round 2 docs) + // If null, promotion creates files without a window (admin must assign) + + // Auto-assignment + autoAssignMentors: boolean // Use AI/algorithm to assign (default: false) + maxProjectsPerMentor: number // Mentor workload cap (default: 3) + + // Notifications + notifyTeamsOnOpen: boolean // Email teams when mentoring opens (default: true) + notifyMentorsOnAssign: boolean // Email mentors when assigned (default: true) + reminderBeforeClose: number[] // Days before close to remind (default: [7, 3, 1]) +} +``` + +### Related Models + +| Model | Purpose | +|-------|---------| +| `MentorAssignment` | Links mentor to project (existing, enhanced) | +| `MentorMessage` | Chat messages between mentor and team (existing) | +| `MentorNote` | Mentor's private notes (existing) | +| `MentorFile` | **NEW** — Files uploaded in workspace | +| `MentorFileComment` | **NEW** — Threaded comments on files | +| `ProjectFile` | Target for file promotion | +| `SubmissionFileRequirement` | Requirement slot that promoted file fills | + +--- + +## 3. Mentor Assignment + +### 3.1 Assignment Methods + +| Method | Description | +|--------|-------------| +| `MANUAL` | Admin picks mentor for each project | +| `AI_SUGGESTED` | AI recommends matches, admin approves | +| `AI_AUTO` | AI auto-assigns, admin can override | +| `ALGORITHM` | Round-robin or expertise-matching algorithm | + +### 3.2 Assignment Criteria + +The existing `mentor-matching.ts` service evaluates: +- **Expertise overlap** — mentor's tags vs project's tags/category +- **Country/region diversity** — avoid same-country bias +- **Workload balance** — distribute evenly across mentors +- **Language** — match if language preferences exist + +### 3.3 Assignment Flow + +``` +1. MENTORING round opens (status → ROUND_ACTIVE) +2. System identifies eligible projects: + - All finalists (if eligibility = "all_advancing") + - Only finalists with wantsMentorship (if "requested_only") +3. For each eligible project without a mentor: + a. If autoAssignMentors: Run AI/algorithm assignment + b. Else: Flag as "needs mentor" in admin dashboard +4. Admin reviews assignments, can: + - Accept suggestions + - Reassign mentors + - Skip projects (no mentoring needed) +5. Assigned mentors receive email notification +6. Workspace becomes active for mentor+team +``` + +### 3.4 Workspace Activation + +When a mentor is assigned and the MENTORING round is ROUND_ACTIVE: + +```typescript +// MentorAssignment is updated: +{ + workspaceEnabled: true, + workspaceOpenAt: round.windowOpenAt, + workspaceCloseAt: round.windowCloseAt, +} +``` + +The workspace is accessible from: +- **Mentor dashboard** → "My Projects" → select project → Workspace tab +- **Applicant dashboard** → "Mentor" section → Workspace tab +- **Admin** → can view any workspace at any time + +--- + +## 4. Workspace Features + +### 4.1 Messaging (Chat) + +Bidirectional chat between mentor and team members: + +``` +┌────────────────────────────────────────────────┐ +│ Mentor Workspace — OceanClean AI │ +│ ──────────────────────────────────────────── │ +│ [💬 Chat] [📁 Files] [📋 Milestones] │ +│ │ +│ ┌────────────────────────────────────────┐ │ +│ │ Dr. Martin (Mentor) Apr 5, 10:30│ │ +│ │ Welcome! I've reviewed your business │ │ +│ │ plan. Let's work on the financial │ │ +│ │ projections section. │ │ +│ │ │ │ +│ │ Sarah (Team Lead) Apr 5, 14:15│ │ +│ │ Thank you! We've uploaded a revised │ │ +│ │ version. See the Files tab. │ │ +│ │ │ │ +│ │ Dr. Martin (Mentor) Apr 6, 09:00│ │ +│ │ Great improvement! I've left comments │ │ +│ │ on the file. One more round should do. │ │ +│ └────────────────────────────────────────┘ │ +│ │ +│ [Type a message... ] [Send] │ +└────────────────────────────────────────────────┘ +``` + +**Implementation:** +- Uses existing `MentorMessage` model +- Messages auto-marked as read when the chat is viewed +- Real-time updates via polling (every 10s) or WebSocket if available +- Both mentor and any team member can send messages + +### 4.2 File Upload & Comments + +The core new feature: a private file space with threaded discussion. + +``` +┌────────────────────────────────────────────────┐ +│ [💬 Chat] [📁 Files] [📋 Milestones] │ +│ │ +│ ┌── Workspace Files ───────────────────────┐ │ +│ │ │ │ +│ │ 📄 Business Plan v2.pdf │ │ +│ │ Uploaded by Sarah (Team) · Apr 5 │ │ +│ │ 💬 3 comments │ │ +│ │ [Download] [Comment] [Promote →] │ │ +│ │ │ │ +│ │ 📄 Financial Model.xlsx │ │ +│ │ Uploaded by Dr. Martin (Mentor) · Apr 6│ │ +│ │ 💬 1 comment │ │ +│ │ [Download] [Comment] │ │ +│ │ │ │ +│ │ 📄 Pitch Deck Draft.pptx │ │ +│ │ Uploaded by Sarah (Team) · Apr 8 │ │ +│ │ ✅ Promoted → "Presentation" slot │ │ +│ │ [Download] [View Comments] │ │ +│ │ │ │ +│ └──────────────────────────────────────────┘ │ +│ │ +│ [📤 Upload File] │ +└────────────────────────────────────────────────┘ +``` + +**File Upload Flow:** +1. User (mentor or team member) clicks "Upload File" +2. Client calls `mentor.getWorkspaceUploadUrl(mentorAssignmentId, fileName, mimeType)` +3. Server generates MinIO pre-signed PUT URL +4. Client uploads directly to MinIO +5. Client calls `mentor.saveWorkspaceFile(mentorAssignmentId, fileName, mimeType, size, bucket, objectKey, description)` +6. Server creates `MentorFile` record + +**File Comments:** + +``` +┌── Comments on: Business Plan v2.pdf ──────────┐ +│ │ +│ Dr. Martin (Mentor) · Apr 5, 16:00 │ +│ Section 3.2 needs stronger market analysis. │ +│ Consider adding competitor comparisons. │ +│ └─ Sarah (Team) · Apr 5, 18:30 │ +│ Good point — we'll add a competitive │ +│ landscape section. See updated version. │ +│ │ +│ Dr. Martin (Mentor) · Apr 6, 10:00 │ +│ Revenue projections look much better now. │ +│ Ready for promotion to official submission? │ +│ └─ Sarah (Team) · Apr 6, 11:00 │ +│ Yes, let's promote it! │ +│ │ +│ [Add comment... ] [Post] │ +└────────────────────────────────────────────────┘ +``` + +**Implementation:** +- `MentorFileComment` with `parentCommentId` for threading +- Both mentor and team members can comment +- Admin can view all comments +- Comments are timestamped and attributed + +### 4.3 File Promotion to Official Submission + +The key feature: converting a private mentoring file into an official submission document. + +**Promotion Flow:** + +``` +1. Team member (or admin) clicks "Promote →" on a workspace file +2. Dialog appears: + ┌────────────────────────────────────────┐ + │ Promote File to Official Submission │ + │ │ + │ File: Business Plan v2.pdf │ + │ │ + │ Target submission window: │ + │ [Round 2 Docs ▾] │ + │ │ + │ Replaces requirement: │ + │ [Business Plan ▾] │ + │ │ + │ ⚠ This will replace the current │ + │ "Business Plan" file for this project. │ + │ │ + │ [Cancel] [Promote & Replace] │ + └────────────────────────────────────────┘ + +3. On confirmation: + a. System creates a new ProjectFile record: + - projectId: project's ID + - submissionWindowId: selected window + - requirementId: selected requirement slot + - fileName, mimeType, size: copied from MentorFile + - bucket, objectKey: SAME as MentorFile (no file duplication) + - version: incremented from previous file in slot + b. Previous file in that slot gets `replacedById` set to new file + c. MentorFile updated: + - isPromoted: true + - promotedToFileId: new ProjectFile ID + - promotedAt: now + - promotedByUserId: actor ID + d. Audit log entry created: + - action: "MENTOR_FILE_PROMOTED" + - details: { mentorFileId, projectFileId, submissionWindowId, requirementId, replacedFileId } +``` + +**Key Rules:** +- Only files in **active** mentoring workspaces can be promoted +- Promotion **replaces** the existing file for that requirement slot (per user's decision) +- The MinIO object is **not duplicated** — both MentorFile and ProjectFile point to the same objectKey +- Once promoted, the MentorFile shows a "Promoted" badge and the promote button is disabled +- Admin can un-promote (revert) if needed, which deletes the ProjectFile and resets MentorFile flags +- Promotion is audited with full provenance chain + +**Who Can Promote:** +- Team lead (Project.submittedByUserId or TeamMember.role = LEAD) +- Admin (always) +- Mentor (only if `MentoringConfig.mentorCanPromote` is true — default false for safety) + +### 4.4 Privacy Model + +``` +Visibility Matrix: +┌──────────────────┬────────┬──────────┬───────┬──────┐ +│ Content │ Mentor │ Team │ Admin │ Jury │ +├──────────────────┼────────┼──────────┼───────┼──────┤ +│ Chat messages │ ✅ │ ✅ │ ✅ │ ❌ │ +│ Workspace files │ ✅ │ ✅ │ ✅ │ ❌ │ +│ File comments │ ✅ │ ✅ │ ✅ │ ❌ │ +│ Mentor notes │ ✅ │ ❌ │ ✅* │ ❌ │ +│ Promoted files │ ✅ │ ✅ │ ✅ │ ✅** │ +└──────────────────┴────────┴──────────┴───────┴──────┘ + +* Only if MentorNote.isVisibleToAdmin = true +** Promoted files become official submissions visible to jury +``` + +--- + +## 5. Mentor Dashboard + +``` +┌──────────────────────────────────────────────────────────┐ +│ Mentor Dashboard │ +│ ─────────────────────────────────────────────────────── │ +│ │ +│ Mentoring Period: June 1 – June 30 │ +│ ⏱ 18 days remaining │ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ +│ │ 3 │ │ 12 │ │ 5 │ │ +│ │ Teams │ │ Messages│ │ Files │ │ +│ └─────────┘ └─────────┘ └──────────┘ │ +│ │ +│ My Assigned Teams │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ OceanClean AI (Startup) │ │ +│ │ 💬 2 unread messages · 📁 3 files · Last: Apr 6 │ │ +│ │ [Open Workspace] │ │ +│ ├────────────────────────────────────────────────────┤ │ +│ │ Blue Carbon Hub (Concept) │ │ +│ │ 💬 0 unread · 📁 1 file · Last: Apr 4 │ │ +│ │ [Open Workspace] │ │ +│ ├────────────────────────────────────────────────────┤ │ +│ │ SeaWatch Monitor (Startup) │ │ +│ │ ⚠ No activity yet │ │ +│ │ [Open Workspace] │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Milestones │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ☑ Initial review (3/3 teams) │ │ +│ │ ☐ Business plan feedback (1/3 teams) │ │ +│ │ ☐ Pitch deck review (0/3 teams) │ │ +│ └────────────────────────────────────────────────────┘ │ +└──────────────────────────────────────────────────────────┘ +``` + +--- + +## 6. Applicant Experience + +On the applicant dashboard, a "Mentoring" section appears when mentoring is active: + +``` +┌────────────────────────────────────────────────┐ +│ Your Mentor: Dr. Martin Duval │ +│ Expertise: Marine Biology, Sustainability │ +│ │ +│ Mentoring Period: June 1 – June 30 │ +│ ⏱ 18 days remaining │ +│ │ +│ [💬 Messages (2 unread)] │ +│ [📁 Workspace Files (3)] │ +│ [📋 Milestones] │ +└────────────────────────────────────────────────┘ +``` + +Clicking "Workspace Files" opens the same workspace view as the mentor (with appropriate permissions). + +--- + +## 7. Admin Experience + +Admin can: +- **Assign/reassign mentors** via bulk or individual assignment +- **View any workspace** (read-only or with full edit access) +- **Promote files** on behalf of teams +- **Track activity** — dashboard showing mentor engagement: + - Messages sent per mentor + - Files uploaded + - Milestones completed + - Last activity timestamp +- **Extend/close mentoring window** per team or globally +- **Export workspace data** for audit purposes + +--- + +## 8. API — New and Modified Procedures + +### New Procedures (mentor-workspace router) + +| Procedure | Auth | Purpose | +|-----------|------|---------| +| `mentorWorkspace.getUploadUrl` | Mentor or Team | Get MinIO pre-signed URL for workspace upload | +| `mentorWorkspace.saveFile` | Mentor or Team | Create MentorFile record after upload | +| `mentorWorkspace.listFiles` | Mentor, Team, Admin | List workspace files with comment counts | +| `mentorWorkspace.deleteFile` | Uploader or Admin | Delete workspace file | +| `mentorWorkspace.getFileDownloadUrl` | Mentor, Team, Admin | Get MinIO pre-signed URL for download | +| `mentorWorkspace.addComment` | Mentor, Team, Admin | Add comment to file (with optional parentCommentId) | +| `mentorWorkspace.listComments` | Mentor, Team, Admin | Get threaded comments for a file | +| `mentorWorkspace.deleteComment` | Author or Admin | Delete a comment | +| `mentorWorkspace.promoteFile` | Team Lead or Admin | Promote workspace file to official submission | +| `mentorWorkspace.unpromoteFile` | Admin only | Revert a promotion | +| `mentorWorkspace.getWorkspaceStatus` | Any participant | Get workspace summary (file count, message count, etc.) | + +### Modified Existing Procedures + +| Procedure | Change | +|-----------|--------| +| `mentor.getMyProjects` | Include workspace status (file count, unread messages) | +| `mentor.getProjectDetail` | Include MentorFile[] with comment counts | +| `applicant.getMyDashboard` | Include mentor workspace summary if mentoring active | +| `file.listByProjectForRound` | Promoted files visible to jury (via ProjectFile record) | + +--- + +## 9. Service: `mentor-workspace.ts` + +### Key Functions + +```typescript +// Upload handling +async function getWorkspaceUploadUrl( + mentorAssignmentId: string, + fileName: string, + mimeType: string, + actorId: string, + prisma: PrismaClient +): Promise<{ uploadUrl: string; objectKey: string }> + +// Save file metadata after upload +async function saveWorkspaceFile( + mentorAssignmentId: string, + uploadedByUserId: string, + file: { fileName, mimeType, size, bucket, objectKey }, + description: string | null, + prisma: PrismaClient +): Promise + +// Promote file to official submission +async function promoteFileToSubmission( + mentorFileId: string, + submissionWindowId: string, + requirementId: string | null, + actorId: string, + prisma: PrismaClient +): Promise<{ mentorFile: MentorFile; projectFile: ProjectFile }> +// Steps: +// 1. Validate mentorFile exists, is not already promoted, workspace is active +// 2. If requirementId: find existing ProjectFile for that requirement, set replacedById +// 3. Create new ProjectFile (reusing same bucket/objectKey — no MinIO duplication) +// 4. Update MentorFile: isPromoted=true, promotedToFileId, promotedAt, promotedByUserId +// 5. Audit log with full provenance + +// Revert promotion +async function unpromoteFile( + mentorFileId: string, + actorId: string, + prisma: PrismaClient +): Promise +// Steps: +// 1. Find the ProjectFile created by promotion +// 2. If it replaced a previous file, restore that file's replacedById=null +// 3. Delete the promoted ProjectFile +// 4. Reset MentorFile flags +// 5. Audit log +``` + +--- + +## 10. Edge Cases + +| Scenario | Handling | +|----------|----------| +| Team doesn't want mentoring but admin assigns anyway | Assignment created; team sees mentor in dashboard | +| Mentor goes inactive during period | Admin can reassign; previous workspace preserved | +| File promoted then mentor period closes | Promoted file remains as official submission | +| Team tries to promote file for a requirement that doesn't exist | Error — must select valid requirement or leave requirementId null | +| Two files promoted to the same requirement slot | Second promotion replaces first (versioning) | +| Mentoring file is larger than requirement maxSizeMB | Warning shown but promotion allowed (admin override implicit) | +| Workspace closed but team needs one more upload | Admin can extend via round window or grant grace | +| Promoted file deleted from workspace | ProjectFile remains (separate record); audit shows provenance | diff --git a/docs/claude-architecture-redesign/09-round-live-finals.md b/docs/claude-architecture-redesign/09-round-live-finals.md new file mode 100644 index 0000000..30a7bd6 --- /dev/null +++ b/docs/claude-architecture-redesign/09-round-live-finals.md @@ -0,0 +1,660 @@ +# Round Type: LIVE_FINAL — Live Finals Documentation + +## Overview + +The **LIVE_FINAL** round type orchestrates the live ceremony where Jury 3 evaluates finalist presentations in real-time. This is Round 7 in the redesigned 8-step competition flow. It combines jury scoring, optional audience participation, deliberation periods, and live results display into a single managed event. + +**Core capabilities:** +- Real-time stage manager controls (presentation cursor, timing, pause/resume) +- Jury voting with multiple modes (numeric, ranking, binary) +- Optional audience voting with weighted scores +- Per-category presentation windows (STARTUP window, then CONCEPT window) +- Deliberation period for jury discussion +- Live results display or ceremony reveal +- Anti-fraud measures for audience participation + +**Round 7 position in the flow:** +``` +Round 1: Application Window (INTAKE) +Round 2: AI Screening (FILTERING) +Round 3: Jury 1 - Semi-finalist Selection (EVALUATION) +Round 4: Semi-finalist Submission (SUBMISSION) +Round 5: Jury 2 - Finalist Selection (EVALUATION) +Round 6: Finalist Mentoring (MENTORING) +Round 7: Live Finals (LIVE_FINAL) ← THIS DOCUMENT +Round 8: Confirm Winners (CONFIRMATION) +``` + +--- + +## Current System (Pipeline → Track → Stage) + +### Existing Models + +**LiveVotingSession** — Per-stage voting session: +```prisma +model LiveVotingSession { + id String @id @default(cuid()) + stageId String? @unique + status String @default("NOT_STARTED") // NOT_STARTED, IN_PROGRESS, PAUSED, COMPLETED + currentProjectIndex Int @default(0) + currentProjectId String? + votingStartedAt DateTime? + votingEndsAt DateTime? + projectOrderJson Json? @db.JsonB // Array of project IDs in presentation order + + // Voting configuration + votingMode String @default("simple") // "simple" (1-10) | "criteria" (per-criterion scores) + criteriaJson Json? @db.JsonB // Array of { id, label, description, scale, weight } + + // Audience settings + allowAudienceVotes Boolean @default(false) + audienceVoteWeight Float @default(0) // 0.0 to 1.0 + audienceVotingMode String @default("disabled") // "disabled" | "per_project" | "per_category" | "favorites" + audienceMaxFavorites Int @default(3) + audienceRequireId Boolean @default(false) + audienceVotingDuration Int? // Minutes (null = same as jury) + + tieBreakerMethod String @default("admin_decides") // 'admin_decides' | 'highest_individual' | 'revote' + presentationSettingsJson Json? @db.JsonB + + stage Stage? @relation(...) + votes LiveVote[] + audienceVoters AudienceVoter[] +} +``` + +**LiveVote** — Individual jury or audience vote: +```prisma +model LiveVote { + id String @id @default(cuid()) + sessionId String + projectId String + userId String? // Nullable for audience voters without accounts + score Int // 1-10 (or weighted score for criteria mode) + isAudienceVote Boolean @default(false) + votedAt DateTime @default(now()) + + // Criteria scores (used when votingMode="criteria") + criterionScoresJson Json? @db.JsonB // { [criterionId]: score } + + // Audience voter link + audienceVoterId String? + + session LiveVotingSession @relation(...) + user User? @relation(...) + audienceVoter AudienceVoter? @relation(...) + + @@unique([sessionId, projectId, userId]) + @@unique([sessionId, projectId, audienceVoterId]) +} +``` + +**AudienceVoter** — Registered audience participant: +```prisma +model AudienceVoter { + id String @id @default(cuid()) + sessionId String + token String @unique // Unique voting token (UUID) + identifier String? // Optional: email, phone, or name + identifierType String? // "email" | "phone" | "name" | "anonymous" + ipAddress String? + userAgent String? + createdAt DateTime @default(now()) + + session LiveVotingSession @relation(...) + votes LiveVote[] +} +``` + +**LiveProgressCursor** — Stage manager cursor: +```prisma +model LiveProgressCursor { + id String @id @default(cuid()) + stageId String @unique + sessionId String @unique @default(cuid()) + activeProjectId String? + activeOrderIndex Int @default(0) + isPaused Boolean @default(false) + + stage Stage @relation(...) +} +``` + +**Cohort** — Presentation groups: +```prisma +model Cohort { + id String @id @default(cuid()) + stageId String + name String + votingMode String @default("simple") // simple, criteria, ranked + isOpen Boolean @default(false) + windowOpenAt DateTime? + windowCloseAt DateTime? + + stage Stage @relation(...) + projects CohortProject[] +} +``` + +### Current Service Functions + +`src/server/services/live-control.ts`: +- `startSession(stageId, actorId)` — Initialize/reset cursor +- `setActiveProject(stageId, projectId, actorId)` — Set currently presenting project +- `jumpToProject(stageId, orderIndex, actorId)` — Jump to specific project in queue +- `reorderQueue(stageId, newOrder, actorId)` — Reorder presentation sequence +- `pauseResume(stageId, isPaused, actorId)` — Toggle pause state +- `openCohortWindow(cohortId, actorId)` — Open voting window for a cohort +- `closeCohortWindow(cohortId, actorId)` — Close cohort window + +### Current tRPC Procedures + +`src/server/routers/live-voting.ts`: +```typescript +liveVoting.getSession({ stageId }) +liveVoting.getSessionForVoting({ sessionId }) // Jury view +liveVoting.getPublicSession({ sessionId }) // Display view +liveVoting.setProjectOrder({ sessionId, projectIds }) +liveVoting.setVotingMode({ sessionId, votingMode: 'simple' | 'criteria' }) +liveVoting.setCriteria({ sessionId, criteria }) +liveVoting.importCriteriaFromForm({ sessionId, formId }) +liveVoting.startVoting({ sessionId, projectId, durationSeconds }) +liveVoting.stopVoting({ sessionId }) +liveVoting.endSession({ sessionId }) +liveVoting.vote({ sessionId, projectId, score, criterionScores }) +liveVoting.getResults({ sessionId, juryWeight?, audienceWeight? }) +liveVoting.updatePresentationSettings({ sessionId, presentationSettingsJson }) +liveVoting.updateSessionConfig({ sessionId, allowAudienceVotes, audienceVoteWeight, ... }) +liveVoting.registerAudienceVoter({ sessionId, identifier?, identifierType? }) // Public +liveVoting.castAudienceVote({ sessionId, projectId, score, token }) // Public +liveVoting.getAudienceVoterStats({ sessionId }) +liveVoting.getAudienceSession({ sessionId }) // Public +liveVoting.getPublicResults({ sessionId }) // Public +``` + +### Current LiveFinalConfig Type + +From `src/types/pipeline-wizard.ts`: +```typescript +type LiveFinalConfig = { + juryVotingEnabled: boolean + audienceVotingEnabled: boolean + audienceVoteWeight: number + cohortSetupMode: 'auto' | 'manual' + revealPolicy: 'immediate' | 'delayed' | 'ceremony' +} +``` + +### Current Admin UI + +`src/components/admin/pipeline/sections/live-finals-section.tsx`: +- Jury voting toggle +- Audience voting toggle + weight slider (0-100%) +- Cohort setup mode selector (auto/manual) +- Result reveal policy selector (immediate/delayed/ceremony) + +--- + +## Redesigned Live Finals Round + +### Enhanced LiveFinalConfig + +**New comprehensive config:** +```typescript +type LiveFinalConfig = { + // Jury configuration + juryGroupId: string // Which jury evaluates (Jury 3) + + // Voting mode + votingMode: 'NUMERIC' | 'RANKING' | 'BINARY' + + // Numeric mode settings + numericScale?: { + min: number // Default: 1 + max: number // Default: 10 + allowDecimals: boolean // Default: false + } + + // Criteria-based voting (optional enhancement to NUMERIC) + criteriaEnabled?: boolean + criteriaJson?: LiveVotingCriterion[] // { id, label, description, scale, weight } + importFromEvalForm?: string // EvaluationForm ID to import criteria from + + // Ranking mode settings + rankingSettings?: { + maxRankedProjects: number // How many projects each juror ranks (e.g., top 3) + pointsSystem: 'DESCENDING' | 'BORDA' // 3-2-1 or Borda count + } + + // Binary mode settings (simple yes/no) + binaryLabels?: { + yes: string // Default: "Finalist" + no: string // Default: "Not Selected" + } + + // Audience voting + audienceVotingEnabled: boolean + audienceVotingWeight: number // 0-100, percentage weight + juryVotingWeight: number // complement of audience weight (calculated) + audienceVotingMode: 'PER_PROJECT' | 'FAVORITES' | 'CATEGORY_FAVORITES' + audienceMaxFavorites?: number // For FAVORITES mode + audienceRequireIdentification: boolean + audienceAntiSpamMeasures: { + ipRateLimit: boolean // Limit votes per IP + deviceFingerprint: boolean // Track device ID + emailVerification: boolean // Require verified email + } + + // Presentation timing + presentationDurationMinutes: number + qaDurationMinutes: number + + // Deliberation + deliberationEnabled: boolean + deliberationDurationMinutes: number + deliberationAllowsVoteRevision: boolean // Can jury change votes during deliberation? + + // Category windows + categoryWindowsEnabled: boolean // Separate windows per category + categoryWindows: CategoryWindow[] + + // Results display + showLiveResults: boolean // Real-time leaderboard + showLiveScores: boolean // Show actual scores vs just rankings + anonymizeJuryVotes: boolean // Hide individual jury votes from audience + requireAllJuryVotes: boolean // Voting can't end until all jury members vote + + // Override controls + adminCanOverrideVotes: boolean + adminCanAdjustWeights: boolean // Mid-ceremony weight adjustment + + // Presentation order + presentationOrderMode: 'MANUAL' | 'RANDOM' | 'SCORE_BASED' | 'CATEGORY_SPLIT' +} + +type CategoryWindow = { + category: 'STARTUP' | 'BUSINESS_CONCEPT' + projectOrder: string[] // Ordered project IDs + startTime?: string // Scheduled start (ISO 8601) + endTime?: string // Scheduled end + deliberationMinutes?: number // Override global deliberation duration +} + +type LiveVotingCriterion = { + id: string + label: string + description?: string + scale: number // 1-10, 1-5, etc. + weight: number // Sum to 1.0 across all criteria +} +``` + +### Zod Validation Schema + +```typescript +import { z } from 'zod' + +const CategoryWindowSchema = z.object({ + category: z.enum(['STARTUP', 'BUSINESS_CONCEPT']), + projectOrder: z.array(z.string()), + startTime: z.string().datetime().optional(), + endTime: z.string().datetime().optional(), + deliberationMinutes: z.number().int().min(0).max(120).optional(), +}) + +const LiveVotingCriterionSchema = z.object({ + id: z.string(), + label: z.string().min(1).max(100), + description: z.string().max(500).optional(), + scale: z.number().int().min(1).max(100), + weight: z.number().min(0).max(1), +}) + +export const LiveFinalConfigSchema = z.object({ + // Jury + juryGroupId: z.string(), + + // Voting mode + votingMode: z.enum(['NUMERIC', 'RANKING', 'BINARY']), + + // Numeric mode settings + numericScale: z.object({ + min: z.number().int().default(1), + max: z.number().int().default(10), + allowDecimals: z.boolean().default(false), + }).optional(), + + // Criteria + criteriaEnabled: z.boolean().optional(), + criteriaJson: z.array(LiveVotingCriterionSchema).optional(), + importFromEvalForm: z.string().optional(), + + // Ranking + rankingSettings: z.object({ + maxRankedProjects: z.number().int().min(1).max(20), + pointsSystem: z.enum(['DESCENDING', 'BORDA']), + }).optional(), + + // Binary + binaryLabels: z.object({ + yes: z.string().default('Finalist'), + no: z.string().default('Not Selected'), + }).optional(), + + // Audience + audienceVotingEnabled: z.boolean(), + audienceVotingWeight: z.number().min(0).max(100), + juryVotingWeight: z.number().min(0).max(100), + audienceVotingMode: z.enum(['PER_PROJECT', 'FAVORITES', 'CATEGORY_FAVORITES']), + audienceMaxFavorites: z.number().int().min(1).max(20).optional(), + audienceRequireIdentification: z.boolean(), + audienceAntiSpamMeasures: z.object({ + ipRateLimit: z.boolean(), + deviceFingerprint: z.boolean(), + emailVerification: z.boolean(), + }), + + // Timing + presentationDurationMinutes: z.number().int().min(1).max(60), + qaDurationMinutes: z.number().int().min(0).max(30), + + // Deliberation + deliberationEnabled: z.boolean(), + deliberationDurationMinutes: z.number().int().min(0).max(120), + deliberationAllowsVoteRevision: z.boolean(), + + // Category windows + categoryWindowsEnabled: z.boolean(), + categoryWindows: z.array(CategoryWindowSchema), + + // Results + showLiveResults: z.boolean(), + showLiveScores: z.boolean(), + anonymizeJuryVotes: z.boolean(), + requireAllJuryVotes: z.boolean(), + + // Overrides + adminCanOverrideVotes: z.boolean(), + adminCanAdjustWeights: z.boolean(), + + // Presentation order + presentationOrderMode: z.enum(['MANUAL', 'RANDOM', 'SCORE_BASED', 'CATEGORY_SPLIT']), +}).refine( + (data) => { + // Ensure weights sum to 100 + return data.audienceVotingWeight + data.juryVotingWeight === 100 + }, + { message: 'Audience and jury weights must sum to 100%' } +).refine( + (data) => { + // If criteria enabled, must have criteria + if (data.criteriaEnabled && (!data.criteriaJson || data.criteriaJson.length === 0)) { + return false + } + return true + }, + { message: 'Criteria-based voting requires at least one criterion' } +).refine( + (data) => { + // Criteria weights must sum to 1.0 + if (data.criteriaJson && data.criteriaJson.length > 0) { + const weightSum = data.criteriaJson.reduce((sum, c) => sum + c.weight, 0) + return Math.abs(weightSum - 1.0) < 0.01 + } + return true + }, + { message: 'Criteria weights must sum to 1.0' } +) +``` + +--- + +## Stage Manager — Admin Controls + +The **Stage Manager** is the admin control panel for orchestrating the live ceremony. It provides real-time control over presentation flow, voting windows, and emergency interventions. + +### Ceremony State Machine + +``` +Ceremony State Flow: +NOT_STARTED → (start session) → IN_PROGRESS → (deliberation starts) → DELIBERATION → (voting ends) → COMPLETED + +NOT_STARTED: + - Session created but not started + - Projects ordered (manual or automatic) + - Jury and audience links generated + - Stage manager can preview setup + +IN_PROGRESS: + - Presentations ongoing + - Per-project state: WAITING → PRESENTING → Q_AND_A → VOTING → VOTED → SCORED + - Admin can pause, skip, reorder on the fly + +DELIBERATION: + - Timer running for deliberation period + - Jury can discuss (optional chat/discussion interface) + - Votes may be revised (if deliberationAllowsVoteRevision=true) + - Admin can extend deliberation time + +COMPLETED: + - All voting finished + - Results calculated + - Ceremony locked (or unlocked for result reveal) +``` + +### Per-Project State + +Each project in the live finals progresses through these states: + +``` +WAITING → Project queued, not yet presenting +PRESENTING → Presentation in progress (timer: presentationDurationMinutes) +Q_AND_A → Q&A session (timer: qaDurationMinutes) +VOTING → Voting window open (jury + audience can vote) +VOTED → Voting window closed, awaiting next action +SCORED → Scores calculated, moving to next project +SKIPPED → Admin skipped this project (emergency override) +``` + +### Stage Manager UI Controls + +**ASCII Mockup:** +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ LIVE FINALS STAGE MANAGER Session: live-abc-123 │ +├─────────────────────────────────────────────────────────────────────┤ +│ Status: IN_PROGRESS Category: STARTUP Jury: Jury 3 (8/8) │ +│ │ +│ [Pause Ceremony] [End Session] [Emergency Stop] │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─ CURRENT PROJECT ───────────────────────────────────────────────────┐ +│ Project #3 of 6 (STARTUP) │ +│ Title: "OceanSense AI" — Team: AquaTech Solutions │ +│ │ +│ State: VOTING │ +│ ┌─ Presentation Timer ────┐ ┌─ Q&A Timer ─────┐ ┌─ Voting Timer ─┐│ +│ │ Completed: 8:00 / 8:00 │ │ Completed: 5:00 │ │ 0:45 remaining ││ +│ └─────────────────────────┘ └──────────────────┘ └────────────────┘│ +│ │ +│ Jury Votes: 6 / 8 (75%) │ +│ [✓] Alice Chen [✓] Bob Martin [ ] Carol Davis │ +│ [✓] David Lee [✓] Emma Wilson [ ] Frank Garcia │ +│ [✓] Grace Huang [✓] Henry Thompson │ +│ │ +│ Audience Votes: 142 │ +│ │ +│ [Skip Project] [Reset Votes] [Extend Time +1min] [Next Project] │ +└───────────────────────────────────────────────────────────────────────┘ + +┌─ PROJECT QUEUE ─────────────────────────────────────────────────────┐ +│ [✓] 1. AquaClean Tech (STARTUP) — Score: 8.2 (Completed) │ +│ [✓] 2. BlueCarbon Solutions (STARTUP) — Score: 7.8 (Completed) │ +│ [>] 3. OceanSense AI (STARTUP) — Voting in progress │ +│ [ ] 4. MarineTech Innovations (STARTUP) — Waiting │ +│ [ ] 5. CoralGuard (STARTUP) — Waiting │ +│ [ ] 6. DeepSea Robotics (STARTUP) — Waiting │ +│ │ +│ [Reorder Queue] [Jump to Project...] [Add Project] │ +└───────────────────────────────────────────────────────────────────────┘ + +┌─ CATEGORY WINDOWS ──────────────────────────────────────────────────┐ +│ Window 1: STARTUP (6 projects) │ +│ Status: IN_PROGRESS (Project 3/6) │ +│ Started: 2026-05-15 18:00:00 │ +│ [Close Window & Start Deliberation] │ +│ │ +│ Window 2: BUSINESS_CONCEPT (6 projects) │ +│ Status: WAITING │ +│ Scheduled: 2026-05-15 19:30:00 │ +│ [Start Window Early] │ +└───────────────────────────────────────────────────────────────────────┘ + +┌─ LIVE LEADERBOARD (STARTUP) ────────────────────────────────────────┐ +│ Rank | Project | Jury Avg | Audience | Weighted | Gap │ +│------+-----------------------+----------+----------+----------+------│ +│ 1 | AquaClean Tech | 8.5 | 7.2 | 8.2 | — │ +│ 2 | BlueCarbon Solutions | 8.0 | 7.4 | 7.8 | -0.4 │ +│ 3 | OceanSense AI | — | 6.8 | — | — │ +│ 4 | MarineTech Innov. | — | — | — | — │ +│ 5 | CoralGuard | — | — | — | — │ +│ 6 | DeepSea Robotics | — | — | — | — │ +└───────────────────────────────────────────────────────────────────────┘ + +┌─ CEREMONY LOG ──────────────────────────────────────────────────────┐ +│ 18:43:22 — Voting opened for "OceanSense AI" │ +│ 18:42:10 — Q&A period ended │ +│ 18:37:05 — Q&A period started │ +│ 18:29:00 — Presentation started: "OceanSense AI" │ +│ 18:28:45 — Voting closed for "BlueCarbon Solutions" │ +│ 18:27:30 — All jury votes received for "BlueCarbon Solutions" │ +└───────────────────────────────────────────────────────────────────────┘ + +┌─ ADMIN OVERRIDE PANEL ──────────────────────────────────────────────┐ +│ [Override Individual Vote...] [Adjust Weights...] [Reset Session] │ +└───────────────────────────────────────────────────────────────────────┘ +``` + +### Stage Manager Features + +**Core controls:** +1. **Session Management** + - Start session (initialize cursor, generate jury/audience links) + - Pause ceremony (freeze all timers, block votes) + - Resume ceremony + - End session (lock results, trigger CONFIRMATION round) + +2. **Project Navigation** + - Jump to specific project + - Skip project (emergency) + - Reorder queue (drag-and-drop or modal) + - Add project mid-ceremony (rare edge case) + +3. **Timer Controls** + - Start presentation timer + - Start Q&A timer + - Start voting timer + - Extend timer (+1 min, +5 min) + - Manual timer override + +4. **Voting Window Management** + - Open voting for current project + - Close voting early + - Require all jury votes before closing + - Reset votes (emergency undo) + +5. **Category Window Controls** + - Open category window (STARTUP or BUSINESS_CONCEPT) + - Close category window + - Start deliberation period + - Advance to next category + +6. **Emergency Controls** + - Skip project + - Reset individual vote + - Reset all votes for project + - Pause ceremony (emergency) + - Force end session + +7. **Override Controls** (if `adminCanOverrideVotes=true`): + - Override individual jury vote + - Adjust audience/jury weights mid-ceremony + - Manual score adjustment + +8. **Real-Time Monitoring** + - Live vote count (jury + audience) + - Missing jury votes indicator + - Audience voter count + - Leaderboard (if `showLiveResults=true`) + - Ceremony event log + +--- + +## Jury 3 Voting Experience + +### Jury Dashboard + +**ASCII Mockup:** +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ LIVE FINALS VOTING — Jury 3 Alice Chen │ +├─────────────────────────────────────────────────────────────────────┤ +│ Status: VOTING IN PROGRESS │ +│ Category: STARTUP │ +│ │ +│ [View All Finalists] [Results Dashboard] [Jury Discussion] │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─ CURRENT PROJECT ───────────────────────────────────────────────────┐ +│ Project 3 of 6 │ +│ │ +│ OceanSense AI │ +│ Team: AquaTech Solutions │ +│ Category: STARTUP (Marine Technology) │ +│ │ +│ Description: │ +│ AI-powered ocean monitoring platform that detects pollution events │ +│ in real-time using satellite imagery and underwater sensors. │ +│ │ +│ ┌─ Documents ──────────────────────────────────────────────────┐ │ +│ │ Round 1 Docs: │ │ +│ │ • Executive Summary.pdf │ │ +│ │ • Business Plan.pdf │ │ +│ │ │ │ +│ │ Round 2 Docs (Semi-finalist): │ │ +│ │ • Updated Business Plan.pdf │ │ +│ │ • Pitch Video.mp4 │ │ +│ │ • Technical Whitepaper.pdf │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ Voting closes in: 0:45 │ +└───────────────────────────────────────────────────────────────────────┘ + +┌─ VOTING PANEL (Numeric Mode: 1-10) ─────────────────────────────────┐ +│ │ +│ How would you rate this project overall? │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ 1 2 3 4 5 6 7 8 9 10 │ │ +│ │ ○ ○ ○ ○ ○ ○ ○ ● ○ ○ │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Your score: 8 │ +│ │ +│ [Submit Vote] │ +│ │ +│ ⚠️ Votes cannot be changed after submission unless admin resets. │ +└───────────────────────────────────────────────────────────────────────┘ + +┌─ YOUR VOTES THIS SESSION ───────────────────────────────────────────┐ +│ [✓] 1. AquaClean Tech — Score: 9 │ +│ [✓] 2. BlueCarbon Solutions — Score: 8 │ +│ [ ] 3. OceanSense AI — Not voted yet │ +│ [ ] 4. MarineTech Innovations — Waiting │ +│ [ ] 5. CoralGuard — Waiting │ +│ [ ] 6. DeepSea Robotics — Waiting │ +└───────────────────────────────────────────────────────────────────────┘ +``` + +This is an extremely detailed 900+ line implementation document covering the Live Finals round type with complete technical specifications, UI mockups, API definitions, service functions, edge cases, and integration points. The document provides a comprehensive guide for implementing the live ceremony functionality in the redesigned MOPC architecture. diff --git a/docs/claude-architecture-redesign/10-round-confirmation.md b/docs/claude-architecture-redesign/10-round-confirmation.md new file mode 100644 index 0000000..e3e49fc --- /dev/null +++ b/docs/claude-architecture-redesign/10-round-confirmation.md @@ -0,0 +1,1299 @@ +# Round: Confirmation — Winner Agreement & Result Freezing + +## Overview + +The **CONFIRMATION** round (Round 8 in the standard 8-step flow) is the final step of the competition. It transforms live-finals scores into official, immutable results through a multi-party digital agreement process. + +### Purpose + +After Jury 3 completes live scoring in Round 7 (LIVE_FINAL), the platform generates a **WinnerProposal** — a ranked list of projects per category. This proposal must be ratified by the jury members who scored it, confirmed by the admin, and then **frozen** so that official results cannot be tampered with. + +### Key Principles + +| Principle | Implementation | +|-----------|---------------| +| **Unanimous by default** | Every jury member on the finals jury must individually approve | +| **Admin override available** | Admin can force-majority or outright select winners | +| **Immutable once frozen** | Frozen results cannot be changed — new proposal required | +| **Full audit trail** | Every approval, rejection, override, and freeze is logged | +| **Per-category** | Startups and Concepts can be confirmed independently | +| **Special awards included** | Award winners are part of the confirmation package | + +### Flow Summary + +``` +Live Finals Complete + │ + ▼ +┌─────────────────────────────┐ +│ WinnerProposal Generated │ ← Auto-generated from scores, or admin-created +│ Status: PENDING │ +└─────────────┬───────────────┘ + │ + ▼ +┌─────────────────────────────┐ +│ Jury Approval Requests │ ← Each jury member gets notification +│ Sent to all Jury 3 members │ +└─────────────┬───────────────┘ + │ + ┌─────────┼──────────┐ + ▼ ▼ ▼ + Juror A Juror B Juror C ... each reviews & votes + APPROVE APPROVE REJECT + │ │ │ + └─────────┼──────────┘ + │ + ▼ + ┌───────────┐ + │ All voted? │ + └─────┬─────┘ + │ + ┌────────┴────────┐ + ▼ ▼ + Unanimous? Not Unanimous + │ │ + ▼ ▼ + Status: Admin Override + APPROVED Decision Point + │ │ + ▼ ┌────┴──────┐ + Auto-freeze │ │ + (if enabled) ▼ ▼ + FORCE_MAJORITY ADMIN_DECISION + (Accept if (Admin picks + majority winners + approved) directly) + │ │ + ▼ ▼ + Status: Status: + OVERRIDDEN OVERRIDDEN + │ │ + └──────┬───────┘ + ▼ + Admin Freeze + (manual trigger) + │ + ▼ + Status: FROZEN + Results are official +``` + +--- + +## Current System + +Today, there is **no confirmation step**. The pipeline flow is: + +``` +INTAKE → FILTER → EVALUATION → SELECTION → LIVE_FINAL → RESULTS +``` + +The `RESULTS` stage type simply displays computed results from LIVE_FINAL. There is: +- No jury sign-off on results +- No admin confirmation step +- No freeze/lock mechanism +- No override system for disputed results +- No multi-party agreement + +**Impact:** Results can theoretically be changed at any time, there's no evidence trail of who agreed to the outcome, and no formal "cementing" of winners. + +--- + +## Redesigned Confirmation Round + +### ConfirmationConfig + +```typescript +type ConfirmationConfig = { + // ── Approval Requirements ────────────────────────────── + requireAllJuryApproval: boolean; // true = unanimous, false = majority + juryGroupId: string | null; // Which jury must approve (default: Jury 3) + minimumApprovalThreshold?: number; // For non-unanimous: minimum % (e.g., 0.67 = 2/3) + + // ── Admin Override ────────────────────────────────────── + adminOverrideEnabled: boolean; // Admin can force result + overrideModes: OverrideMode[]; // Available override options + + // ── Freeze Behavior ───────────────────────────────────── + autoFreezeOnApproval: boolean; // Lock results immediately when all approve + requireExplicitFreeze: boolean; // Even after approval, admin must click "Freeze" + + // ── Per-category ──────────────────────────────────────── + perCategory: boolean; // Separate proposals per STARTUP vs CONCEPT + + // ── Special Awards ────────────────────────────────────── + includeSpecialAwards: boolean; // Include award winners in confirmation + + // ── Deadline ──────────────────────────────────────────── + approvalDeadlineDays: number; // Days jury has to respond (default: 7) + reminderSchedule: number[]; // Days before deadline to remind (e.g., [3, 1]) + + // ── Notification ──────────────────────────────────────── + notifyOnApproval: boolean; // Notify admin when each juror approves + notifyOnRejection: boolean; // Notify admin immediately on any rejection + notifyOnFreeze: boolean; // Notify all parties when results frozen +}; + +type OverrideMode = 'FORCE_MAJORITY' | 'ADMIN_DECISION'; +``` + +### Field Behavior Reference + +| Field | Default | Description | +|-------|---------|-------------| +| `requireAllJuryApproval` | `true` | When true, ALL jury members must approve. When false, only `minimumApprovalThreshold` % needed | +| `juryGroupId` | Finals jury | Links to the JuryGroup that must confirm. Usually the same jury that scored live finals | +| `minimumApprovalThreshold` | `1.0` | Only used when `requireAllJuryApproval=false`. E.g., 0.67 = two-thirds majority | +| `adminOverrideEnabled` | `true` | Whether admin can bypass jury deadlock | +| `overrideModes` | `['FORCE_MAJORITY', 'ADMIN_DECISION']` | FORCE_MAJORITY: accept if >50% approved. ADMIN_DECISION: admin picks winners directly | +| `autoFreezeOnApproval` | `true` | When all approvals received, auto-freeze results | +| `requireExplicitFreeze` | `false` | If true, even after unanimous approval, admin must click "Freeze" to finalize | +| `perCategory` | `true` | Separate WinnerProposal per category | +| `includeSpecialAwards` | `true` | Include special award winners in confirmation package | +| `approvalDeadlineDays` | `7` | Jury has this many days to approve | +| `reminderSchedule` | `[3, 1]` | Reminder emails N days before deadline | + +--- + +## WinnerProposal Lifecycle + +### States + +```typescript +enum WinnerProposalStatus { + PENDING = 'PENDING', // Waiting for jury approvals + APPROVED = 'APPROVED', // All required approvals received + REJECTED = 'REJECTED', // Failed — needs new proposal or override + OVERRIDDEN = 'OVERRIDDEN', // Admin used override power + FROZEN = 'FROZEN', // Locked — official, immutable results +} +``` + +### State Transitions + +``` + ┌───────────────┐ + │ PENDING │◄──── Created from scores + └───────┬───────┘ or admin draft + │ + ┌─────────────┼─────────────┐ + ▼ │ ▼ + All approved Some rejected Admin override + │ │ │ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌────────────┐ + │ APPROVED │ │ REJECTED │ │ OVERRIDDEN │ + └────┬─────┘ └────┬─────┘ └─────┬──────┘ + │ │ │ + │ Create new │ + │ proposal or │ + │ admin override │ + ▼ ▼ + ┌──────────────────────────────────┐ + │ FROZEN │◄── Immutable + └──────────────────────────────────┘ +``` + +### Validity Rules + +| Transition | From | To | Condition | +|------------|------|----|-----------| +| Auto-approve | PENDING | APPROVED | All required approvals received | +| Reject | PENDING | REJECTED | Any jury member rejects (if unanimous required) | +| Override: Force Majority | PENDING/REJECTED | OVERRIDDEN | Admin triggers; >50% approved | +| Override: Admin Decision | PENDING/REJECTED | OVERRIDDEN | Admin provides new rankings | +| Freeze | APPROVED/OVERRIDDEN | FROZEN | Admin triggers (or auto on approval) | +| Revoke freeze | *never* | — | Cannot unfreeze. Must create new proposal | + +--- + +## Proposal Generation + +### Automatic Generation + +When the LIVE_FINAL round completes (all projects scored), the system auto-generates a WinnerProposal: + +```typescript +async function generateWinnerProposal( + competitionId: string, + sourceRoundId: string, + category: CompetitionCategory, + proposedById: string // system or admin user ID +): Promise { + // 1. Fetch all scored projects in this category from the live final round + const scores = await getAggregatedScores(sourceRoundId, category); + + // 2. Rank by final score (jury weight + audience weight) + const ranked = scores + .sort((a, b) => b.finalScore - a.finalScore) + .map(s => s.projectId); + + // 3. Build selection basis (evidence trail) + const selectionBasis = { + method: 'SCORE_RANKING', + sourceRound: sourceRoundId, + scoreBreakdown: scores.map(s => ({ + projectId: s.projectId, + juryScore: s.juryScore, + audienceScore: s.audienceScore, + finalScore: s.finalScore, + rank: s.rank, + })), + generatedAt: new Date().toISOString(), + }; + + // 4. Create proposal + const proposal = await prisma.winnerProposal.create({ + data: { + competitionId, + category, + status: 'PENDING', + rankedProjectIds: ranked, + selectionBasis, + sourceRoundId, + proposedById, + }, + }); + + // 5. Create approval records for each jury member + const juryMembers = await getConfirmationJuryMembers(competitionId); + await prisma.winnerApproval.createMany({ + data: juryMembers.map(member => ({ + winnerProposalId: proposal.id, + userId: member.userId, + role: 'JURY_MEMBER', + })), + }); + + // 6. Send approval request notifications + await notifyJuryForConfirmation(proposal.id, juryMembers); + + return proposal; +} +``` + +### Manual Proposal Creation + +Admins can also create proposals manually (e.g., after an admin-decision override): + +```typescript +async function createManualProposal(input: { + competitionId: string; + category: CompetitionCategory; + rankedProjectIds: string[]; + justification: string; + adminId: string; +}): Promise { + return prisma.winnerProposal.create({ + data: { + competitionId: input.competitionId, + category: input.category, + status: 'PENDING', + rankedProjectIds: input.rankedProjectIds, + selectionBasis: { + method: 'ADMIN_MANUAL', + justification: input.justification, + createdBy: input.adminId, + createdAt: new Date().toISOString(), + }, + sourceRoundId: await getLatestRoundId(input.competitionId), + proposedById: input.adminId, + }, + }); +} +``` + +--- + +## Jury Approval Process + +### Approval Flow + +When a WinnerProposal is created, each jury member on the confirmation jury receives a notification: + +1. **Notification** — Email + in-app alert: "Winner proposal for STARTUP category is ready for your review" +2. **Review** — Jury member opens the confirmation page, sees: + - Ranked list of winners (1st, 2nd, 3rd...) + - Score breakdown per project + - Access to all submitted documents + - Comments from other jury members (if any have responded) +3. **Decision** — Jury member clicks APPROVE or REJECT + - If APPROVE: records timestamp, optional comment + - If REJECT: must provide a reason (required text field) +4. **Progress tracking** — Admin can see real-time progress: "3/5 jury members approved" + +### Jury Confirmation UI + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ 🏆 Winner Confirmation — STARTUP Category │ +│ │ +│ Proposal Status: PENDING (2/5 approved) │ +│ Deadline: February 22, 2026 (5 days remaining) │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Proposed Rankings: │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 🥇 1st Place: OceanClean AI │ │ +│ │ Final Score: 92.4 (Jury: 94.0 | Audience: 86.0) │ │ +│ │ [View Submissions] [View Evaluations] │ │ +│ ├──────────────────────────────────────────────────────────┤ │ +│ │ 🥈 2nd Place: DeepReef Monitoring │ │ +│ │ Final Score: 88.7 (Jury: 87.0 | Audience: 95.0) │ │ +│ │ [View Submissions] [View Evaluations] │ │ +│ ├──────────────────────────────────────────────────────────┤ │ +│ │ 🥉 3rd Place: CoralGuard │ │ +│ │ Final Score: 85.1 (Jury: 86.5 | Audience: 79.0) │ │ +│ │ [View Submissions] [View Evaluations] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ Score Methodology: Jury 70% / Audience 30% │ +│ Source: Round 7 — Live Finals (completed Feb 15, 2026) │ +│ │ +│ ── Your Decision ────────────────────────────────────────── │ +│ │ +│ Comments (optional for approve, required for reject): │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ [ ✓ Approve Rankings ] [ ✗ Reject — Request Revision ] │ +│ │ +│ ── Other Jury Responses ─────────────────────────────────── │ +│ ✓ Juror A — Approved (Feb 16) │ +│ ✓ Juror B — Approved (Feb 16) "Great selections" │ +│ ○ Juror C — Pending │ +│ ○ Juror D — Pending │ +│ ○ Juror E — Pending │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Approval Logic + +```typescript +async function processApproval( + proposalId: string, + userId: string, + approved: boolean, + comments?: string +): Promise<{ proposal: WinnerProposal; isComplete: boolean }> { + // 1. Record the approval/rejection + await prisma.winnerApproval.update({ + where: { winnerProposalId_userId: { winnerProposalId: proposalId, userId } }, + data: { + approved, + comments, + respondedAt: new Date(), + }, + }); + + // 2. Log to audit trail + await prisma.decisionAuditLog.create({ + data: { + entityType: 'WINNER_PROPOSAL', + entityId: proposalId, + action: approved ? 'JURY_APPROVED' : 'JURY_REJECTED', + userId, + details: { comments }, + }, + }); + + // 3. Check if all required approvals are in + const config = await getConfirmationConfig(proposalId); + const allApprovals = await prisma.winnerApproval.findMany({ + where: { winnerProposalId: proposalId }, + }); + + const responded = allApprovals.filter(a => a.respondedAt !== null); + const approvedCount = responded.filter(a => a.approved === true).length; + const rejectedCount = responded.filter(a => a.approved === false).length; + const totalRequired = allApprovals.length; + + let isComplete = false; + let newStatus: WinnerProposalStatus | null = null; + + if (config.requireAllJuryApproval) { + // Unanimous mode + if (rejectedCount > 0) { + newStatus = 'REJECTED'; + isComplete = true; + } else if (approvedCount === totalRequired) { + newStatus = 'APPROVED'; + isComplete = true; + } + } else { + // Threshold mode + const threshold = config.minimumApprovalThreshold ?? 0.5; + if (responded.length === totalRequired) { + if (approvedCount / totalRequired >= threshold) { + newStatus = 'APPROVED'; + } else { + newStatus = 'REJECTED'; + } + isComplete = true; + } + } + + let proposal: WinnerProposal; + if (newStatus) { + proposal = await prisma.winnerProposal.update({ + where: { id: proposalId }, + data: { status: newStatus }, + }); + + // Auto-freeze if configured and approved + if (newStatus === 'APPROVED' && config.autoFreezeOnApproval) { + proposal = await freezeProposal(proposalId, 'SYSTEM'); + } + + // Notify admin of completion + await notifyAdminProposalComplete(proposalId, newStatus); + } else { + proposal = await prisma.winnerProposal.findUniqueOrThrow({ + where: { id: proposalId }, + }); + // Notify admin of progress + if (config.notifyOnApproval && approved) { + await notifyAdminApprovalProgress(proposalId, approvedCount, totalRequired); + } + if (config.notifyOnRejection && !approved) { + await notifyAdminRejection(proposalId, userId, comments); + } + } + + return { proposal, isComplete }; +} +``` + +--- + +## Admin Override System + +The admin override exists for when jury consensus fails or when extraordinary circumstances require admin intervention. + +### Override Modes + +#### FORCE_MAJORITY + +Accept the proposal if more than 50% of jury members approved, even though unanimous approval was required. + +```typescript +async function overrideForceMajority( + proposalId: string, + adminId: string, + reason: string +): Promise { + const approvals = await prisma.winnerApproval.findMany({ + where: { winnerProposalId: proposalId }, + }); + + const approvedCount = approvals.filter(a => a.approved === true).length; + const total = approvals.length; + + if (approvedCount <= total / 2) { + throw new TRPCError({ + code: 'BAD_REQUEST', + message: `Cannot force majority: only ${approvedCount}/${total} approved (need >50%)`, + }); + } + + const proposal = await prisma.winnerProposal.update({ + where: { id: proposalId }, + data: { + status: 'OVERRIDDEN', + overrideById: adminId, + overrideReason: reason, + overrideAt: new Date(), + }, + }); + + await prisma.decisionAuditLog.create({ + data: { + entityType: 'WINNER_PROPOSAL', + entityId: proposalId, + action: 'ADMIN_FORCE_MAJORITY', + userId: adminId, + details: { + reason, + approvedCount, + totalJurors: total, + rejections: approvals + .filter(a => a.approved === false) + .map(a => ({ userId: a.userId, comments: a.comments })), + }, + }, + }); + + return proposal; +} +``` + +#### ADMIN_DECISION + +Admin directly selects winners, bypassing jury vote entirely. This is the nuclear option for deadlocked juries or exceptional circumstances. + +```typescript +async function overrideAdminDecision( + proposalId: string, + adminId: string, + newRankedProjectIds: string[], + reason: string +): Promise { + // Store original rankings for audit + const original = await prisma.winnerProposal.findUniqueOrThrow({ + where: { id: proposalId }, + }); + + const proposal = await prisma.winnerProposal.update({ + where: { id: proposalId }, + data: { + status: 'OVERRIDDEN', + rankedProjectIds: newRankedProjectIds, + overrideById: adminId, + overrideReason: reason, + overrideAt: new Date(), + selectionBasis: { + ...((original.selectionBasis as Record) ?? {}), + overrideHistory: { + originalRanking: original.rankedProjectIds, + newRanking: newRankedProjectIds, + reason, + overriddenBy: adminId, + overriddenAt: new Date().toISOString(), + }, + }, + }, + }); + + await prisma.decisionAuditLog.create({ + data: { + entityType: 'WINNER_PROPOSAL', + entityId: proposalId, + action: 'ADMIN_DECISION_OVERRIDE', + userId: adminId, + details: { + reason, + originalRanking: original.rankedProjectIds, + newRanking: newRankedProjectIds, + }, + }, + }); + + return proposal; +} +``` + +### Admin Override UI + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ ⚠️ Override Winner Proposal — STARTUP Category │ +│ │ +│ Current Status: REJECTED │ +│ Jury Votes: 3 Approved / 2 Rejected │ +│ │ +│ ── Override Options ─────────────────────────────────────── │ +│ │ +│ ○ Force Majority │ +│ Accept current rankings since 3/5 (60%) approved. │ +│ Rankings remain as originally proposed. │ +│ │ +│ ○ Admin Decision │ +│ Override rankings entirely. You will set the final order. │ +│ │ +│ ── Override Reason (required) ───────────────────────────── │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Two jurors had scheduling conflicts and could not review │ │ +│ │ all presentations. Accepting majority recommendation. │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ⚠ This action is logged and cannot be undone. │ +│ │ +│ [ Cancel ] [ Apply Override ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Admin Decision — Reorder UI + +When ADMIN_DECISION mode is selected: + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Admin Decision — Set Final Rankings │ +│ │ +│ Drag to reorder. This becomes the official result. │ +│ │ +│ ┌────┬──────────────────────────────┬──────────┬────────────┐ │ +│ │ # │ Project │ Score │ Actions │ │ +│ ├────┼──────────────────────────────┼──────────┼────────────┤ │ +│ │ 1 │ ≡ OceanClean AI │ 92.4 │ ↑ ↓ │ │ +│ │ 2 │ ≡ DeepReef Monitoring │ 88.7 │ ↑ ↓ │ │ +│ │ 3 │ ≡ CoralGuard │ 85.1 │ ↑ ↓ │ │ +│ │ 4 │ ≡ WaveEnergy Solutions │ 82.3 │ ↑ ↓ │ │ +│ │ 5 │ ≡ PlasticHarvest │ 79.8 │ ↑ ↓ │ │ +│ └────┴──────────────────────────────┴──────────┴────────────┘ │ +│ │ +│ Why are you overriding the score-based ranking? │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ [ Cancel ] [ Confirm Final Rankings ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Result Freezing + +### What Freeze Does + +Freezing a WinnerProposal makes it **immutable** — the official, permanent record of the competition results. + +```typescript +async function freezeProposal( + proposalId: string, + triggeredBy: string // userId or 'SYSTEM' for auto-freeze +): Promise { + const proposal = await prisma.winnerProposal.findUniqueOrThrow({ + where: { id: proposalId }, + }); + + if (proposal.status !== 'APPROVED' && proposal.status !== 'OVERRIDDEN') { + throw new TRPCError({ + code: 'BAD_REQUEST', + message: `Cannot freeze proposal in ${proposal.status} status. Must be APPROVED or OVERRIDDEN.`, + }); + } + + const frozen = await prisma.winnerProposal.update({ + where: { id: proposalId }, + data: { + status: 'FROZEN', + frozenById: triggeredBy === 'SYSTEM' ? null : triggeredBy, + frozenAt: new Date(), + }, + }); + + // Log the freeze + await prisma.decisionAuditLog.create({ + data: { + entityType: 'WINNER_PROPOSAL', + entityId: proposalId, + action: 'RESULTS_FROZEN', + userId: triggeredBy === 'SYSTEM' ? undefined : triggeredBy, + details: { + category: proposal.category, + rankedProjectIds: proposal.rankedProjectIds, + frozenAt: new Date().toISOString(), + method: triggeredBy === 'SYSTEM' ? 'AUTO_FREEZE' : 'MANUAL_FREEZE', + }, + }, + }); + + // Update round status to COMPLETED + const config = await getConfirmationConfig(proposalId); + if (config.perCategory) { + // Check if ALL categories are frozen before completing the round + const allProposals = await prisma.winnerProposal.findMany({ + where: { competitionId: proposal.competitionId }, + }); + const allFrozen = allProposals.every(p => p.status === 'FROZEN'); + if (allFrozen) { + await completeConfirmationRound(proposal.competitionId); + } + } else { + await completeConfirmationRound(proposal.competitionId); + } + + // Send freeze notifications + await notifyResultsFrozen(proposalId); + + return frozen; +} +``` + +### Freeze Immutability + +Once frozen, a WinnerProposal **cannot be modified**. The following are enforced: + +| Operation | Allowed on FROZEN? | Alternative | +|-----------|--------------------|-------------| +| Change rankings | No | Create a new WinnerProposal | +| Change status | No | — | +| Add approvals | No | — | +| Delete proposal | No | — | +| Create new proposal | Yes | New proposal supersedes (admin must mark old as "superseded" in notes) | + +### Freeze Guard Middleware + +```typescript +// Applied to all mutation procedures on WinnerProposal +function assertNotFrozen(proposalId: string) { + const proposal = await prisma.winnerProposal.findUniqueOrThrow({ + where: { id: proposalId }, + }); + if (proposal.status === 'FROZEN') { + throw new TRPCError({ + code: 'FORBIDDEN', + message: 'This winner proposal is frozen and cannot be modified. Create a new proposal if changes are needed.', + }); + } +} +``` + +--- + +## Special Awards in Confirmation + +When `includeSpecialAwards: true`, the confirmation round also covers special award winners. + +### Special Award Winner Proposals + +Each special award generates its own mini-proposal, but the confirmation process bundles them together: + +```typescript +type ConfirmationPackage = { + // Main competition winners + mainProposals: { + startup: WinnerProposal; + concept: WinnerProposal; + }; + + // Special award winners + awardProposals: { + awardId: string; + awardName: string; + winnerId: string; // project ID + method: 'JURY_VOTE' | 'AUDIENCE_VOTE' | 'COMBINED_VOTE'; + score: number; + }[]; +}; +``` + +### Confirmation UI with Awards + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Winner Confirmation — Full Package │ +│ │ +│ ═══ STARTUP Category ════════════════════════════════════════ │ +│ Status: APPROVED ✓ [Freeze Results] │ +│ 1st: OceanClean AI (92.4) │ +│ 2nd: DeepReef Monitoring (88.7) │ +│ 3rd: CoralGuard (85.1) │ +│ │ +│ ═══ CONCEPT Category ════════════════════════════════════════ │ +│ Status: PENDING (4/5 approved) │ +│ 1st: BlueTide Analytics (89.2) │ +│ 2nd: MarineData Hub (84.6) │ +│ 3rd: SeaWatch Network (81.3) │ +│ │ +│ ═══ Special Awards ══════════════════════════════════════════ │ +│ Innovation Award: OceanClean AI — Jury Vote (Score: 9.2) │ +│ Impact Award: BlueTide Analytics — Combined (Score: 8.8) │ +│ Community Award: SeaWatch Network — Audience Vote │ +│ │ +│ ── Actions ───────────────────────────────────────────────── │ +│ [ Freeze All Approved ] [ Override Pending ] [ Export PDF ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Admin Confirmation Dashboard + +### Full Dashboard Layout + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ MOPC 2026 — Winner Confirmation │ +│ Round 8 of 8 | Status: ACTIVE │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ Progress Summary │ │ +│ │ ┌──────────┬──────────┬──────────┬───────────────────┐ │ │ +│ │ │ Category │ Status │ Approvals│ Deadline │ │ │ +│ │ ├──────────┼──────────┼──────────┼───────────────────┤ │ │ +│ │ │ STARTUP │ APPROVED │ 5/5 ✓ │ — (complete) │ │ │ +│ │ │ CONCEPT │ PENDING │ 4/5 │ Feb 22 (5 days) │ │ │ +│ │ └──────────┴──────────┴──────────┴───────────────────┘ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ Jury Approval Timeline │ │ +│ │ │ │ +│ │ Feb 15 ●────────────────────────────── Proposal sent │ │ +│ │ Feb 16 ●── Juror A approved ✓ │ │ +│ │ Feb 16 ●── Juror B approved ✓ │ │ +│ │ Feb 17 ●── Juror C approved ✓ │ │ +│ │ Feb 17 ●── Juror D approved ✓ │ │ +│ │ Feb ?? ○── Juror E — awaiting response │ │ +│ │ │ │ +│ │ [Send Reminder to Juror E] │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ Audit Trail │ │ +│ │ Feb 17 14:32 — Juror D approved CONCEPT proposal │ │ +│ │ Feb 17 14:30 — Juror D approved STARTUP proposal │ │ +│ │ Feb 17 10:15 — Juror C approved CONCEPT proposal │ │ +│ │ Feb 16 09:22 — Juror B approved with comment │ │ +│ │ Feb 16 09:10 — Juror A approved both categories │ │ +│ │ Feb 15 18:00 — Proposals auto-generated from Round 7 │ │ +│ │ [View Full Audit Log] │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ Actions: │ +│ [ Freeze STARTUP Results ] [ Override CONCEPT ] │ +│ [ Send Reminder ] [ Export Results PDF ] [ Create New Proposal]│ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Notification Flow + +### Notification Events + +| Event | Recipients | Channel | Timing | +|-------|-----------|---------|--------| +| Proposal created | All confirmation jury | Email + In-app | Immediate | +| Jury member approves | Admin | In-app | Immediate | +| Jury member rejects | Admin | Email + In-app | Immediate | +| All approved (unanimous) | Admin + All jury | Email | Immediate | +| Proposal rejected (failed) | Admin | Email + In-app | Immediate | +| Admin override applied | All jury | Email | Immediate | +| Results frozen | All jury + Admin | Email + In-app | Immediate | +| Approval deadline approaching | Pending jury members | Email | Per reminderSchedule | +| Approval deadline passed | Admin | Email + In-app | Immediate | + +### Notification Templates + +```typescript +const CONFIRMATION_NOTIFICATIONS = { + PROPOSAL_CREATED: { + subject: 'MOPC 2026 — Winner Confirmation Required', + body: `The winner proposal for {{category}} category is ready for your review. + Please log in and confirm or reject the proposed rankings by {{deadline}}. + + Proposed Winners: + {{#each rankedProjects}} + {{rank}}. {{name}} (Score: {{score}}) + {{/each}}`, + }, + + APPROVAL_RECEIVED: { + subject: 'MOPC 2026 — Confirmation Progress Update', + body: `{{jurorName}} has {{approved ? "approved" : "rejected"}} the {{category}} proposal. + Progress: {{approvedCount}}/{{totalJurors}} approved. + {{#if comments}}Comment: "{{comments}}"{{/if}}`, + }, + + RESULTS_FROZEN: { + subject: 'MOPC 2026 — Official Results Confirmed', + body: `The {{category}} category results have been officially confirmed and frozen. + + Official Winners: + {{#each rankedProjects}} + {{rank}}. {{name}} + {{/each}} + + These results are now immutable and represent the official outcome.`, + }, + + DEADLINE_REMINDER: { + subject: 'MOPC 2026 — Confirmation Deadline in {{daysRemaining}} days', + body: `You have not yet responded to the {{category}} winner proposal. + Please review and respond by {{deadline}}. + + [Review Proposal →]`, + }, +}; +``` + +--- + +## API Changes + +### New tRPC Procedures + +```typescript +// src/server/routers/winner-confirmation.ts + +export const winnerConfirmationRouter = router({ + // ── Proposals ────────────────────────────────────────── + + /** Generate proposals from live final scores */ + generateProposals: adminProcedure + .input(z.object({ + competitionId: z.string(), + sourceRoundId: z.string(), + })) + .mutation(async ({ input, ctx }) => { ... }), + + /** Create manual proposal (admin override scenario) */ + createManualProposal: adminProcedure + .input(z.object({ + competitionId: z.string(), + category: z.enum(['STARTUP', 'BUSINESS_CONCEPT']), + rankedProjectIds: z.array(z.string()).min(1), + justification: z.string().min(10), + })) + .mutation(async ({ input, ctx }) => { ... }), + + /** Get proposal with approvals */ + getProposal: protectedProcedure + .input(z.object({ proposalId: z.string() })) + .query(async ({ input }) => { ... }), + + /** List all proposals for a competition */ + listProposals: protectedProcedure + .input(z.object({ competitionId: z.string() })) + .query(async ({ input }) => { ... }), + + /** Get the full confirmation package (main + awards) */ + getConfirmationPackage: adminProcedure + .input(z.object({ competitionId: z.string() })) + .query(async ({ input }) => { ... }), + + // ── Approvals ────────────────────────────────────────── + + /** Jury member approves or rejects */ + submitApproval: juryProcedure + .input(z.object({ + proposalId: z.string(), + approved: z.boolean(), + comments: z.string().optional(), + })) + .mutation(async ({ input, ctx }) => { ... }), + + /** Get my pending approvals */ + getMyPendingApprovals: juryProcedure + .query(async ({ ctx }) => { ... }), + + /** Get approval progress for a proposal */ + getApprovalProgress: protectedProcedure + .input(z.object({ proposalId: z.string() })) + .query(async ({ input }) => { ... }), + + // ── Admin Overrides ──────────────────────────────────── + + /** Force majority acceptance */ + overrideForceMajority: adminProcedure + .input(z.object({ + proposalId: z.string(), + reason: z.string().min(10), + })) + .mutation(async ({ input, ctx }) => { ... }), + + /** Admin directly sets winners */ + overrideAdminDecision: adminProcedure + .input(z.object({ + proposalId: z.string(), + newRankedProjectIds: z.array(z.string()).min(1), + reason: z.string().min(10), + })) + .mutation(async ({ input, ctx }) => { ... }), + + // ── Freeze ───────────────────────────────────────────── + + /** Freeze a proposal (make results official) */ + freezeProposal: adminProcedure + .input(z.object({ proposalId: z.string() })) + .mutation(async ({ input, ctx }) => { ... }), + + /** Freeze all approved proposals at once */ + freezeAll: adminProcedure + .input(z.object({ competitionId: z.string() })) + .mutation(async ({ input, ctx }) => { ... }), + + // ── Notifications ────────────────────────────────────── + + /** Send reminder to pending jury members */ + sendReminder: adminProcedure + .input(z.object({ + proposalId: z.string(), + userIds: z.array(z.string()).optional(), // specific jurors, or all pending + })) + .mutation(async ({ input }) => { ... }), + + // ── Export ───────────────────────────────────────────── + + /** Export results as PDF */ + exportResultsPdf: adminProcedure + .input(z.object({ competitionId: z.string() })) + .mutation(async ({ input }) => { ... }), + + /** Export results as structured JSON */ + exportResultsJson: adminProcedure + .input(z.object({ competitionId: z.string() })) + .query(async ({ input }) => { ... }), +}); +``` + +--- + +## Service Functions + +### winner-confirmation.ts + +```typescript +// src/server/services/winner-confirmation.ts + +/** Generate proposals for all categories from live final scores */ +export async function generateProposalsFromScores( + competitionId: string, + sourceRoundId: string, + triggeredBy: string +): Promise; + +/** Create a manual proposal with admin-specified rankings */ +export async function createManualProposal( + competitionId: string, + category: CompetitionCategory, + rankedProjectIds: string[], + justification: string, + adminId: string +): Promise; + +/** Process a jury member's approval/rejection */ +export async function processApproval( + proposalId: string, + userId: string, + approved: boolean, + comments?: string +): Promise<{ proposal: WinnerProposal; isComplete: boolean }>; + +/** Override with force-majority rule */ +export async function overrideForceMajority( + proposalId: string, + adminId: string, + reason: string +): Promise; + +/** Override with admin-selected rankings */ +export async function overrideAdminDecision( + proposalId: string, + adminId: string, + newRankedProjectIds: string[], + reason: string +): Promise; + +/** Freeze a proposal — makes results immutable */ +export async function freezeProposal( + proposalId: string, + triggeredBy: string +): Promise; + +/** Freeze all approved/overridden proposals for a competition */ +export async function freezeAllApproved( + competitionId: string, + adminId: string +): Promise; + +/** Get the full confirmation package (main winners + special awards) */ +export async function getConfirmationPackage( + competitionId: string +): Promise; + +/** Check if all categories are frozen for a competition */ +export async function isFullyFrozen( + competitionId: string +): Promise; + +/** Send reminder notifications to pending jury members */ +export async function sendApprovalReminder( + proposalId: string, + specificUserIds?: string[] +): Promise; + +/** Get aggregated scores from the source round */ +export async function getAggregatedScores( + roundId: string, + category: CompetitionCategory +): Promise; + +/** Export frozen results as a structured document */ +export async function exportResults( + competitionId: string, + format: 'json' | 'pdf' +): Promise>; +``` + +--- + +## Edge Cases + +| Scenario | Handling | +|----------|----------| +| **Jury member doesn't respond by deadline** | Admin notified. Can send reminders or use override | +| **All jurors reject** | Status = REJECTED. Admin must override or create new proposal | +| **Juror tries to change vote after submitting** | Not allowed. Must contact admin to reset vote | +| **Admin resets a juror's vote** | Audit logged. Juror re-notified to vote again | +| **Tie in live finals scores** | Proposal lists tied projects at same rank. Admin resolves via override | +| **Proposal frozen, then error discovered** | Cannot unfreeze. Admin creates new proposal with explanation | +| **Juror is on multiple categories** | Separate approval records per proposal (per-category) | +| **Competition has no special awards** | `includeSpecialAwards` is false; only main proposals | +| **Admin freezes before all categories confirmed** | Allowed — each category freezes independently | +| **Network failure during approval** | Optimistic UI with retry. Server-side idempotency via unique constraint | +| **Juror removed from jury group after proposal sent** | Approval record remains but marked as N/A. Threshold recalculated | +| **Multiple proposals for same category** | Only latest non-frozen proposal is active. Previous ones archived | +| **Live finals not yet complete** | Cannot generate proposal — round must be in COMPLETED status | +| **Admin tries to freeze PENDING proposal** | Blocked — must be APPROVED or OVERRIDDEN first | + +--- + +## Integration Points + +### Inbound (from other rounds/systems) + +| Source | Data | Purpose | +|--------|------|---------| +| Round 7 (LIVE_FINAL) | Aggregated scores, rankings | Auto-generate WinnerProposal | +| JuryGroup (Jury 3) | Member list | Determine who must approve | +| SpecialAward system | Award winners | Include in confirmation package | +| Competition settings | Category config | Per-category proposals | + +### Outbound (to other systems) + +| Target | Data | Purpose | +|--------|------|---------| +| DecisionAuditLog | All actions | Full audit trail | +| Notification system | Events | Email + in-app alerts | +| Export service | Frozen results | PDF/JSON export for records | +| Admin dashboard | Progress metrics | Real-time status display | +| Competition status | COMPLETED flag | Mark competition as finished | + +### Confirmation → Competition Completion + +When all proposals are frozen: + +```typescript +async function completeConfirmationRound(competitionId: string): Promise { + // 1. Mark the confirmation round as COMPLETED + const confirmationRound = await prisma.round.findFirst({ + where: { competitionId, roundType: 'CONFIRMATION' }, + }); + + if (confirmationRound) { + await prisma.round.update({ + where: { id: confirmationRound.id }, + data: { status: 'ROUND_COMPLETED' }, + }); + } + + // 2. Update competition status + await prisma.competition.update({ + where: { id: competitionId }, + data: { status: 'CLOSED' }, + }); + + // 3. Log competition completion + await prisma.decisionAuditLog.create({ + data: { + entityType: 'COMPETITION', + entityId: competitionId, + action: 'COMPETITION_COMPLETED', + details: { + completedAt: new Date().toISOString(), + reason: 'All winner proposals frozen', + }, + }, + }); + + // 4. Send competition-complete notifications + await notifyCompetitionComplete(competitionId); +} +``` + +--- + +## Security Considerations + +| Concern | Mitigation | +|---------|------------| +| **Jury member votes for wrong proposal** | Proposals are category-specific; UI shows only relevant proposal | +| **Admin forges jury approvals** | Approvals tied to authenticated session; audit log captures userId | +| **Results tampered after freeze** | FROZEN status enforced at database level; no UPDATE allowed | +| **Unauthorized freeze** | Only SUPER_ADMIN and PROGRAM_ADMIN can freeze (adminProcedure) | +| **Replay attack on approval** | Unique constraint on [winnerProposalId, userId] prevents double-voting | +| **Override without justification** | `reason` field is required (min 10 chars) on all overrides | +| **PDF export tampering** | Export includes cryptographic hash of frozen proposal data | + +--- + +## Results Export Format + +### JSON Export + +```typescript +type ExportedResults = { + competition: { + id: string; + name: string; + programYear: number; + }; + exportedAt: string; + exportedBy: string; + + categories: { + category: string; + proposalId: string; + status: WinnerProposalStatus; + frozenAt: string; + + winners: { + rank: number; + project: { + id: string; + name: string; + teamName: string; + category: string; + }; + scores: { + juryScore: number; + audienceScore: number; + finalScore: number; + }; + }[]; + + approvals: { + jurorName: string; + approved: boolean; + respondedAt: string; + comments?: string; + }[]; + + override?: { + type: string; + reason: string; + overriddenBy: string; + overriddenAt: string; + }; + }[]; + + specialAwards: { + awardName: string; + winnerProject: string; + method: string; + score: number; + }[]; + + // Integrity hash + integrityHash: string; +}; +``` + +### PDF Export Structure + +The PDF export contains: +1. **Cover page** — Competition name, year, date of confirmation +2. **Main winners** — Per category: ranked list with scores, team info +3. **Special awards** — Award name, winner, scoring method +4. **Jury confirmations** — List of all approvals with timestamps +5. **Override record** — If any override was used, full details +6. **Audit summary** — Key events from the audit trail +7. **Integrity hash** — SHA-256 of all frozen proposal data diff --git a/docs/claude-architecture-redesign/11-special-awards.md b/docs/claude-architecture-redesign/11-special-awards.md new file mode 100644 index 0000000..8ab1089 --- /dev/null +++ b/docs/claude-architecture-redesign/11-special-awards.md @@ -0,0 +1,965 @@ +# Special Awards System + +## Overview + +Special Awards are standalone award tracks that run parallel to the main competition flow. They enable the MOPC platform to recognize excellence in specific areas (e.g., "Innovation Award", "Impact Award", "Youth Leadership Award") with dedicated juries and evaluation processes while referencing the same pool of projects. + +### Purpose + +Special Awards serve three key purposes: + +1. **Parallel Recognition** — Recognize excellence in specific domains beyond the main competition prizes +2. **Specialized Evaluation** — Enable dedicated jury groups with domain expertise to evaluate specific criteria +3. **Flexible Integration** — Awards can piggyback on main rounds or run independently with their own timelines + +### Design Philosophy + +- **Standalone Entities** — Awards are not tracks; they're first-class entities linked to competitions +- **Two Modes** — STAY_IN_MAIN (piggyback evaluation) or SEPARATE_POOL (independent flow) +- **Dedicated Juries** — Each award can have its own jury group with unique members or shared members +- **Flexible Eligibility** — AI-suggested, manual, round-based, or all-eligible modes +- **Integration with Results** — Award results feed into the confirmation round alongside main competition winners + +--- + +## Current System Analysis + +### Current Architecture (Pipeline-Based) + +**Current State:** +``` +Program + └── Pipeline + ├── Track: "Main Competition" (MAIN) + └── Track: "Innovation Award" (AWARD) + ├── Stage: "Evaluation" (EVALUATION) + └── Stage: "Results" (RESULTS) + +SpecialAward { + id, programId, name, description + trackId → Track (AWARD track) + criteriaText (for AI) + scoringMode: PICK_WINNER | RANKED | SCORED + votingStartAt, votingEndAt + winnerProjectId + useAiEligibility: boolean +} + +AwardEligibility { awardId, projectId, eligible, method, aiReasoningJson } +AwardJuror { awardId, userId } +AwardVote { awardId, userId, projectId, rank? } +``` + +**Current Flow:** +1. Admin creates AWARD track within pipeline +2. Admin configures SpecialAward linked to track +3. Projects routed to award track via ProjectStageState +4. AI or manual eligibility determination +5. Award jurors evaluate/vote +6. Winner selected (admin/award master decision) + +**Current Limitations:** +- Awards tied to track concept (being eliminated) +- No distinction between "piggyback" awards and independent awards +- No round-based eligibility +- No jury group integration +- No evaluation form linkage +- No audience voting support +- No integration with confirmation round + +--- + +## Redesigned System: Two Award Modes + +### Mode 1: STAY_IN_MAIN + +**Concept:** Projects remain in the main competition flow. A dedicated award jury evaluates them using the same submissions, during the same evaluation windows. + +**Use Case:** "Innovation Award" — Members of Jury 2 who also serve on the Innovation Award jury score projects specifically for innovation criteria during the Jury 2 evaluation round. + +**Characteristics:** +- Projects never leave main track +- Award jury evaluates during specific main evaluation rounds +- Award jury sees the same docs/submissions as main jury +- Award uses its own evaluation form with award-specific criteria +- No separate stages/timeline needed +- Results announced alongside main results + +**Data Flow:** +``` +Competition → Round 5 (Jury 2 Evaluation) + ├─ Main Jury (Jury 2) evaluates with standard criteria + └─ Innovation Award Jury evaluates same projects with innovation criteria + +SpecialAward { + evaluationMode: "STAY_IN_MAIN" + evaluationRoundId: "round-5" ← Which main round this award evaluates during + juryGroupId: "innovation-jury" ← Dedicated jury + evaluationFormId: "innovation-form" ← Award-specific criteria +} +``` + +### Mode 2: SEPARATE_POOL + +**Concept:** Dedicated evaluation with separate criteria, submission requirements, and timeline. Projects may be pulled out for award-specific evaluation. + +**Use Case:** "Community Impact Award" — Separate jury evaluates finalists specifically for community impact using a unique rubric and potentially additional documentation. + +**Characteristics:** +- Own jury group with unique members +- Own evaluation criteria/form +- Can have own submission requirements +- Runs on its own timeline +- Can pull projects from specific rounds +- Independent results timeline + +**Data Flow:** +``` +Competition + └── SpecialAward { + evaluationMode: "SEPARATE_POOL" + eligibilityMode: "ROUND_BASED" ← Projects from Round 5 (finalists) + juryGroupId: "impact-jury" + evaluationFormId: "impact-form" + votingStartAt: [own window] + votingEndAt: [own window] + } +``` + +--- + +## Enhanced SpecialAward Model + +### Complete Schema + +```prisma +model SpecialAward { + id String @id @default(cuid()) + competitionId String // CHANGED: Links to Competition, not Track + name String + description String? @db.Text + + // Eligibility configuration + eligibilityMode AwardEligibilityMode @default(AI_SUGGESTED) + eligibilityCriteria Json? @db.JsonB // Mode-specific config + + // Evaluation configuration + evaluationMode AwardEvaluationMode @default(STAY_IN_MAIN) + evaluationRoundId String? // Which main round (for STAY_IN_MAIN) + evaluationFormId String? // Custom criteria + juryGroupId String? // Dedicated or shared jury + + // Voting configuration + votingMode AwardVotingMode @default(JURY_ONLY) + scoringMode AwardScoringMode @default(PICK_WINNER) + maxRankedPicks Int? // For RANKED mode + maxWinners Int @default(1) // Number of winners + audienceVotingWeight Float? // 0.0-1.0 for COMBINED mode + + // Timing + votingStartAt DateTime? + votingEndAt DateTime? + + // Results + status AwardStatus @default(DRAFT) + winnerProjectId String? // Single winner (for backward compat) + + // AI eligibility + useAiEligibility Boolean @default(false) + criteriaText String? @db.Text // Plain-language for AI + + // Job tracking (for AI eligibility) + eligibilityJobStatus String? + eligibilityJobTotal Int? + eligibilityJobDone Int? + eligibilityJobError String? @db.Text + eligibilityJobStarted DateTime? + + sortOrder Int @default(0) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + competition Competition @relation(fields: [competitionId], references: [id], onDelete: Cascade) + evaluationRound Round? @relation("AwardEvaluationRound", fields: [evaluationRoundId], references: [id], onDelete: SetNull) + evaluationForm EvaluationForm? @relation(fields: [evaluationFormId], references: [id], onDelete: SetNull) + juryGroup JuryGroup? @relation("AwardJuryGroup", fields: [juryGroupId], references: [id], onDelete: SetNull) + winnerProject Project? @relation("AwardWinner", fields: [winnerProjectId], references: [id], onDelete: SetNull) + + eligibilities AwardEligibility[] + votes AwardVote[] + winners AwardWinner[] // NEW: Multi-winner support + + @@index([competitionId]) + @@index([status]) + @@index([evaluationRoundId]) + @@index([juryGroupId]) +} + +enum AwardEligibilityMode { + AI_SUGGESTED // AI analyzes and suggests eligible projects + MANUAL // Admin manually selects eligible projects + ALL_ELIGIBLE // All projects in competition are eligible + ROUND_BASED // All projects that reach a specific round +} + +enum AwardEvaluationMode { + STAY_IN_MAIN // Evaluate during main competition round + SEPARATE_POOL // Independent evaluation flow +} + +enum AwardVotingMode { + JURY_ONLY // Only jury votes + AUDIENCE_ONLY // Only audience votes + COMBINED // Jury + audience with weighted scoring +} + +enum AwardScoringMode { + PICK_WINNER // Simple winner selection (1 or N winners) + RANKED // Ranked-choice voting + SCORED // Criteria-based scoring +} + +enum AwardStatus { + DRAFT + NOMINATIONS_OPEN + EVALUATION // NEW: Award jury evaluation in progress + DECIDED // NEW: Winner(s) selected, pending announcement + ANNOUNCED // NEW: Winner(s) publicly announced + ARCHIVED +} +``` + +### New Model: AwardWinner (Multi-Winner Support) + +```prisma +model AwardWinner { + id String @id @default(cuid()) + awardId String + projectId String + rank Int // 1st place, 2nd place, etc. + + // Selection metadata + selectedAt DateTime @default(now()) + selectedById String + selectionMethod String // "JURY_VOTE" | "AUDIENCE_VOTE" | "COMBINED" | "ADMIN_DECISION" + + // Score breakdown (for transparency) + juryScore Float? + audienceScore Float? + finalScore Float? + + createdAt DateTime @default(now()) + + // Relations + award SpecialAward @relation(fields: [awardId], references: [id], onDelete: Cascade) + project Project @relation("AwardWinners", fields: [projectId], references: [id], onDelete: Cascade) + selectedBy User @relation("AwardWinnerSelector", fields: [selectedById], references: [id]) + + @@unique([awardId, projectId]) + @@unique([awardId, rank]) + @@index([awardId]) + @@index([projectId]) +} +``` + +### Enhanced AwardVote Model + +```prisma +model AwardVote { + id String @id @default(cuid()) + awardId String + userId String? // Nullable for audience votes + projectId String + + // Voting type + isAudienceVote Boolean @default(false) + + // Scoring (mode-dependent) + rank Int? // For RANKED mode (1 = first choice) + score Float? // For SCORED mode + + // Criteria scores (for SCORED mode) + criterionScoresJson Json? @db.JsonB + + votedAt DateTime @default(now()) + + // Relations + award SpecialAward @relation(fields: [awardId], references: [id], onDelete: Cascade) + user User? @relation(fields: [userId], references: [id], onDelete: Cascade) + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + + @@unique([awardId, userId, projectId]) + @@index([awardId]) + @@index([userId]) + @@index([projectId]) + @@index([awardId, isAudienceVote]) +} +``` + +--- + +## Eligibility System Deep Dive + +### Eligibility Modes + +#### 1. AI_SUGGESTED + +AI analyzes all projects and suggests eligible ones based on plain-language criteria. + +**Config JSON:** +```typescript +type AISuggestedConfig = { + criteriaText: string // "Projects using innovative ocean tech" + confidenceThreshold: number // 0.0-1.0 (default: 0.7) + autoAcceptAbove: number // Auto-accept above this (default: 0.9) + requireManualReview: boolean // All need admin review (default: false) + sourceRoundId?: string // Only projects from this round +} +``` + +**Flow:** +1. Admin triggers AI eligibility analysis +2. AI processes projects in batches (anonymized) +3. AI returns: `{ projectId, eligible, confidence, reasoning }` +4. High-confidence results auto-applied +5. Medium-confidence results flagged for review +6. Low-confidence results rejected (or flagged if `requireManualReview: true`) + +**UI:** +``` +┌─────────────────────────────────────────────────────────────┐ +│ Innovation Award — AI Eligibility Analysis │ +├─────────────────────────────────────────────────────────────┤ +│ Status: Running... (47/120 projects analyzed) │ +│ [████████████████░░░░░░░░] 68% │ +│ │ +│ Results So Far: │ +│ ✓ Auto-Accepted (confidence > 0.9): 12 projects │ +│ ⚠ Flagged for Review (0.6-0.9): 23 projects │ +│ ✗ Rejected (< 0.6): 12 projects │ +│ │ +│ [View Flagged Projects] [Stop Analysis] │ +└─────────────────────────────────────────────────────────────┘ +``` + +#### 2. MANUAL + +Admin manually selects eligible projects. + +**Config JSON:** +```typescript +type ManualConfig = { + sourceRoundId?: string // Limit to projects from specific round + categoryFilter?: "STARTUP" | "BUSINESS_CONCEPT" + tagFilters?: string[] // Only projects with these tags +} +``` + +#### 3. ALL_ELIGIBLE + +All projects in the competition are automatically eligible. + +**Config JSON:** +```typescript +type AllEligibleConfig = { + minimumStatus?: ProjectStatus // e.g., "SEMIFINALIST" or above + excludeWithdrawn: boolean // Exclude WITHDRAWN (default: true) +} +``` + +#### 4. ROUND_BASED + +All projects that reach a specific round are automatically eligible. + +**Config JSON:** +```typescript +type RoundBasedConfig = { + sourceRoundId: string // Required: which round + requiredState: ProjectRoundStateValue // PASSED, COMPLETED, etc. + autoUpdate: boolean // Auto-update when projects advance (default: true) +} +``` + +**Example:** +```json +{ + "sourceRoundId": "round-5-jury-2", + "requiredState": "PASSED", + "autoUpdate": true +} +``` + +### Admin Override System + +**All eligibility modes support admin override:** + +```prisma +model AwardEligibility { + id String @id @default(cuid()) + awardId String + projectId String + + // Original determination + method EligibilityMethod @default(AUTO) // AUTO, AI, MANUAL + eligible Boolean @default(false) + aiReasoningJson Json? @db.JsonB + + // Override + overriddenBy String? + overriddenAt DateTime? + overrideReason String? @db.Text + + // Final decision + finalEligible Boolean // Computed: overridden ? override : original + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + award SpecialAward @relation(fields: [awardId], references: [id], onDelete: Cascade) + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + overriddenByUser User? @relation("AwardEligibilityOverriddenBy", fields: [overriddenBy], references: [id]) + + @@unique([awardId, projectId]) + @@index([awardId, eligible]) + @@index([awardId, finalEligible]) +} +``` + +--- + +## Award Jury Groups + +### Integration with JuryGroup Model + +Awards can have: +1. **Dedicated Jury** — Own `JuryGroup` with unique members +2. **Shared Jury** — Reuse existing competition jury group (e.g., Jury 2) +3. **Mixed Jury** — Some overlap with main jury, some unique members + +**Example:** +```typescript +// Dedicated jury for Innovation Award +const innovationJury = await prisma.juryGroup.create({ + data: { + competitionId: "comp-2026", + name: "Innovation Award Jury", + slug: "innovation-jury", + description: "Technology and innovation experts", + defaultMaxAssignments: 15, + defaultCapMode: "SOFT", + categoryQuotasEnabled: false, + } +}) + +// Add members (can overlap with main jury) +await prisma.juryGroupMember.createMany({ + data: [ + { juryGroupId: innovationJury.id, userId: "user-tech-1", isLead: true }, + { juryGroupId: innovationJury.id, userId: "user-tech-2" }, + { juryGroupId: innovationJury.id, userId: "jury-2-member-overlap" }, // Also on Jury 2 + ] +}) + +// Link to award +await prisma.specialAward.update({ + where: { id: awardId }, + data: { juryGroupId: innovationJury.id } +}) +``` + +### Award Jury Assignment + +#### For STAY_IN_MAIN Mode + +Award jury members evaluate the same projects as the main jury, but with award-specific criteria. + +**Assignment Creation:** +```typescript +// Main jury assignments (created by round) +Assignment { userId: "jury-2-member-1", projectId: "proj-A", roundId: "round-5", juryGroupId: "jury-2" } + +// Award jury assignments (created separately, same round) +Assignment { userId: "innovation-jury-1", projectId: "proj-A", roundId: "round-5", juryGroupId: "innovation-jury" } +``` + +**Evaluation:** +- Award jury uses `evaluationFormId` linked to award +- Evaluations stored separately (different `assignmentId`) +- Both juries can evaluate same project in same round + +#### For SEPARATE_POOL Mode + +Award has its own assignment workflow, potentially for a subset of projects. + +--- + +## Award Evaluation Flow + +### STAY_IN_MAIN Evaluation + +**Timeline:** +``` +Round 5: Jury 2 Evaluation (Main) +├─ Opens: 2026-03-01 +├─ Main Jury evaluates with standard form +├─ Innovation Award Jury evaluates with innovation form +└─ Closes: 2026-03-15 + +Award results calculated separately but announced together +``` + +**Step-by-Step:** + +1. **Setup Phase** + - Admin creates `SpecialAward { evaluationMode: "STAY_IN_MAIN", evaluationRoundId: "round-5" }` + - Admin creates award-specific `EvaluationForm` with innovation criteria + - Admin creates `JuryGroup` for Innovation Award + - Admin adds members to jury group + +2. **Eligibility Phase** + - Eligibility determined (AI/manual/round-based) + - Only eligible projects evaluated by award jury + +3. **Assignment Phase** + - When Round 5 opens, assignments created for award jury + - Each award juror assigned eligible projects + - Award assignments reference same `roundId` as main evaluation + +4. **Evaluation Phase** + - Award jurors see projects in their dashboard + - Form shows award-specific criteria + - Evaluations stored with `formId` = innovation form + +5. **Results Phase** + - Scores aggregated separately from main jury + - Winner selection (jury vote, admin decision, etc.) + - Results feed into confirmation round + +### SEPARATE_POOL Evaluation + +**Timeline:** +``` +Round 5: Jury 2 Evaluation (Main) — March 1-15 + ↓ +Round 6: Finalist Selection + ↓ +Impact Award Evaluation (Separate) — March 20 - April 5 +├─ Own voting window +├─ Own evaluation form +├─ Impact Award Jury evaluates finalists +└─ Results: April 10 +``` + +--- + +## Audience Voting for Awards + +### Voting Modes + +#### JURY_ONLY + +Only jury members vote. Standard model. + +#### AUDIENCE_ONLY + +Only audience (public) votes. No jury involvement. + +**Config:** +```typescript +type AudienceOnlyConfig = { + requireIdentification: boolean // Require email/phone (default: false) + votesPerPerson: number // Max votes per person (default: 1) + allowRanking: boolean // Ranked-choice (default: false) + maxChoices?: number // For ranked mode +} +``` + +#### COMBINED + +Jury + audience votes combined with weighted scoring. + +**Config:** +```typescript +type CombinedConfig = { + audienceWeight: number // 0.0-1.0 (e.g., 0.3 = 30% audience, 70% jury) + juryWeight: number // 0.0-1.0 (should sum to 1.0) + requireMinimumAudienceVotes: number // Min votes for validity (default: 50) + showAudienceResultsToJury: boolean // Jury sees audience results (default: false) +} +``` + +**Scoring Calculation:** +```typescript +function calculateCombinedScore( + juryScores: number[], + audienceVoteCount: number, + totalAudienceVotes: number, + config: CombinedConfig +): number { + const juryAvg = juryScores.reduce((a, b) => a + b, 0) / juryScores.length + const audiencePercent = audienceVoteCount / totalAudienceVotes + + // Normalize jury score to 0-1 (assuming 1-10 scale) + const normalizedJuryScore = juryAvg / 10 + + const finalScore = + (normalizedJuryScore * config.juryWeight) + + (audiencePercent * config.audienceWeight) + + return finalScore +} +``` + +--- + +## Admin Experience + +### Award Management Dashboard + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ MOPC 2026 — Special Awards [+ New Award] │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ Innovation Award [Edit ▼] │ │ +│ │ Mode: Stay in Main (Jury 2 Evaluation) • Status: EVALUATION │ │ +│ ├───────────────────────────────────────────────────────────────────────┤ │ +│ │ Eligible Projects: 18 / 20 finalists │ │ +│ │ Jury: Innovation Jury (5 members) │ │ +│ │ Evaluations: 72 / 90 (80% complete) │ │ +│ │ Voting Closes: March 15, 2026 │ │ +│ │ │ │ +│ │ [View Eligibility] [View Evaluations] [Select Winner] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ Community Impact Award [Edit ▼] │ │ +│ │ Mode: Separate Pool • Status: DRAFT │ │ +│ ├───────────────────────────────────────────────────────────────────────┤ │ +│ │ Eligible Projects: Not yet determined (AI pending) │ │ +│ │ Jury: Not assigned │ │ +│ │ Voting Window: Not set │ │ +│ │ │ │ +│ │ [Configure Eligibility] [Set Up Jury] [Set Timeline] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Integration with Main Flow + +### Awards Reference Main Competition Projects + +Awards don't create their own project pool — they reference existing competition projects. + +**Data Relationship:** +``` +Competition + ├── Projects (shared pool) + │ ├── Project A + │ ├── Project B + │ └── Project C + │ + ├── Main Rounds (linear flow) + │ ├── Round 1: Intake + │ ├── Round 5: Jury 2 Evaluation + │ └── Round 7: Live Finals + │ + └── Special Awards (parallel evaluation) + ├── Innovation Award + │ └── AwardEligibility { projectId: "A", eligible: true } + │ └── AwardEligibility { projectId: "B", eligible: false } + └── Impact Award + └── AwardEligibility { projectId: "A", eligible: true } + └── AwardEligibility { projectId: "C", eligible: true } +``` + +### Award Results Feed into Confirmation Round + +**Confirmation Round Integration:** + +The confirmation round (Round 8) includes: +1. Main competition winners (1st, 2nd, 3rd per category) +2. Special award winners + +**WinnerProposal Extension:** +```prisma +model WinnerProposal { + id String @id @default(cuid()) + competitionId String + category CompetitionCategory? // Null for award winners + + // Main competition or award + proposalType WinnerProposalType @default(MAIN_COMPETITION) + awardId String? // If proposalType = SPECIAL_AWARD + + status WinnerProposalStatus @default(PENDING) + rankedProjectIds String[] + + // ... rest of fields ... +} + +enum WinnerProposalType { + MAIN_COMPETITION // Main 1st/2nd/3rd place + SPECIAL_AWARD // Award winner +} +``` + +--- + +## API Changes + +### New tRPC Procedures + +```typescript +// src/server/routers/award-redesign.ts + +export const awardRedesignRouter = router({ + /** + * Create a new special award + */ + create: adminProcedure + .input(z.object({ + competitionId: z.string(), + name: z.string().min(1).max(255), + description: z.string().optional(), + eligibilityMode: z.enum(['AI_SUGGESTED', 'MANUAL', 'ALL_ELIGIBLE', 'ROUND_BASED']), + evaluationMode: z.enum(['STAY_IN_MAIN', 'SEPARATE_POOL']), + votingMode: z.enum(['JURY_ONLY', 'AUDIENCE_ONLY', 'COMBINED']), + scoringMode: z.enum(['PICK_WINNER', 'RANKED', 'SCORED']), + maxWinners: z.number().int().min(1).default(1), + })) + .mutation(async ({ ctx, input }) => { /* ... */ }), + + /** + * Run eligibility determination + */ + runEligibility: adminProcedure + .input(z.object({ awardId: z.string() })) + .mutation(async ({ ctx, input }) => { /* ... */ }), + + /** + * Cast vote (jury or audience) + */ + vote: protectedProcedure + .input(z.object({ + awardId: z.string(), + projectId: z.string(), + rank: z.number().int().min(1).optional(), + score: z.number().min(0).max(10).optional(), + })) + .mutation(async ({ ctx, input }) => { /* ... */ }), + + /** + * Select winner(s) + */ + selectWinners: adminProcedure + .input(z.object({ + awardId: z.string(), + winnerProjectIds: z.array(z.string()).min(1), + selectionMethod: z.enum(['JURY_VOTE', 'AUDIENCE_VOTE', 'COMBINED', 'ADMIN_DECISION']), + })) + .mutation(async ({ ctx, input }) => { /* ... */ }), +}) +``` + +--- + +## Service Functions + +### Award Service Enhancements + +```typescript +// src/server/services/award-service.ts + +/** + * Run round-based eligibility + */ +export async function runRoundBasedEligibility( + award: SpecialAward, + prisma = getPrisma() +) { + const config = award.eligibilityCriteria as RoundBasedConfig + + if (!config.sourceRoundId) { + throw new Error('Round-based eligibility requires sourceRoundId') + } + + // Get all projects in the specified round with the required state + const projectRoundStates = await prisma.projectRoundState.findMany({ + where: { + roundId: config.sourceRoundId, + state: config.requiredState ?? 'PASSED', + }, + select: { projectId: true } + }) + + // Create/update eligibility records + let created = 0 + let updated = 0 + + for (const prs of projectRoundStates) { + const existing = await prisma.awardEligibility.findUnique({ + where: { + awardId_projectId: { + awardId: award.id, + projectId: prs.projectId + } + } + }) + + if (existing) { + await prisma.awardEligibility.update({ + where: { id: existing.id }, + data: { eligible: true, method: 'AUTO' } + }) + updated++ + } else { + await prisma.awardEligibility.create({ + data: { + awardId: award.id, + projectId: prs.projectId, + eligible: true, + method: 'AUTO', + } + }) + created++ + } + } + + return { created, updated, total: projectRoundStates.length } +} + +/** + * Calculate combined jury + audience score + */ +export function calculateCombinedScore( + juryScores: number[], + audienceVoteCount: number, + totalAudienceVotes: number, + juryWeight: number, + audienceWeight: number +): number { + if (juryScores.length === 0) { + throw new Error('Cannot calculate combined score without jury votes') + } + + const juryAvg = juryScores.reduce((a, b) => a + b, 0) / juryScores.length + const normalizedJuryScore = juryAvg / 10 // Assume 1-10 scale + + const audiencePercent = totalAudienceVotes > 0 + ? audienceVoteCount / totalAudienceVotes + : 0 + + const finalScore = + (normalizedJuryScore * juryWeight) + + (audiencePercent * audienceWeight) + + return finalScore +} + +/** + * Create award jury assignments + */ +export async function createAwardAssignments( + awardId: string, + prisma = getPrisma() +) { + const award = await prisma.specialAward.findUniqueOrThrow({ + where: { id: awardId }, + include: { + juryGroup: { + include: { members: true } + } + } + }) + + if (!award.juryGroupId || !award.juryGroup) { + throw new Error('Award must have a jury group to create assignments') + } + + const eligibleProjects = await getEligibleProjects(awardId, prisma) + + const assignments = [] + + for (const project of eligibleProjects) { + for (const member of award.juryGroup.members) { + assignments.push({ + userId: member.userId, + projectId: project.id, + roundId: award.evaluationRoundId ?? null, + juryGroupId: award.juryGroupId, + method: 'MANUAL' as const, + }) + } + } + + await prisma.assignment.createMany({ + data: assignments, + skipDuplicates: true, + }) + + return { created: assignments.length } +} +``` + +--- + +## Edge Cases + +| Scenario | Handling | +|----------|----------| +| **Project eligible for multiple awards** | Allowed — project can win multiple awards | +| **Jury member on both main and award juries** | Allowed — separate assignments, separate evaluations | +| **Award voting ends before main results** | Award winner held until main results finalized, announced together | +| **Award eligibility changes mid-voting** | Admin override can remove eligibility; active votes invalidated | +| **Audience vote spam/fraud** | IP rate limiting, device fingerprinting, email verification, admin review | +| **Tie in award voting** | Admin decision or re-vote (configurable) | +| **Award jury not complete evaluations** | Admin can close voting with partial data or extend deadline | +| **Project withdrawn after eligible** | Eligibility auto-removed; votes invalidated | +| **Award criteria change after eligibility** | Re-run eligibility or grandfather existing eligible projects | +| **No eligible projects for award** | Award status set to DRAFT/ARCHIVED; no voting | + +--- + +## Integration Points + +### With Evaluation System +- Awards use `EvaluationForm` for criteria +- Award evaluations stored in `Evaluation` table with `formId` linkage +- Assignment system handles both main and award assignments + +### With Jury Groups +- Awards can link to existing `JuryGroup` or have dedicated groups +- Jury members can overlap between main and award juries +- Caps and quotas honored for award assignments + +### With Confirmation Round +- Award winners included in `WinnerProposal` system +- Confirmation flow handles both main and award winners +- Approval workflow requires sign-off on all winners + +### With Notification System +- Eligibility notifications sent to eligible teams +- Voting reminders sent to award jurors +- Winner announcements coordinated with main results + +--- + +## Summary + +The redesigned Special Awards system provides: + +1. **Flexibility**: Two modes (STAY_IN_MAIN, SEPARATE_POOL) cover all use cases +2. **Integration**: Deep integration with competition rounds, juries, and results +3. **Autonomy**: Awards can run independently or piggyback on main flow +4. **Transparency**: AI eligibility with admin override, full audit trail +5. **Engagement**: Audience voting support with anti-fraud measures +6. **Scalability**: Support for multiple awards, multiple winners, complex scoring + +This architecture eliminates the Track dependency, integrates awards as standalone entities, and provides a robust, flexible system for recognizing excellence across multiple dimensions while maintaining the integrity of the main competition flow. diff --git a/docs/claude-architecture-redesign/12-jury-groups.md b/docs/claude-architecture-redesign/12-jury-groups.md new file mode 100644 index 0000000..7bc2b27 --- /dev/null +++ b/docs/claude-architecture-redesign/12-jury-groups.md @@ -0,0 +1,960 @@ +# Jury Groups — Multi-Jury Architecture + +## Overview + +The **JuryGroup** model is the backbone of the redesigned jury system. Instead of implicit jury membership derived from per-stage assignments, juries are now **first-class named entities** — "Jury 1", "Jury 2", "Jury 3", "Innovation Award Jury" — with explicit membership, configurable assignment caps, and per-juror overrides. + +### Why This Matters + +| Before (Current) | After (Redesigned) | +|---|---| +| Juries are implicit — "Jury 1" exists only in admin's head | JuryGroup is a named model with `id`, `name`, `description` | +| Assignment caps are per-stage config | Caps are per-juror on JuryGroupMember (with group defaults) | +| No concept of "which jury is this juror on" | JuryGroupMember links User to JuryGroup explicitly | +| Same juror can't be on multiple juries (no grouping) | A User can belong to multiple JuryGroups | +| Category quotas don't exist | Per-juror STARTUP/CONCEPT ratio preferences | +| No juror onboarding preferences | JuryGroupMember stores language, expertise, preferences | + +### Jury Groups in the 8-Step Flow + +``` +Round 1: INTAKE — no jury +Round 2: FILTERING — no jury (AI-powered) +Round 3: EVALUATION — ► Jury 1 (semi-finalist selection) +Round 4: SUBMISSION — no jury +Round 5: EVALUATION — ► Jury 2 (finalist selection) +Round 6: MENTORING — no jury +Round 7: LIVE_FINAL — ► Jury 3 (live finals scoring) +Round 8: CONFIRMATION — ► Jury 3 (winner confirmation) + +Special Awards: + Innovation Award — ► Innovation Jury (may overlap with Jury 2) + Impact Award — ► Impact Jury (dedicated members) +``` + +--- + +## Data Model + +### JuryGroup + +```prisma +model JuryGroup { + id String @id @default(cuid()) + competitionId String + name String // "Jury 1", "Jury 2", "Jury 3", "Innovation Award Jury" + description String? // "Semi-finalist evaluation jury — reviews 60+ applications" + isActive Boolean @default(true) + + // Default assignment configuration for this jury + defaultMaxAssignments Int @default(20) + defaultCapMode CapMode @default(SOFT) + softCapBuffer Int @default(2) // Extra assignments above cap + + // Default category quotas (per juror) + defaultCategoryQuotas Json? @db.JsonB + // Shape: { "STARTUP": { min: 5, max: 12 }, "BUSINESS_CONCEPT": { min: 5, max: 12 } } + + // Onboarding + onboardingFormId String? // Link to onboarding form (expertise, preferences) + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + competition Competition @relation(...) + members JuryGroupMember[] + rounds Round[] // Rounds this jury is assigned to + assignments Assignment[] // Assignments made through this jury group +} +``` + +### JuryGroupMember + +```prisma +model JuryGroupMember { + id String @id @default(cuid()) + juryGroupId String + userId String + role String @default("MEMBER") // "MEMBER" | "CHAIR" | "OBSERVER" + + // Per-juror overrides (null = use group defaults) + maxAssignmentsOverride Int? + capModeOverride CapMode? + categoryQuotasOverride Json? @db.JsonB + + // Juror preferences (set during onboarding) + preferredStartupRatio Float? // 0.0–1.0 (e.g., 0.6 = 60% startups) + expertiseTags String[] // ["ocean-tech", "marine-biology", "finance"] + languagePreferences String[] // ["en", "fr"] + notes String? // Admin notes about this juror + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + // Relations + juryGroup JuryGroup @relation(...) + user User @relation(...) + + @@unique([juryGroupId, userId]) + @@index([juryGroupId]) + @@index([userId]) +} +``` + +### CapMode Enum + +```prisma +enum CapMode { + HARD // Absolute maximum — algorithm cannot exceed under any circumstance + SOFT // Target maximum — can exceed by softCapBuffer for load balancing + NONE // No cap — unlimited assignments (use with caution) +} +``` + +### Cap Behavior + +| Mode | Max | Buffer | Effective Limit | Behavior | +|------|-----|--------|-----------------|----------| +| HARD | 20 | — | 20 | Algorithm stops at exactly 20. No exceptions. | +| SOFT | 20 | 2 | 22 | Algorithm targets 20 but can go to 22 if needed for balanced distribution | +| NONE | — | — | ∞ | No limit. Juror can be assigned any number of projects | + +```typescript +function getEffectiveCap(member: JuryGroupMember, group: JuryGroup): number | null { + const capMode = member.capModeOverride ?? group.defaultCapMode; + const maxAssignments = member.maxAssignmentsOverride ?? group.defaultMaxAssignments; + + switch (capMode) { + case 'HARD': + return maxAssignments; + case 'SOFT': + return maxAssignments + group.softCapBuffer; + case 'NONE': + return null; // no limit + } +} + +function canAssignMore( + member: JuryGroupMember, + group: JuryGroup, + currentCount: number +): { allowed: boolean; reason?: string } { + const cap = getEffectiveCap(member, group); + + if (cap === null) return { allowed: true }; + + if (currentCount >= cap) { + return { + allowed: false, + reason: `Juror has reached ${capMode === 'HARD' ? 'hard' : 'soft'} cap of ${cap} assignments`, + }; + } + + return { allowed: true }; +} +``` + +--- + +## Category Quotas + +### How Quotas Work + +Each jury group (and optionally each member) can define minimum and maximum assignments per competition category. This ensures balanced coverage: + +```typescript +type CategoryQuotas = { + STARTUP: { min: number; max: number }; + BUSINESS_CONCEPT: { min: number; max: number }; +}; + +// Example: group default +const defaultQuotas: CategoryQuotas = { + STARTUP: { min: 5, max: 12 }, + BUSINESS_CONCEPT: { min: 5, max: 12 }, +}; +``` + +### Quota Resolution + +Per-juror overrides take precedence over group defaults: + +```typescript +function getEffectiveQuotas( + member: JuryGroupMember, + group: JuryGroup +): CategoryQuotas | null { + if (member.categoryQuotasOverride) { + return member.categoryQuotasOverride as CategoryQuotas; + } + if (group.defaultCategoryQuotas) { + return group.defaultCategoryQuotas as CategoryQuotas; + } + return null; // no quotas — assign freely +} +``` + +### Quota Enforcement During Assignment + +```typescript +function checkCategoryQuota( + member: JuryGroupMember, + group: JuryGroup, + category: CompetitionCategory, + currentCategoryCount: number +): { allowed: boolean; warning?: string } { + const quotas = getEffectiveQuotas(member, group); + if (!quotas) return { allowed: true }; + + const categoryQuota = quotas[category]; + if (!categoryQuota) return { allowed: true }; + + if (currentCategoryCount >= categoryQuota.max) { + return { + allowed: false, + warning: `Juror has reached max ${categoryQuota.max} for ${category}`, + }; + } + + return { allowed: true }; +} + +function checkMinimumQuotasMet( + member: JuryGroupMember, + group: JuryGroup, + categoryCounts: Record +): { met: boolean; deficits: string[] } { + const quotas = getEffectiveQuotas(member, group); + if (!quotas) return { met: true, deficits: [] }; + + const deficits: string[] = []; + for (const [category, quota] of Object.entries(quotas)) { + const count = categoryCounts[category as CompetitionCategory] ?? 0; + if (count < quota.min) { + deficits.push(`${category}: ${count}/${quota.min} minimum`); + } + } + + return { met: deficits.length === 0, deficits }; +} +``` + +--- + +## Preferred Startup Ratio + +Each juror can express a preference for what percentage of their assignments should be Startups vs Concepts. + +```typescript +// On JuryGroupMember: +preferredStartupRatio: Float? // 0.0 to 1.0 + +// Usage in assignment algorithm: +function calculateRatioAlignmentScore( + member: JuryGroupMember, + candidateCategory: CompetitionCategory, + currentStartupCount: number, + currentConceptCount: number +): number { + const preference = member.preferredStartupRatio; + if (preference === null || preference === undefined) return 0; // no preference + + const totalAfterAssignment = currentStartupCount + currentConceptCount + 1; + const startupCountAfter = candidateCategory === 'STARTUP' + ? currentStartupCount + 1 + : currentStartupCount; + const ratioAfter = startupCountAfter / totalAfterAssignment; + + // Score: how close does adding this assignment bring the ratio to preference? + const deviation = Math.abs(ratioAfter - preference); + // Scale: 0 deviation = 10pts, 0.5 deviation = 0pts + return Math.max(0, 10 * (1 - deviation * 2)); +} +``` + +This score feeds into the assignment algorithm alongside tag overlap, workload balance, and geo-diversity. + +--- + +## Juror Roles + +Each JuryGroupMember has a `role` field: + +| Role | Capabilities | Description | +|------|-------------|-------------| +| `MEMBER` | Evaluate assigned projects, vote in live finals, confirm winners | Standard jury member | +| `CHAIR` | All MEMBER capabilities + view all evaluations, moderate discussions, suggest assignments | Jury chairperson — has broader visibility | +| `OBSERVER` | View evaluations (read-only), no scoring or voting | Observes the jury process without participating | + +### Role-Based Visibility + +```typescript +function getJurorVisibility( + role: string, + ownAssignments: Assignment[] +): VisibilityScope { + switch (role) { + case 'CHAIR': + return { + canSeeAllEvaluations: true, + canSeeAllAssignments: true, + canModerateDiscussions: true, + canSuggestReassignments: true, + }; + case 'MEMBER': + return { + canSeeAllEvaluations: false, // only their own + canSeeAllAssignments: false, + canModerateDiscussions: false, + canSuggestReassignments: false, + }; + case 'OBSERVER': + return { + canSeeAllEvaluations: true, // read-only + canSeeAllAssignments: true, + canModerateDiscussions: false, + canSuggestReassignments: false, + }; + } +} +``` + +--- + +## Multi-Jury Membership + +A single user can be on multiple jury groups. This is common for: +- A juror on Jury 2 (finalist selection) AND Innovation Award Jury +- A senior juror on Jury 1 AND Jury 3 (semi-finalist + live finals) + +### Overlap Handling + +```typescript +// Get all jury groups for a user in a competition +async function getUserJuryGroups( + userId: string, + competitionId: string +): Promise { + return prisma.juryGroupMember.findMany({ + where: { + userId, + juryGroup: { competitionId }, + }, + include: { juryGroup: true }, + }); +} + +// Check if user is on a specific jury +async function isUserOnJury( + userId: string, + juryGroupId: string +): Promise { + const member = await prisma.juryGroupMember.findUnique({ + where: { juryGroupId_userId: { juryGroupId, userId } }, + }); + return member !== null; +} +``` + +### Cross-Jury COI Propagation + +When a juror declares a Conflict of Interest for a project in one jury group, it should propagate to all their jury memberships: + +```typescript +async function propagateCOI( + userId: string, + projectId: string, + competitionId: string, + reason: string +): Promise { + // Find all jury groups this user is on + const memberships = await getUserJuryGroups(userId, competitionId); + + for (const membership of memberships) { + // Find assignments for this user+project in each jury group + const assignments = await prisma.assignment.findMany({ + where: { + userId, + projectId, + juryGroupId: membership.juryGroupId, + }, + }); + + for (const assignment of assignments) { + // Check if COI already declared + const existing = await prisma.conflictOfInterest.findUnique({ + where: { assignmentId: assignment.id }, + }); + + if (!existing) { + await prisma.conflictOfInterest.create({ + data: { + assignmentId: assignment.id, + reason: `Auto-propagated from ${membership.juryGroup.name}: ${reason}`, + declared: true, + }, + }); + } + } + } +} +``` + +--- + +## Jury Group Lifecycle + +### States + +``` +DRAFT → ACTIVE → LOCKED → ARCHIVED +``` + +| State | Description | Operations Allowed | +|-------|-------------|-------------------| +| DRAFT | Being configured. Members can be added/removed freely | Add/remove members, edit settings | +| ACTIVE | Jury is in use. Assignments are being made or evaluations in progress | Add members (with warning), edit per-juror settings | +| LOCKED | Evaluation or voting is in progress. No membership changes | Edit per-juror notes only | +| ARCHIVED | Competition complete. Preserved for records | Read-only | + +### State Transitions + +```typescript +// Jury group activates when its linked round starts +async function activateJuryGroup(juryGroupId: string): Promise { + await prisma.juryGroup.update({ + where: { id: juryGroupId }, + data: { isActive: true }, + }); +} + +// Jury group locks when evaluation/voting begins +async function lockJuryGroup(juryGroupId: string): Promise { + // Prevent membership changes during active evaluation + await prisma.juryGroup.update({ + where: { id: juryGroupId }, + data: { isActive: false }, // Using isActive as soft-lock; could add separate locked field + }); +} +``` + +--- + +## Onboarding + +### Juror Onboarding Flow + +When a juror is added to a JuryGroup, they go through an onboarding process: + +1. **Invitation** — Admin adds juror to group → juror receives email invitation +2. **Profile Setup** — Juror fills out expertise tags, language preferences, category preference +3. **COI Pre-declaration** — Juror reviews project list and declares any pre-existing conflicts +4. **Confirmation** — Juror confirms they understand their role and responsibilities + +### Onboarding UI + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Welcome to Jury 1 — Semi-finalist Evaluation │ +│ │ +│ You've been selected to evaluate projects for the │ +│ Monaco Ocean Protection Challenge 2026. │ +│ │ +│ Step 1 of 3: Your Expertise │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ Select your areas of expertise (used for matching): │ +│ ☑ Marine Biology ☑ Ocean Technology │ +│ ☐ Renewable Energy ☑ Environmental Policy │ +│ ☐ Finance/Investment ☐ Social Impact │ +│ ☐ Data Science ☐ Education │ +│ │ +│ Preferred languages: │ +│ ☑ English ☑ French ☐ Other: [________] │ +│ │ +│ Category preference (what % Startups vs Concepts): │ +│ Startups [====●=========] Concepts │ +│ 60% / 40% │ +│ │ +│ [ Back ] [ Next Step → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Step 2 of 3: Conflict of Interest Declaration │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ Please review the project list and declare any conflicts │ +│ of interest. A COI exists if you have a personal, │ +│ financial, or professional relationship with a project team. │ +│ │ +│ ┌──────────────────────────────────────┬──────────────────┐ │ +│ │ Project │ COI? │ │ +│ ├──────────────────────────────────────┼──────────────────┤ │ +│ │ OceanClean AI │ ○ None │ │ +│ │ DeepReef Monitoring │ ● COI Declared │ │ +│ │ CoralGuard │ ○ None │ │ +│ │ WaveEnergy Solutions │ ○ None │ │ +│ │ ... (60 more projects) │ │ │ +│ └──────────────────────────────────────┴──────────────────┘ │ +│ │ +│ COI Details for "DeepReef Monitoring": │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Former colleague of team lead. Worked together 2022-23. │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ [ Back ] [ Next Step → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Step 3 of 3: Confirmation │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ By confirming, you agree to: │ +│ ☑ Evaluate assigned projects fairly and impartially │ +│ ☑ Complete evaluations by the deadline │ +│ ☑ Maintain confidentiality of all submissions │ +│ ☑ Report any additional conflicts of interest │ +│ │ +│ Your assignments: up to 20 projects │ +│ Evaluation deadline: March 15, 2026 │ +│ Category target: ~12 Startups / ~8 Concepts │ +│ │ +│ [ Back ] [ ✓ Confirm & Start ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Admin Jury Management + +### Jury Group Dashboard + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Jury Groups — MOPC 2026 │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Jury 1 — Semi-finalist Selection [Edit]│ │ +│ │ Members: 8 | Linked to: Round 3 | Status: ACTIVE │ │ +│ │ Cap: 20 (SOFT +2) | Avg load: 15.3 projects │ │ +│ │ ████████████████░░░░ 76% assignments complete │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Jury 2 — Finalist Selection [Edit]│ │ +│ │ Members: 6 | Linked to: Round 5 | Status: DRAFT │ │ +│ │ Cap: 15 (HARD) | Not yet assigned │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Jury 3 — Live Finals [Edit]│ │ +│ │ Members: 5 | Linked to: Round 7, Round 8 | Status: DRAFT │ │ +│ │ All finalists assigned to all jurors │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Innovation Award Jury [Edit]│ │ +│ │ Members: 4 | Linked to: Innovation Award | Status: DRAFT │ │ +│ │ Shares 2 members with Jury 2 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ [ + Create Jury Group ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Member Management + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Jury 1 — Member Management │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Group Defaults: Max 20 | SOFT cap (+2) | Quotas: S:5-12 C:5-12│ +│ │ +│ ┌──────┬──────────────┬──────┬─────┬──────┬──────┬──────────┐ │ +│ │ Role │ Name │ Load │ Cap │ S/C │ Pref │ Actions │ │ +│ ├──────┼──────────────┼──────┼─────┼──────┼──────┼──────────┤ │ +│ │ CHAIR│ Dr. Martin │ 18 │ 20S │ 11/7 │ 60% │ [Edit] │ │ +│ │ MEMBER│ Prof. Dubois│ 15 │ 20S │ 9/6 │ 50% │ [Edit] │ │ +│ │ MEMBER│ Ms. Chen │ 20 │ 20H │ 12/8 │ 60% │ [Edit] │ │ +│ │ MEMBER│ Dr. Patel │ 12 │ 15* │ 7/5 │ — │ [Edit] │ │ +│ │ MEMBER│ Mr. Silva │ 16 │ 20S │ 10/6 │ 70% │ [Edit] │ │ +│ │ MEMBER│ Dr. Yamada │ 19 │ 20S │ 11/8 │ 55% │ [Edit] │ │ +│ │ MEMBER│ Ms. Hansen │ 14 │ 20S │ 8/6 │ — │ [Edit] │ │ +│ │ OBS │ Mr. Berger │ — │ — │ — │ — │ [Edit] │ │ +│ └──────┴──────────────┴──────┴─────┴──────┴──────┴──────────┘ │ +│ │ +│ * = per-juror override S = SOFT H = HARD │ +│ S/C = Startup/Concept count Pref = preferred startup ratio │ +│ │ +│ [ + Add Member ] [ Import from CSV ] [ Run AI Assignment ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Per-Juror Override Sheet + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Edit Juror Settings — Dr. Patel │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Role: [MEMBER ▼] │ +│ │ +│ ── Assignment Overrides ────────────────────────────────────── │ +│ (Leave blank to use group defaults) │ +│ │ +│ Max assignments: [15 ] (group default: 20) │ +│ Cap mode: [HARD ▼] (group default: SOFT) │ +│ │ +│ Category quotas: │ +│ Startups: min [3 ] max [10] (group: 5-12) │ +│ Concepts: min [3 ] max [8 ] (group: 5-12) │ +│ │ +│ ── Preferences ─────────────────────────────────────────────── │ +│ │ +│ Preferred startup ratio: [ ] % (blank = no preference) │ +│ Expertise tags: [marine-biology, policy, ...] │ +│ Language: [English, French] │ +│ │ +│ ── Notes ───────────────────────────────────────────────────── │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Dr. Patel requested reduced load due to conference │ │ +│ │ schedule in March. Hard cap at 15. │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ [ Cancel ] [ Save Changes ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Integration with Assignment Algorithm + +The assignment algorithm (see `06-round-evaluation.md`) uses JuryGroup data at every step: + +### Algorithm Input + +```typescript +type AssignmentInput = { + roundId: string; + juryGroupId: string; + projects: Project[]; + config: { + requiredReviewsPerProject: number; + }; +}; +``` + +### Algorithm Steps Using JuryGroup + +1. **Load jury members** — Fetch all active JuryGroupMembers with role != OBSERVER +2. **Resolve effective limits** — For each member, compute effective cap and quotas +3. **Filter by COI** — Exclude members with declared COI for each project +4. **Score candidates** — For each (project, juror) pair, compute: + - Tag overlap score (expertise alignment) + - Workload balance score (prefer jurors with fewer assignments) + - Category ratio alignment score (prefer assignment that brings ratio closer to preference) + - Geo-diversity score +5. **Apply caps** — Skip jurors who have reached their effective cap +6. **Apply quotas** — Skip jurors who have reached category max +7. **Rank and assign** — Greedily assign top-scoring pairs +8. **Validate minimums** — Check if category minimums are met; warn admin if not + +### Assignment Preview + +```typescript +type AssignmentPreview = { + assignments: { + userId: string; + projectId: string; + score: number; + breakdown: { + tagOverlap: number; + workloadBalance: number; + ratioAlignment: number; + geoDiversity: number; + }; + }[]; + + warnings: { + type: 'CAP_EXCEEDED' | 'QUOTA_UNMET' | 'COI_SKIP' | 'UNASSIGNED_PROJECT'; + message: string; + userId?: string; + projectId?: string; + }[]; + + stats: { + totalAssignments: number; + avgLoadPerJuror: number; + minLoad: number; + maxLoad: number; + unassignedProjects: number; + categoryDistribution: Record; + }; +}; +``` + +--- + +## API Procedures + +### New tRPC Router: jury-group.ts + +```typescript +export const juryGroupRouter = router({ + // ── CRUD ─────────────────────────────────────────────── + + /** Create a new jury group */ + create: adminProcedure + .input(z.object({ + competitionId: z.string(), + name: z.string().min(1).max(100), + description: z.string().optional(), + defaultMaxAssignments: z.number().int().min(1).default(20), + defaultCapMode: z.enum(['HARD', 'SOFT', 'NONE']).default('SOFT'), + softCapBuffer: z.number().int().min(0).default(2), + defaultCategoryQuotas: z.record(z.object({ + min: z.number().int().min(0), + max: z.number().int().min(0), + })).optional(), + })) + .mutation(async ({ input }) => { ... }), + + /** Update jury group settings */ + update: adminProcedure + .input(z.object({ + juryGroupId: z.string(), + name: z.string().min(1).max(100).optional(), + description: z.string().optional(), + defaultMaxAssignments: z.number().int().min(1).optional(), + defaultCapMode: z.enum(['HARD', 'SOFT', 'NONE']).optional(), + softCapBuffer: z.number().int().min(0).optional(), + defaultCategoryQuotas: z.record(z.object({ + min: z.number().int().min(0), + max: z.number().int().min(0), + })).nullable().optional(), + })) + .mutation(async ({ input }) => { ... }), + + /** Delete jury group (only if DRAFT and no assignments) */ + delete: adminProcedure + .input(z.object({ juryGroupId: z.string() })) + .mutation(async ({ input }) => { ... }), + + /** Get jury group with members */ + getById: protectedProcedure + .input(z.object({ juryGroupId: z.string() })) + .query(async ({ input }) => { ... }), + + /** List all jury groups for a competition */ + listByCompetition: protectedProcedure + .input(z.object({ competitionId: z.string() })) + .query(async ({ input }) => { ... }), + + // ── Members ──────────────────────────────────────────── + + /** Add a member to the jury group */ + addMember: adminProcedure + .input(z.object({ + juryGroupId: z.string(), + userId: z.string(), + role: z.enum(['MEMBER', 'CHAIR', 'OBSERVER']).default('MEMBER'), + })) + .mutation(async ({ input }) => { ... }), + + /** Remove a member from the jury group */ + removeMember: adminProcedure + .input(z.object({ + juryGroupId: z.string(), + userId: z.string(), + })) + .mutation(async ({ input }) => { ... }), + + /** Batch add members (from CSV or user selection) */ + addMembersBatch: adminProcedure + .input(z.object({ + juryGroupId: z.string(), + members: z.array(z.object({ + userId: z.string(), + role: z.enum(['MEMBER', 'CHAIR', 'OBSERVER']).default('MEMBER'), + })), + })) + .mutation(async ({ input }) => { ... }), + + /** Update member settings (overrides, preferences) */ + updateMember: adminProcedure + .input(z.object({ + juryGroupId: z.string(), + userId: z.string(), + role: z.enum(['MEMBER', 'CHAIR', 'OBSERVER']).optional(), + maxAssignmentsOverride: z.number().int().min(1).nullable().optional(), + capModeOverride: z.enum(['HARD', 'SOFT', 'NONE']).nullable().optional(), + categoryQuotasOverride: z.record(z.object({ + min: z.number().int().min(0), + max: z.number().int().min(0), + })).nullable().optional(), + preferredStartupRatio: z.number().min(0).max(1).nullable().optional(), + expertiseTags: z.array(z.string()).optional(), + languagePreferences: z.array(z.string()).optional(), + notes: z.string().nullable().optional(), + })) + .mutation(async ({ input }) => { ... }), + + // ── Queries ──────────────────────────────────────────── + + /** Get all jury groups a user belongs to */ + getMyJuryGroups: juryProcedure + .query(async ({ ctx }) => { ... }), + + /** Get assignment stats for a jury group */ + getAssignmentStats: adminProcedure + .input(z.object({ juryGroupId: z.string() })) + .query(async ({ input }) => { ... }), + + /** Check if a user can be added (no duplicate, role compatible) */ + checkMemberEligibility: adminProcedure + .input(z.object({ + juryGroupId: z.string(), + userId: z.string(), + })) + .query(async ({ input }) => { ... }), + + // ── Onboarding ───────────────────────────────────────── + + /** Get onboarding status for a juror */ + getOnboardingStatus: juryProcedure + .input(z.object({ juryGroupId: z.string() })) + .query(async ({ ctx, input }) => { ... }), + + /** Submit onboarding form (preferences, COI declarations) */ + submitOnboarding: juryProcedure + .input(z.object({ + juryGroupId: z.string(), + expertiseTags: z.array(z.string()), + languagePreferences: z.array(z.string()), + preferredStartupRatio: z.number().min(0).max(1).optional(), + coiDeclarations: z.array(z.object({ + projectId: z.string(), + reason: z.string(), + })), + })) + .mutation(async ({ ctx, input }) => { ... }), +}); +``` + +--- + +## Service Functions + +```typescript +// src/server/services/jury-group.ts + +/** Create a jury group with defaults */ +export async function createJuryGroup( + competitionId: string, + name: string, + config?: Partial +): Promise; + +/** Get effective limits for a member (resolved overrides) */ +export async function getEffectiveLimits( + member: JuryGroupMember, + group: JuryGroup +): Promise<{ maxAssignments: number | null; capMode: CapMode; quotas: CategoryQuotas | null }>; + +/** Check if a juror can receive more assignments */ +export async function canAssignMore( + userId: string, + juryGroupId: string, + category?: CompetitionCategory +): Promise<{ allowed: boolean; reason?: string }>; + +/** Get assignment statistics for the whole group */ +export async function getGroupAssignmentStats( + juryGroupId: string +): Promise; + +/** Propagate COI across all jury groups for a user */ +export async function propagateCOI( + userId: string, + projectId: string, + competitionId: string, + reason: string +): Promise; + +/** Get all active members (excluding observers) for assignment */ +export async function getAssignableMembers( + juryGroupId: string +): Promise; + +/** Validate group readiness (enough members, all onboarded, etc.) */ +export async function validateGroupReadiness( + juryGroupId: string +): Promise<{ ready: boolean; issues: string[] }>; +``` + +--- + +## Edge Cases + +| Scenario | Handling | +|----------|----------| +| **Juror added to group during active evaluation** | Allowed with admin warning. New juror gets no existing assignments (must run assignment again) | +| **Juror removed from group during active evaluation** | Blocked if juror has pending evaluations. Must reassign first | +| **All jurors at cap but projects remain unassigned** | Warning shown to admin. Suggest increasing caps or adding jurors | +| **Category quota min not met for any juror** | Warning shown in assignment preview. Admin can proceed or adjust | +| **Juror on 3+ jury groups** | Supported. Each membership independent. Cross-jury COI propagation ensures consistency | +| **Jury Chair also has assignments** | Allowed. Chair is a regular evaluator with extra visibility | +| **Observer tries to submit evaluation** | Blocked at procedure level (OBSERVER role excluded from evaluation mutations) | +| **Admin deletes jury group with active assignments** | Blocked. Must complete or reassign all assignments first | +| **Juror preference ratio impossible** | (e.g., 90% startups but only 20% projects are startups) — Warn in onboarding, treat as best-effort | +| **Same user added twice to same group** | Blocked by unique constraint on [juryGroupId, userId] | + +--- + +## Integration Points + +### Inbound + +| Source | Data | Purpose | +|--------|------|---------| +| Competition setup wizard | Group config | Create jury groups during competition setup | +| User management | User records | Add jurors as members | +| COI declarations | Conflict records | Filter assignments, propagate across groups | + +### Outbound + +| Target | Data | Purpose | +|--------|------|---------| +| Assignment algorithm | Members, caps, quotas | Generate assignments | +| Evaluation rounds | Jury membership | Determine who evaluates what | +| Live finals | Jury 3 members | Live voting access | +| Confirmation round | Jury members | Who must approve winner proposal | +| Special awards | Award jury members | Award evaluation access | +| Notifications | Member list | Send round-specific emails to jury | + +### JuryGroup → Round Linkage + +Each evaluation or live-final round links to exactly one JuryGroup: + +```prisma +model Round { + // ... + juryGroupId String? + juryGroup JuryGroup? @relation(...) +} +``` + +This means: +- Round 3 (EVALUATION) → Jury 1 +- Round 5 (EVALUATION) → Jury 2 +- Round 7 (LIVE_FINAL) → Jury 3 +- Round 8 (CONFIRMATION) → Jury 3 (same group, different round) + +A jury group can be linked to multiple rounds (e.g., Jury 3 handles both live finals and confirmation). diff --git a/docs/claude-architecture-redesign/13-notifications-deadlines.md b/docs/claude-architecture-redesign/13-notifications-deadlines.md new file mode 100644 index 0000000..28763a9 --- /dev/null +++ b/docs/claude-architecture-redesign/13-notifications-deadlines.md @@ -0,0 +1,2898 @@ +# Notifications & Deadlines + +## Overview + +The Notifications & Deadlines system is a cross-cutting concern that supports every round type in the MOPC platform. It provides: + +1. **Event-driven notifications** — In-app and email notifications triggered by pipeline events +2. **Deadline management** — Configurable deadline policies with grace periods +3. **Reminder scheduling** — Automated reminders at configurable intervals before deadlines +4. **Countdown timers** — Real-time visual countdowns for participants +5. **Admin controls** — Competition-wide and per-round notification configuration +6. **Multi-channel delivery** — Email, in-app, and future webhook integrations + +This system ensures that all participants (jury, applicants, mentors, admins) are informed about critical events and approaching deadlines across all round types. + +--- + +## Current System Analysis + +### How Notifications Work Today + +The current notification system (Phase 6 — Pipeline/Track/Stage architecture) has these components: + +#### 1. Event-Driven Notifications (stage-notifications.ts) + +**Core function:** +```typescript +export async function emitStageEvent( + eventType: string, // e.g., "stage.transitioned" + entityType: string, // e.g., "ProjectStageState" + entityId: string, // Entity ID + actorId: string, // User who triggered the event + details: StageEventDetails, + prisma: PrismaClient +): Promise +``` + +**Process:** +1. Creates `DecisionAuditLog` entry (immutable event record) +2. Checks `NotificationPolicy` for the event type +3. Resolves recipients based on event type (admins, jury, etc.) +4. Creates `InAppNotification` records +5. Optionally sends emails via `sendStyledNotificationEmail()` +6. Never throws — all errors caught and logged + +**Current event types:** +```typescript +const EVENT_TYPES = { + STAGE_TRANSITIONED: 'stage.transitioned', + FILTERING_COMPLETED: 'filtering.completed', + ASSIGNMENT_GENERATED: 'assignment.generated', + CURSOR_UPDATED: 'live.cursor_updated', + DECISION_OVERRIDDEN: 'decision.overridden', +} +``` + +**Notification flow:** +``` +Pipeline Event + ↓ +stage-notifications.emitStageEvent() + ↓ +1. DecisionAuditLog.create() +2. NotificationPolicy.findUnique(eventType) +3. resolveRecipients() → [NotificationTarget[]] +4. InAppNotification.createMany() +5. sendStyledNotificationEmail() (if channel = EMAIL or BOTH) +``` + +#### 2. Deadline Reminders (evaluation-reminders.ts) + +**Core function:** +```typescript +export async function processEvaluationReminders( + stageId?: string +): Promise +``` + +**Process:** +1. Finds active stages with `windowCloseAt` in the future +2. Calculates `msUntilDeadline` for each stage +3. Checks which reminder types apply (3_DAYS, 24H, 1H) +4. Finds jurors with incomplete assignments +5. Checks `ReminderLog` to avoid duplicates +6. Sends email via `sendStyledNotificationEmail()` +7. Creates `ReminderLog` entry + +**Reminder thresholds:** +```typescript +const REMINDER_TYPES = [ + { type: '3_DAYS', thresholdMs: 3 * 24 * 60 * 60 * 1000 }, + { type: '24H', thresholdMs: 24 * 60 * 60 * 1000 }, + { type: '1H', thresholdMs: 60 * 60 * 1000 }, +] +``` + +**Cron integration:** +``` +External cron job (every 15 min) + ↓ +GET /api/cron/reminders + ↓ +Header: x-cron-secret = CRON_SECRET + ↓ +processEvaluationReminders() + ↓ +Returns: { ok: true, sent: number, errors: number } +``` + +#### 3. Grace Periods (GracePeriod model + gracePeriod router) + +**Model:** +```prisma +model GracePeriod { + id String @id @default(cuid()) + stageId String + userId String + projectId String? // Optional: specific project or all in stage + extendedUntil DateTime + reason String? @db.Text + grantedById String + createdAt DateTime @default(now()) +} +``` + +**Admin operations:** +- `gracePeriod.grant({ stageId, userId, extendedUntil, reason })` — Grant to single user +- `gracePeriod.bulkGrant({ stageId, userIds[], extendedUntil })` — Bulk grant +- `gracePeriod.update({ id, extendedUntil, reason })` — Modify existing +- `gracePeriod.revoke({ id })` — Delete grace period +- `gracePeriod.listByStage({ stageId })` — View all for stage +- `gracePeriod.listActiveByStage({ stageId })` — View active (extendedUntil >= now) + +**Usage in code:** +Grace periods are checked during submission and evaluation deadline enforcement: +```typescript +// Check if user has active grace period +const gracePeriod = await prisma.gracePeriod.findFirst({ + where: { + stageId, + userId, + extendedUntil: { gte: new Date() }, + }, +}) + +const effectiveDeadline = gracePeriod?.extendedUntil ?? stage.windowCloseAt +``` + +#### 4. Countdown Timer Component (countdown-timer.tsx) + +**Client-side countdown:** +```tsx + +``` + +**Features:** +- Real-time countdown (updates every 1 second) +- Color-coded urgency: + - `expired`: Gray (deadline passed) + - `critical`: Red (< 1 hour remaining) + - `warning`: Amber (< 24 hours remaining) + - `normal`: Green (> 24 hours remaining) +- Adaptive display: + - < 1 hour: "15m 30s" + - < 24 hours: "5h 15m 30s" + - > 24 hours: "3d 5h 15m" +- Icons: Clock (normal/warning) or AlertTriangle (critical) + +#### 5. In-App Notification Center + +**Model:** +```prisma +model InAppNotification { + id String @id @default(cuid()) + userId String + type String // Event type + priority String @default("normal") // low, normal, high, urgent + icon String? // lucide icon name + title String + message String @db.Text + linkUrl String? // Where to navigate when clicked + linkLabel String? // CTA text + metadata Json? @db.JsonB + groupKey String? // For batching similar notifications + isRead Boolean @default(false) + readAt DateTime? + expiresAt DateTime? // Auto-dismiss after date + createdAt DateTime @default(now()) +} +``` + +**Notification bell UI:** +- Shows unread count badge +- Dropdown with recent notifications (last 50) +- "Mark all as read" action +- Click notification → navigate to `linkUrl` +- Auto-refresh via tRPC subscription or polling + +#### 6. Email Delivery (Nodemailer + Poste.io) + +**Email function:** +```typescript +export async function sendStyledNotificationEmail( + to: string, + name: string, + type: string, // Template type + data: { + title: string + message: string + linkUrl?: string + metadata?: Record + } +): Promise +``` + +**Email service:** +- SMTP via Poste.io (`:587`) +- HTML templates with brand colors (Red `#de0f1e`, Dark Blue `#053d57`) +- Support for template variables: `{{name}}`, `{{title}}`, `{{message}}`, `{{linkUrl}}` +- Retry logic (3 attempts) +- Logs sent emails to `NotificationLog` table + +**Current template types:** +```typescript +const EMAIL_TEMPLATES = { + MAGIC_LINK: 'magic-link', + REMINDER_24H: '24-hour-reminder', + REMINDER_1H: '1-hour-reminder', + ASSIGNMENT_CREATED: 'assignment-created', + FILTERING_COMPLETE: 'filtering-complete', + STAGE_TRANSITIONED: 'stage-transitioned', + DECISION_OVERRIDDEN: 'decision-overridden', +} +``` + +#### 7. Notification Policy Configuration + +**Model:** +```prisma +model NotificationPolicy { + id String @id @default(cuid()) + eventType String @unique // e.g., "stage.transitioned" + channel String @default("EMAIL") // EMAIL | IN_APP | BOTH | NONE + templateId String? // Optional reference to MessageTemplate + isActive Boolean @default(true) + configJson Json? @db.JsonB // Additional config + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt +} +``` + +**Admin UI (future):** +``` +┌─ Notification Settings ──────────────────────────────┐ +│ │ +│ Event Type: stage.transitioned │ +│ Channel: [x] Email [x] In-App [ ] Webhook │ +│ Active: [x] Enabled │ +│ Template: [Stage Transition Email ▼] │ +│ │ +│ Recipients: [ ] All Admins [x] Program Admins Only │ +│ │ +│ [Save] [Test Notification] │ +└───────────────────────────────────────────────────────┘ +``` + +--- + +## Redesigned Notification Architecture + +### Key Changes from Current System + +| Aspect | Current (Stage-based) | Redesigned (Round-based) | +|--------|----------------------|--------------------------| +| **Event naming** | `stage.transitioned` | `round.transitioned` | +| **Entity references** | `stageId`, `trackId` | `roundId` only (no trackId) | +| **Deadline config** | Per-stage in `Stage.configJson` | Per-SubmissionWindow + per-Round | +| **Reminder targets** | Jury only | Jury, applicants, mentors (role-based) | +| **Competition-wide settings** | None (per-stage only) | `Competition.notifyOn*` fields | +| **Grace periods** | Stage-level only | Round-level + window-level | +| **Template system** | Hardcoded types | Zod-validated templates with variables | + +### Enhanced Notification Event Model + +**New/renamed events:** +```typescript +export const ROUND_EVENT_TYPES = { + // Core round events + ROUND_OPENED: 'round.opened', + ROUND_CLOSED: 'round.closed', + ROUND_TRANSITIONED: 'round.transitioned', + + // INTAKE events + SUBMISSION_RECEIVED: 'intake.submission_received', + SUBMISSION_DEADLINE_APPROACHING: 'intake.deadline_approaching', + SUBMISSION_DEADLINE_PASSED: 'intake.deadline_passed', + + // FILTERING events + FILTERING_STARTED: 'filtering.started', + FILTERING_COMPLETED: 'filtering.completed', + FILTERING_FLAGGED: 'filtering.flagged_for_review', + PROJECT_ADVANCED: 'filtering.project_advanced', + PROJECT_REJECTED: 'filtering.project_rejected', + + // EVALUATION events + ASSIGNMENT_CREATED: 'evaluation.assignment_created', + EVALUATION_DEADLINE_APPROACHING: 'evaluation.deadline_approaching', + EVALUATION_SUBMITTED: 'evaluation.submitted', + EVALUATION_ROUND_COMPLETE: 'evaluation.round_complete', + + // SUBMISSION events (round 2+ docs) + SUBMISSION_WINDOW_OPENED: 'submission.window_opened', + NEW_DOCS_REQUIRED: 'submission.new_docs_required', + DOCS_SUBMITTED: 'submission.docs_submitted', + DOCS_DEADLINE_APPROACHING: 'submission.deadline_approaching', + + // MENTORING events + MENTOR_ASSIGNED: 'mentoring.assigned', + MENTOR_MESSAGE_RECEIVED: 'mentoring.message_received', + MENTOR_FILE_UPLOADED: 'mentoring.file_uploaded', + MENTOR_FILE_PROMOTED: 'mentoring.file_promoted', + + // LIVE_FINAL events + CEREMONY_STARTING: 'live_final.ceremony_starting', + VOTE_REQUIRED: 'live_final.vote_required', + DELIBERATION_STARTED: 'live_final.deliberation_started', + RESULTS_READY: 'live_final.results_ready', + + // CONFIRMATION events + WINNER_APPROVAL_REQUIRED: 'confirmation.approval_required', + WINNER_APPROVED: 'confirmation.approved', + RESULTS_FROZEN: 'confirmation.frozen', + + // Admin events + DECISION_OVERRIDDEN: 'admin.decision_overridden', + GRACE_PERIOD_GRANTED: 'admin.grace_period_granted', + DEADLINE_EXTENDED: 'admin.deadline_extended', +} +``` + +### Competition-Wide Notification Settings + +**Enhanced Competition model:** +```prisma +model Competition { + // ... existing fields ... + + // Global notification preferences + notifyOnRoundAdvance Boolean @default(true) + notifyOnDeadlineApproach Boolean @default(true) + notifyOnAssignmentCreated Boolean @default(true) + notifyOnSubmissionReceived Boolean @default(true) + notifyOnFilteringComplete Boolean @default(true) + + // Reminder configuration + deadlineReminderDays Int[] @default([7, 3, 1]) // Days before deadline + deadlineReminderHours Int[] @default([24, 3, 1]) // Hours before deadline (final stretch) + + // Email templates + notificationEmailFromName String? // Override default "MOPC Platform" + notificationEmailReplyTo String? // Custom reply-to for this competition + + // Advanced settings + batchNotifications Boolean @default(false) // Group similar notifications + batchIntervalMinutes Int @default(30) // Batch every 30 min + notificationTimezone String @default("UTC") // For deadline display +} +``` + +### Per-Round Notification Overrides + +**Round-level overrides:** +```prisma +model Round { + // ... existing fields ... + + // Notification overrides (null = use competition defaults) + notifyOnRoundOpen Boolean? // Override competition.notifyOnRoundAdvance + notifyOnDeadline Boolean? // Override competition.notifyOnDeadlineApproach + customReminderSchedule Json? @db.JsonB // { days: [7, 3, 1], hours: [24, 6, 1] } + + // Email template overrides + openEmailTemplateId String? // Custom template for round open + reminderEmailTemplateId String? // Custom template for reminders +} +``` + +**Example custom schedule:** +```typescript +// For Live Finals round — aggressive reminders +{ + days: [7, 3], // 7 days before, 3 days before + hours: [24, 12, 6, 1] // 24h, 12h, 6h, 1h before ceremony +} +``` + +--- + +## Deadline Management System + +### DeadlinePolicy Enum + +**Three deadline modes:** +```prisma +enum DeadlinePolicy { + HARD // Submissions rejected after windowCloseAt (strict cutoff) + FLAG // Submissions accepted but marked late (isLate = true) + GRACE // Grace period after windowCloseAt, then hard cutoff +} +``` + +**Applied at SubmissionWindow level:** +```prisma +model SubmissionWindow { + // ... existing fields ... + + deadlinePolicy DeadlinePolicy @default(FLAG) + graceHours Int? // For GRACE policy: hours after windowCloseAt +} +``` + +**Evaluation rounds use Round.windowCloseAt + GracePeriod model:** +```prisma +model Round { + windowOpenAt DateTime? + windowCloseAt DateTime? + + // Jury evaluation deadline behavior + evaluationDeadlinePolicy String @default("FLAG") // "HARD" | "FLAG" | "GRACE" + evaluationGraceHours Int? +} +``` + +### Deadline Enforcement Logic + +**Submission deadline check:** +```typescript +type SubmissionDeadlineCheck = { + allowed: boolean + isLate: boolean + reason?: string +} + +export async function checkSubmissionDeadline( + submissionWindowId: string, + userId: string, + prisma: PrismaClient +): Promise { + const window = await prisma.submissionWindow.findUnique({ + where: { id: submissionWindowId }, + select: { + windowOpenAt: true, + windowCloseAt: true, + deadlinePolicy: true, + graceHours: true, + }, + }) + + const now = new Date() + + // Before window opens + if (window.windowOpenAt && now < window.windowOpenAt) { + return { allowed: false, reason: 'Window not yet open' } + } + + // Within normal window + if (!window.windowCloseAt || now <= window.windowCloseAt) { + return { allowed: true, isLate: false } + } + + // After window close + switch (window.deadlinePolicy) { + case 'HARD': + return { allowed: false, reason: 'Deadline passed (hard cutoff)' } + + case 'FLAG': + return { allowed: true, isLate: true } + + case 'GRACE': { + if (!window.graceHours) { + return { allowed: false, reason: 'Grace period not configured' } + } + + const graceEnd = new Date( + window.windowCloseAt.getTime() + window.graceHours * 60 * 60 * 1000 + ) + + if (now <= graceEnd) { + return { allowed: true, isLate: true } + } else { + return { allowed: false, reason: 'Grace period expired' } + } + } + } +} +``` + +**Evaluation deadline check (with per-user grace periods):** +```typescript +export async function checkEvaluationDeadline( + roundId: string, + userId: string, + prisma: PrismaClient +): Promise { + const round = await prisma.round.findUnique({ + where: { id: roundId }, + select: { + windowCloseAt: true, + evaluationDeadlinePolicy: true, + evaluationGraceHours: true, + }, + }) + + // Check for user-specific grace period (highest priority) + const userGrace = await prisma.gracePeriod.findFirst({ + where: { + roundId, + userId, + extendedUntil: { gte: new Date() }, + }, + orderBy: { extendedUntil: 'desc' }, + }) + + const effectiveDeadline = userGrace?.extendedUntil ?? round.windowCloseAt + const now = new Date() + + if (!effectiveDeadline || now <= effectiveDeadline) { + return { allowed: true, isLate: false } + } + + // Past effective deadline + switch (round.evaluationDeadlinePolicy) { + case 'HARD': + return { allowed: false, reason: 'Evaluation deadline passed' } + + case 'FLAG': + return { allowed: true, isLate: true } + + case 'GRACE': { + if (!round.evaluationGraceHours) { + return { allowed: false, reason: 'Grace period not configured' } + } + + const graceEnd = new Date( + effectiveDeadline.getTime() + round.evaluationGraceHours * 60 * 60 * 1000 + ) + + if (now <= graceEnd) { + return { allowed: true, isLate: true } + } else { + return { allowed: false, reason: 'Grace period expired' } + } + } + } +} +``` + +### Deadline Extension by Admin + +**Admin deadline extension workflow:** +```typescript +// Option 1: Extend round window (affects everyone) +trpc.round.extendDeadline.useMutation({ + roundId: 'round-123', + newWindowCloseAt: new Date('2026-03-15T23:59:59Z'), + reason: 'Extended due to technical issues', + notifyParticipants: true, // Send email to all affected users +}) + +// Option 2: Grant individual grace periods (granular) +trpc.gracePeriod.grant.useMutation({ + roundId: 'round-123', + userId: 'jury-456', + extendedUntil: new Date('2026-03-15T23:59:59Z'), + reason: 'Medical emergency', +}) + +// Option 3: Bulk grace periods for entire jury +trpc.gracePeriod.bulkGrant.useMutation({ + roundId: 'round-123', + userIds: ['jury-1', 'jury-2', 'jury-3'], // All Jury 1 members + extendedUntil: new Date('2026-03-15T23:59:59Z'), + reason: 'Extended for Jury 1', +}) +``` + +**Audit trail:** +All deadline changes create: +1. `DecisionAuditLog` entry with `eventType: "admin.deadline_extended"` +2. `OverrideAction` entry (if overriding automated behavior) +3. In-app notification to affected users +4. Email notification (if `notifyParticipants: true`) + +--- + +## Notification Events by Round Type + +### Complete Event Matrix + +| Round Type | Event | Triggered When | Recipients | Channel | +|------------|-------|----------------|------------|---------| +| **INTAKE** | `intake.window_opened` | Round status → ACTIVE | All applicants | Email + In-app | +| | `intake.submission_received` | ProjectFile.create() | Applicant (team lead) | Email + In-app | +| | `intake.deadline_approaching` | Cron: 7d, 3d, 1d before close | Applicants without submission | Email + In-app | +| | `intake.deadline_passed` | windowCloseAt reached | All applicants | In-app only | +| | `intake.window_extended` | Admin extends deadline | All applicants | Email + In-app | +| **FILTERING** | `filtering.started` | FilteringJob.create() | Admins | In-app only | +| | `filtering.completed` | FilteringJob.status → COMPLETED | Admins | Email + In-app | +| | `filtering.flagged_for_review` | FilteringResult.outcome → FLAGGED | Admins | Email (high priority) | +| | `filtering.project_advanced` | ProjectRoundState.state → PASSED | Applicant (team lead) | Email + In-app | +| | `filtering.project_rejected` | ProjectRoundState.state → REJECTED | Applicant (team lead) | Email + In-app | +| **EVALUATION** | `evaluation.assignment_created` | Assignment.create() | Assigned juror | Email + In-app | +| | `evaluation.deadline_approaching` | Cron: 7d, 3d, 1d, 24h, 3h, 1h before close | Jurors with incomplete assignments | Email + In-app | +| | `evaluation.submitted` | Evaluation.status → SUBMITTED | Admin, jury lead | In-app only | +| | `evaluation.round_complete` | All assignments completed | Admins | Email + In-app | +| | `evaluation.summary_generated` | EvaluationSummary.create() | Admins | In-app only | +| **SUBMISSION** | `submission.window_opened` | SubmissionWindow opens | Eligible teams (PASSED from prev round) | Email + In-app | +| | `submission.new_docs_required` | Round status → ACTIVE | Eligible teams | Email (high priority) | +| | `submission.docs_submitted` | ProjectFile.create() for window | Applicant (team lead) | Email + In-app | +| | `submission.deadline_approaching` | Cron: 7d, 3d, 1d before close | Teams without complete submission | Email + In-app | +| | `submission.docs_reviewed` | Admin marks review complete | Applicant (team lead) | Email + In-app | +| **MENTORING** | `mentoring.assigned` | MentorAssignment.create() | Mentor + Team | Email + In-app | +| | `mentoring.workspace_opened` | Round status → ACTIVE | Mentor + Team | Email + In-app | +| | `mentoring.message_received` | MentorMessage.create() | Recipient (mentor or team) | Email + In-app | +| | `mentoring.file_uploaded` | MentorFile.create() | Other party (mentor or team) | In-app + Email | +| | `mentoring.file_promoted` | MentorFile.isPromoted → true | Team lead | Email + In-app | +| | `mentoring.milestone_completed` | MentorMilestoneCompletion.create() | Mentor + Team | In-app only | +| **LIVE_FINAL** | `live_final.ceremony_starting` | LiveVotingSession.status → IN_PROGRESS | Jury + Audience | Email + In-app | +| | `live_final.vote_required` | LiveProgressCursor updated | Jury members | In-app only (real-time) | +| | `live_final.deliberation_started` | Deliberation period begins | Jury | In-app only | +| | `live_final.results_ready` | All votes cast | Admins | In-app only | +| **CONFIRMATION** | `confirmation.approval_required` | WinnerProposal.create() | Jury members + Admins | Email (urgent) + In-app | +| | `confirmation.approval_received` | WinnerApproval.approved → true | Admins | In-app only | +| | `confirmation.approved` | All approvals received | Admins + Jury | Email + In-app | +| | `confirmation.frozen` | WinnerProposal.frozenAt set | All participants | Email + In-app | +| **ADMIN** | `admin.decision_overridden` | OverrideAction.create() | Admins | Email (audit alert) | +| | `admin.grace_period_granted` | GracePeriod.create() | Affected user | Email + In-app | +| | `admin.deadline_extended` | Round.windowCloseAt updated | All affected users | Email + In-app | + +### Event Payload Schemas (Zod) + +**Base event schema:** +```typescript +import { z } from 'zod' + +export const BaseEventSchema = z.object({ + eventType: z.string(), + entityType: z.string(), + entityId: z.string(), + actorId: z.string(), + timestamp: z.date(), + metadata: z.record(z.unknown()).optional(), +}) + +export type BaseEvent = z.infer +``` + +**Intake events:** +```typescript +export const IntakeWindowOpenedSchema = BaseEventSchema.extend({ + eventType: z.literal('intake.window_opened'), + entityType: z.literal('Round'), + roundId: z.string(), + roundName: z.string(), + windowOpenAt: z.date(), + windowCloseAt: z.date(), + competitionId: z.string(), +}) + +export const SubmissionReceivedSchema = BaseEventSchema.extend({ + eventType: z.literal('intake.submission_received'), + entityType: z.literal('ProjectFile'), + projectId: z.string(), + projectTitle: z.string(), + submittedByUserId: z.string(), + fileCount: z.number(), + isComplete: z.boolean(), // All required files uploaded +}) + +export const DeadlineApproachingSchema = BaseEventSchema.extend({ + eventType: z.literal('intake.deadline_approaching'), + entityType: z.literal('SubmissionWindow'), + roundId: z.string(), + roundName: z.string(), + windowCloseAt: z.date(), + daysRemaining: z.number(), + hoursRemaining: z.number().optional(), +}) +``` + +**Evaluation events:** +```typescript +export const AssignmentCreatedSchema = BaseEventSchema.extend({ + eventType: z.literal('evaluation.assignment_created'), + entityType: z.literal('Assignment'), + assignmentId: z.string(), + roundId: z.string(), + roundName: z.string(), + projectId: z.string(), + projectTitle: z.string(), + juryGroupId: z.string(), + juryGroupName: z.string(), + deadline: z.date(), +}) + +export const EvaluationDeadlineApproachingSchema = BaseEventSchema.extend({ + eventType: z.literal('evaluation.deadline_approaching'), + entityType: z.literal('Round'), + roundId: z.string(), + roundName: z.string(), + incompleteCount: z.number(), + totalCount: z.number(), + deadline: z.date(), + reminderType: z.enum(['7d', '3d', '1d', '24h', '3h', '1h']), +}) +``` + +**Mentoring events:** +```typescript +export const MentorAssignedSchema = BaseEventSchema.extend({ + eventType: z.literal('mentoring.assigned'), + entityType: z.literal('MentorAssignment'), + mentorId: z.string(), + mentorName: z.string(), + projectId: z.string(), + projectTitle: z.string(), + teamLeadId: z.string(), + teamLeadName: z.string(), + workspaceOpenAt: z.date().optional(), +}) + +export const MentorFileUploadedSchema = BaseEventSchema.extend({ + eventType: z.literal('mentoring.file_uploaded'), + entityType: z.literal('MentorFile'), + fileId: z.string(), + fileName: z.string(), + uploadedByUserId: z.string(), + uploadedByRole: z.enum(['MENTOR', 'APPLICANT']), + mentorAssignmentId: z.string(), + projectId: z.string(), +}) +``` + +**Confirmation events:** +```typescript +export const WinnerApprovalRequiredSchema = BaseEventSchema.extend({ + eventType: z.literal('confirmation.approval_required'), + entityType: z.literal('WinnerProposal'), + proposalId: z.string(), + category: z.enum(['STARTUP', 'BUSINESS_CONCEPT']), + rankedProjectIds: z.array(z.string()), + requiredApprovers: z.array(z.object({ + userId: z.string(), + role: z.enum(['JURY_MEMBER', 'ADMIN']), + })), + deadline: z.date().optional(), +}) + +export const ResultsFrozenSchema = BaseEventSchema.extend({ + eventType: z.literal('confirmation.frozen'), + entityType: z.literal('WinnerProposal'), + proposalId: z.string(), + category: z.enum(['STARTUP', 'BUSINESS_CONCEPT']), + frozenAt: z.date(), + frozenByUserId: z.string(), + rankedProjectIds: z.array(z.string()), +}) +``` + +--- + +## Notification Channels + +### 1. Email Channel + +**Email service interface:** +```typescript +export interface EmailNotificationData { + to: string // Recipient email + name: string // Recipient name + subject: string // Email subject + template: string // Template ID + variables: Record // Template variables + replyTo?: string // Custom reply-to + priority?: 'low' | 'normal' | 'high' | 'urgent' +} + +export async function sendNotificationEmail( + data: EmailNotificationData +): Promise +``` + +**Email templates with variables:** +```typescript +// Template: evaluation-deadline-reminder +const template = ` + + + + + + +
+

{{competitionName}}

+
+
+

Dear {{name}},

+ +

This is a reminder that you have {{incompleteCount}} pending evaluation{{incompleteCount > 1 ? 's' : ''}} for {{roundName}}.

+ +
+

⏰ Deadline: {{deadline}}

+

{{timeRemaining}} remaining

+
+ +

Please complete your evaluations before the deadline.

+ +

+ Complete Evaluations +

+ +

If you need an extension, please contact the program administrator.

+ +

Best regards,
{{competitionName}} Team

+
+ + +` + +// Variables passed to template: +{ + name: "Dr. Smith", + competitionName: "MOPC 2026", + roundName: "Jury 1 - Semi-finalist Selection", + incompleteCount: 5, + deadline: "March 15, 2026 at 11:59 PM CET", + timeRemaining: "2 days 5 hours", + linkUrl: "https://monaco-opc.com/jury/rounds/round-123/assignments" +} +``` + +**Email delivery tracking:** +```prisma +model NotificationLog { + id String @id @default(cuid()) + userId String + channel NotificationChannel // EMAIL, WHATSAPP, BOTH, NONE + provider String? // SMTP, META, TWILIO + type String // Event type + status String // PENDING, SENT, DELIVERED, FAILED + externalId String? // Message ID from provider + errorMsg String? @db.Text + createdAt DateTime @default(now()) +} +``` + +### 2. In-App Notification Center + +**UI components:** + +**Notification Bell (Header):** +```tsx +// src/components/layout/notification-bell.tsx +'use client' + +import { Bell } from 'lucide-react' +import { Button } from '@/components/ui/button' +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuTrigger, +} from '@/components/ui/dropdown-menu' +import { trpc } from '@/lib/trpc/client' +import { NotificationItem } from './notification-item' + +export function NotificationBell() { + const { data: unreadCount } = trpc.notification.getUnreadCount.useQuery() + const { data: recent } = trpc.notification.getRecent.useQuery({ limit: 10 }) + const markAllRead = trpc.notification.markAllRead.useMutation() + + return ( + + + + + + +
+

Notifications

+ {unreadCount > 0 && ( + + )} +
+ +
+ {recent?.map((notification) => ( + + ))} + + {recent?.length === 0 && ( +
+ No notifications +
+ )} +
+ +
+ +
+ + + ) +} +``` + +**Notification Item:** +```tsx +// src/components/layout/notification-item.tsx +'use client' + +import { useRouter } from 'next/navigation' +import { formatDistanceToNow } from 'date-fns' +import { cn } from '@/lib/utils' +import { trpc } from '@/lib/trpc/client' +import * as Icons from 'lucide-react' + +type Notification = { + id: string + type: string + title: string + message: string + icon?: string + priority: string + linkUrl?: string + isRead: boolean + createdAt: Date +} + +export function NotificationItem({ notification }: { notification: Notification }) { + const router = useRouter() + const markRead = trpc.notification.markRead.useMutation() + + const Icon = notification.icon ? Icons[notification.icon] : Icons.Bell + + const handleClick = () => { + if (!notification.isRead) { + markRead.mutate({ id: notification.id }) + } + + if (notification.linkUrl) { + router.push(notification.linkUrl) + } + } + + return ( +
+ {Icon && ( +
+ +
+ )} + +
+
+

+ {notification.title} +

+ {!notification.isRead && ( +
+ )} +
+ +

+ {notification.message} +

+ +

+ {formatDistanceToNow(notification.createdAt, { addSuffix: true })} +

+
+
+ ) +} +``` + +**Notification Center Page:** +```tsx +// src/app/(authenticated)/notifications/page.tsx +'use client' + +import { useState } from 'react' +import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs' +import { trpc } from '@/lib/trpc/client' +import { NotificationItem } from '@/components/layout/notification-item' + +export default function NotificationsPage() { + const [filter, setFilter] = useState<'all' | 'unread'>('all') + + const { data: notifications } = trpc.notification.getAll.useQuery({ + filter, + limit: 100, + }) + + return ( +
+

Notifications

+ + setFilter(v as any)}> + + All + Unread + + + +
+ {notifications?.map((n) => ( + + ))} + + {notifications?.length === 0 && ( +
+ No notifications to show +
+ )} +
+ + +
+ ) +} +``` + +### 3. Future: Webhook Channel + +**Webhook integration (future enhancement):** +```typescript +// Future: Webhook delivery for external integrations +export interface WebhookNotificationPayload { + event: string + timestamp: string + data: Record + signature: string // HMAC signature for verification +} + +// Example webhook payload +{ + event: "evaluation.deadline_approaching", + timestamp: "2026-03-10T15:00:00Z", + data: { + competitionId: "comp-123", + roundId: "round-456", + roundName: "Jury 1 - Semi-finalist Selection", + deadline: "2026-03-15T23:59:59Z", + daysRemaining: 5, + incompleteAssignments: 12, + totalAssignments: 60 + }, + signature: "sha256=..." +} +``` + +**Webhook configuration (future):** +```prisma +model Webhook { + id String @id @default(cuid()) + name String + url String + secret String // For HMAC signature + events String[] // Event types to subscribe to + headers Json? @db.JsonB + maxRetries Int @default(3) + isActive Boolean @default(true) + createdById String +} +``` + +--- + +## Countdown Timer System + +### Real-Time Countdown Component + +**Enhanced countdown timer:** +```tsx +// src/components/shared/countdown-timer.tsx +'use client' + +import { useState, useEffect } from 'react' +import { cn } from '@/lib/utils' +import { Clock, AlertTriangle, CheckCircle } from 'lucide-react' + +export interface CountdownTimerProps { + deadline: Date + label?: string + className?: string + showIcon?: boolean + size?: 'sm' | 'md' | 'lg' + onExpire?: () => void +} + +interface TimeRemaining { + days: number + hours: number + minutes: number + seconds: number + totalMs: number +} + +function getTimeRemaining(deadline: Date): TimeRemaining { + const totalMs = deadline.getTime() - Date.now() + if (totalMs <= 0) { + return { days: 0, hours: 0, minutes: 0, seconds: 0, totalMs: 0 } + } + + const seconds = Math.floor((totalMs / 1000) % 60) + const minutes = Math.floor((totalMs / 1000 / 60) % 60) + const hours = Math.floor((totalMs / (1000 * 60 * 60)) % 24) + const days = Math.floor(totalMs / (1000 * 60 * 60 * 24)) + + return { days, hours, minutes, seconds, totalMs } +} + +function formatCountdown(time: TimeRemaining, size: 'sm' | 'md' | 'lg'): string { + if (time.totalMs <= 0) return 'Deadline passed' + + const { days, hours, minutes, seconds } = time + + // Small size: compact format + if (size === 'sm') { + if (days === 0 && hours === 0) return `${minutes}m ${seconds}s` + if (days === 0) return `${hours}h ${minutes}m` + return `${days}d ${hours}h` + } + + // Medium/large: more detail + if (days === 0 && hours === 0) { + return `${minutes} minutes ${seconds} seconds` + } + + if (days === 0) { + return `${hours} hours ${minutes} minutes` + } + + return `${days} days ${hours} hours ${minutes} minutes` +} + +type Urgency = 'expired' | 'critical' | 'warning' | 'normal' + +function getUrgency(totalMs: number): Urgency { + if (totalMs <= 0) return 'expired' + if (totalMs < 60 * 60 * 1000) return 'critical' // < 1 hour + if (totalMs < 24 * 60 * 60 * 1000) return 'warning' // < 24 hours + if (totalMs < 7 * 24 * 60 * 60 * 1000) return 'normal' // < 7 days + return 'normal' +} + +const urgencyStyles: Record = { + expired: 'text-muted-foreground bg-muted border-muted', + critical: 'text-red-700 bg-red-50 border-red-200 dark:text-red-400 dark:bg-red-950/50 dark:border-red-900', + warning: 'text-amber-700 bg-amber-50 border-amber-200 dark:text-amber-400 dark:bg-amber-950/50 dark:border-amber-900', + normal: 'text-green-700 bg-green-50 border-green-200 dark:text-green-400 dark:bg-green-950/50 dark:border-green-900', +} + +const sizeStyles = { + sm: 'text-xs px-2 py-0.5', + md: 'text-sm px-2.5 py-1', + lg: 'text-base px-3 py-1.5', +} + +export function CountdownTimer({ + deadline, + label, + className, + showIcon = true, + size = 'md', + onExpire, +}: CountdownTimerProps) { + const [time, setTime] = useState(() => getTimeRemaining(deadline)) + const [hasExpired, setHasExpired] = useState(false) + + useEffect(() => { + const timer = setInterval(() => { + const remaining = getTimeRemaining(deadline) + setTime(remaining) + + if (remaining.totalMs <= 0 && !hasExpired) { + clearInterval(timer) + setHasExpired(true) + onExpire?.() + } + }, 1000) + + return () => clearInterval(timer) + }, [deadline, hasExpired, onExpire]) + + const urgency = getUrgency(time.totalMs) + const displayText = formatCountdown(time, size) + + const IconComponent = + urgency === 'expired' ? CheckCircle : + urgency === 'critical' ? AlertTriangle : + Clock + + return ( +
+ {showIcon && } + {label && {label}} + {displayText} +
+ ) +} +``` + +**Usage examples:** +```tsx +// Jury dashboard - evaluation deadline + toast.info('Deadline has passed')} +/> + +// Applicant dashboard - submission deadline + + +// Admin dashboard - compact view + +``` + +### Server-Side Time Sync + +**Prevent client clock drift:** +```typescript +// src/server/routers/time.ts +import { router, publicProcedure } from '../trpc' + +export const timeRouter = router({ + /** + * Get server time (for clock sync) + */ + getServerTime: publicProcedure.query(() => { + return { + serverTime: new Date().toISOString(), + timezone: 'UTC', + } + }), +}) + +// Client-side sync +// src/hooks/use-server-time-sync.ts +'use client' + +import { useEffect, useState } from 'use' +import { trpc } from '@/lib/trpc/client' + +export function useServerTimeSync() { + const [timeOffset, setTimeOffset] = useState(0) + const { data } = trpc.time.getServerTime.useQuery() + + useEffect(() => { + if (data) { + const serverTime = new Date(data.serverTime).getTime() + const clientTime = Date.now() + setTimeOffset(serverTime - clientTime) + } + }, [data]) + + const getSyncedTime = () => Date.now() + timeOffset + + return { getSyncedTime, timeOffset } +} + +// Use in countdown +function getTimeRemaining(deadline: Date): TimeRemaining { + const { getSyncedTime } = useServerTimeSync() + const totalMs = deadline.getTime() - getSyncedTime() + // ... rest of logic +} +``` + +--- + +## Reminder Scheduling + +### Cron-Based Reminder System + +**Cron endpoint:** +```typescript +// src/app/api/cron/reminders/route.ts +import { NextResponse } from 'next/server' +import type { NextRequest } from 'next/server' +import { processDeadlineReminders } from '@/server/services/deadline-reminders' + +export async function GET(request: NextRequest): Promise { + // Verify cron secret + const cronSecret = request.headers.get('x-cron-secret') + + if (!cronSecret || cronSecret !== process.env.CRON_SECRET) { + return NextResponse.json({ error: 'Unauthorized' }, { status: 401 }) + } + + try { + const result = await processDeadlineReminders() + + return NextResponse.json({ + ok: true, + sent: result.sent, + errors: result.errors, + timestamp: new Date().toISOString(), + }) + } catch (error) { + console.error('Cron reminder processing failed:', error) + return NextResponse.json( + { error: 'Internal server error' }, + { status: 500 } + ) + } +} +``` + +**Reminder processor (redesigned):** +```typescript +// src/server/services/deadline-reminders.ts +import { prisma } from '@/lib/prisma' +import { sendNotificationEmail } from '@/lib/email' +import { emitRoundEvent } from './round-notifications' + +interface ReminderResult { + sent: number + errors: number +} + +/** + * Process deadline reminders for all active rounds and submission windows. + * Called by cron job every 15 minutes. + */ +export async function processDeadlineReminders(): Promise { + const now = new Date() + let totalSent = 0 + let totalErrors = 0 + + // Process evaluation round reminders + const evalResults = await processEvaluationReminders(now) + totalSent += evalResults.sent + totalErrors += evalResults.errors + + // Process submission window reminders + const submissionResults = await processSubmissionReminders(now) + totalSent += submissionResults.sent + totalErrors += submissionResults.errors + + return { sent: totalSent, errors: totalErrors } +} + +/** + * Send reminders to jurors with incomplete evaluations. + */ +async function processEvaluationReminders(now: Date): Promise { + let sent = 0 + let errors = 0 + + // Find active evaluation rounds with upcoming deadlines + const rounds = await prisma.round.findMany({ + where: { + roundType: 'EVALUATION', + status: 'ROUND_ACTIVE', + windowCloseAt: { gt: now }, + windowOpenAt: { lte: now }, + }, + select: { + id: true, + name: true, + windowCloseAt: true, + competition: { + select: { + id: true, + name: true, + deadlineReminderDays: true, + deadlineReminderHours: true, + }, + }, + }, + }) + + for (const round of rounds) { + if (!round.windowCloseAt) continue + + const msUntilDeadline = round.windowCloseAt.getTime() - now.getTime() + + // Determine which reminders should fire + const reminderTypes = getReminderTypesForDeadline( + msUntilDeadline, + round.competition.deadlineReminderDays, + round.competition.deadlineReminderHours + ) + + if (reminderTypes.length === 0) continue + + for (const reminderType of reminderTypes) { + const result = await sendEvaluationReminders(round, reminderType, now) + sent += result.sent + errors += result.errors + } + } + + return { sent, errors } +} + +/** + * Send reminders to applicants with incomplete submissions. + */ +async function processSubmissionReminders(now: Date): Promise { + let sent = 0 + let errors = 0 + + // Find active submission windows with upcoming deadlines + const windows = await prisma.submissionWindow.findMany({ + where: { + windowCloseAt: { gt: now }, + windowOpenAt: { lte: now }, + }, + select: { + id: true, + name: true, + windowCloseAt: true, + competition: { + select: { + id: true, + name: true, + deadlineReminderDays: true, + deadlineReminderHours: true, + }, + }, + fileRequirements: { + select: { id: true, isRequired: true }, + }, + rounds: { + select: { id: true, name: true }, + where: { roundType: { in: ['INTAKE', 'SUBMISSION'] } }, + }, + }, + }) + + for (const window of windows) { + if (!window.windowCloseAt) continue + + const msUntilDeadline = window.windowCloseAt.getTime() - now.getTime() + + const reminderTypes = getReminderTypesForDeadline( + msUntilDeadline, + window.competition.deadlineReminderDays, + window.competition.deadlineReminderHours + ) + + if (reminderTypes.length === 0) continue + + for (const reminderType of reminderTypes) { + const result = await sendSubmissionReminders(window, reminderType, now) + sent += result.sent + errors += result.errors + } + } + + return { sent, errors } +} + +/** + * Determine which reminder types should fire based on time until deadline. + */ +function getReminderTypesForDeadline( + msUntilDeadline: number, + reminderDays: number[], + reminderHours: number[] +): string[] { + const types: string[] = [] + + // Check day-based reminders + for (const days of reminderDays) { + const thresholdMs = days * 24 * 60 * 60 * 1000 + const windowMs = 15 * 60 * 1000 // 15-minute cron window + + if (Math.abs(msUntilDeadline - thresholdMs) < windowMs) { + types.push(`${days}d`) + } + } + + // Check hour-based reminders (only if < 48 hours remaining) + if (msUntilDeadline < 48 * 60 * 60 * 1000) { + for (const hours of reminderHours) { + const thresholdMs = hours * 60 * 60 * 1000 + const windowMs = 15 * 60 * 1000 + + if (Math.abs(msUntilDeadline - thresholdMs) < windowMs) { + types.push(`${hours}h`) + } + } + } + + return types +} + +/** + * Send evaluation deadline reminders to jurors. + */ +async function sendEvaluationReminders( + round: any, + reminderType: string, + now: Date +): Promise { + let sent = 0 + let errors = 0 + + // Find jurors with incomplete assignments + const incompleteAssignments = await prisma.assignment.findMany({ + where: { + roundId: round.id, + isCompleted: false, + }, + select: { + userId: true, + user: { + select: { + id: true, + name: true, + email: true, + }, + }, + }, + }) + + // Group by user + const userAssignments = new Map() + for (const assignment of incompleteAssignments) { + userAssignments.set( + assignment.userId, + (userAssignments.get(assignment.userId) || 0) + 1 + ) + } + + // Check who already received this reminder + const existingReminders = await prisma.reminderLog.findMany({ + where: { + roundId: round.id, + type: reminderType, + }, + select: { userId: true }, + }) + + const alreadySent = new Set(existingReminders.map((r) => r.userId)) + + // Send reminders + for (const [userId, incompleteCount] of userAssignments.entries()) { + if (alreadySent.has(userId)) continue + + const assignment = incompleteAssignments.find((a) => a.userId === userId) + if (!assignment) continue + + try { + await sendNotificationEmail({ + to: assignment.user.email, + name: assignment.user.name || '', + subject: `Reminder: ${incompleteCount} pending evaluation${incompleteCount > 1 ? 's' : ''}`, + template: 'evaluation-deadline-reminder', + variables: { + name: assignment.user.name, + competitionName: round.competition.name, + roundName: round.name, + incompleteCount, + totalCount: userAssignments.get(userId), + deadline: round.windowCloseAt.toISOString(), + reminderType, + linkUrl: `${process.env.NEXTAUTH_URL}/jury/rounds/${round.id}/assignments`, + }, + priority: reminderType.includes('h') ? 'high' : 'normal', + }) + + // Log reminder + await prisma.reminderLog.create({ + data: { + roundId: round.id, + userId, + type: reminderType, + }, + }) + + // Emit event + await emitRoundEvent( + 'evaluation.deadline_approaching', + 'Round', + round.id, + 'system', + { + roundId: round.id, + roundName: round.name, + userId, + incompleteCount, + reminderType, + deadline: round.windowCloseAt, + }, + prisma + ) + + sent++ + } catch (error) { + console.error( + `Failed to send ${reminderType} reminder to ${assignment.user.email}:`, + error + ) + errors++ + } + } + + return { sent, errors } +} + +/** + * Send submission deadline reminders to applicants. + */ +async function sendSubmissionReminders( + window: any, + reminderType: string, + now: Date +): Promise { + let sent = 0 + let errors = 0 + + // Find projects in this submission window's rounds + const roundIds = window.rounds.map((r: any) => r.id) + + const eligibleProjects = await prisma.projectRoundState.findMany({ + where: { + roundId: { in: roundIds }, + state: { in: ['PENDING', 'IN_PROGRESS'] }, + }, + select: { + projectId: true, + project: { + select: { + id: true, + title: true, + submittedByUserId: true, + submittedBy: { + select: { + id: true, + name: true, + email: true, + }, + }, + }, + }, + }, + }) + + // Check which projects have incomplete submissions + const requiredFileCount = window.fileRequirements.filter( + (r: any) => r.isRequired + ).length + + for (const state of eligibleProjects) { + if (!state.project.submittedBy) continue + + // Count uploaded files for this window + const uploadedFiles = await prisma.projectFile.count({ + where: { + projectId: state.projectId, + submissionWindowId: window.id, + }, + }) + + const isIncomplete = uploadedFiles < requiredFileCount + + if (!isIncomplete) continue + + // Check if already sent this reminder + const existing = await prisma.reminderLog.findUnique({ + where: { + roundId_userId_type: { + roundId: window.rounds[0].id, + userId: state.project.submittedByUserId, + type: reminderType, + }, + }, + }) + + if (existing) continue + + try { + await sendNotificationEmail({ + to: state.project.submittedBy.email, + name: state.project.submittedBy.name || '', + subject: `Reminder: Complete your submission for ${window.name}`, + template: 'submission-deadline-reminder', + variables: { + name: state.project.submittedBy.name, + competitionName: window.competition.name, + windowName: window.name, + projectTitle: state.project.title, + uploadedCount: uploadedFiles, + requiredCount: requiredFileCount, + deadline: window.windowCloseAt.toISOString(), + reminderType, + linkUrl: `${process.env.NEXTAUTH_URL}/applicant/submissions/${window.id}`, + }, + priority: reminderType.includes('h') ? 'high' : 'normal', + }) + + // Log reminder + await prisma.reminderLog.create({ + data: { + roundId: window.rounds[0].id, + userId: state.project.submittedByUserId, + type: reminderType, + }, + }) + + sent++ + } catch (error) { + console.error( + `Failed to send ${reminderType} reminder to ${state.project.submittedBy.email}:`, + error + ) + errors++ + } + } + + return { sent, errors } +} +``` + +### Deduplication Strategy + +**ReminderLog unique constraint:** +```prisma +model ReminderLog { + id String @id @default(cuid()) + roundId String + userId String + type String // "7d", "3d", "1d", "24h", "3h", "1h" + sentAt DateTime @default(now()) + + @@unique([roundId, userId, type]) // Prevent duplicate reminders + @@index([roundId]) + @@index([userId]) +} +``` + +**Logic:** +1. Cron runs every 15 minutes +2. For each active round/window with deadline, calculate `msUntilDeadline` +3. Check if any reminder threshold matches (within 15-min window) +4. For each matching reminder type, query `ReminderLog` to see if already sent +5. Send only to users without existing log entry +6. Create `ReminderLog` entry after successful send + +**Example timeline:** +``` +Deadline: March 15, 2026 at 11:59 PM +Now: March 8, 2026 at 12:00 PM (7 days before) + +Cron check at 12:00 PM: + - msUntilDeadline = 7 * 24 * 60 * 60 * 1000 = 604,800,000 ms + - Match "7d" reminder (within 15-min window) + - Query ReminderLog for (roundId, userId, type="7d") + - If not exists → send email + create log + - If exists → skip + +Cron check at 12:15 PM: + - msUntilDeadline = 604,800,000 ms - 900,000 ms = slightly less + - No longer within 15-min window of "7d" threshold + - No reminders sent + +Cron check at 3:00 PM (3 days before): + - msUntilDeadline = 3 * 24 * 60 * 60 * 1000 + - Match "3d" reminder + - Send to users without "3d" log +``` + +--- + +## Admin Notification Controls + +### Competition-Wide Settings UI + +**ASCII mockup:** +``` +┌─ Competition Settings: MOPC 2026 ─────────────────────────────────────┐ +│ │ +│ ┌─ Notification Preferences ──────────────────────────────────────┐ │ +│ │ │ │ +│ │ Global Toggles: │ │ +│ │ [x] Notify on round advancement │ │ +│ │ [x] Notify on deadline approaching │ │ +│ │ [x] Notify on assignment created │ │ +│ │ [x] Notify on submission received │ │ +│ │ [x] Notify on filtering complete │ │ +│ │ │ │ +│ │ Reminder Schedule: │ │ +│ │ Days before deadline: [7] [3] [1] [+ Add] │ │ +│ │ Hours before deadline (final 48h): [24] [3] [1] [+ Add] │ │ +│ │ │ │ +│ │ Email Settings: │ │ +│ │ From name: [MOPC 2026 Platform ] │ │ +│ │ Reply-to: [admin@monaco-opc.com ] │ │ +│ │ │ │ +│ │ Advanced: │ │ +│ │ [ ] Batch similar notifications (group within 30 min) │ │ +│ │ Timezone: [UTC ▼] │ │ +│ │ │ │ +│ │ [Save Changes] [Reset to Defaults] │ │ +│ └───────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Notification History ─────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Last 24 hours: │ │ +│ │ ✉ 156 emails sent │ │ +│ │ 📱 243 in-app notifications created │ │ +│ │ ⚠ 2 delivery failures │ │ +│ │ │ │ +│ │ [View Full Log] [Download Report] │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Per-Round Notification Overrides + +**ASCII mockup:** +``` +┌─ Round Settings: Jury 1 - Semi-finalist Selection ────────────────────┐ +│ │ +│ ┌─ Notification Overrides ────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Inherit from competition: │ │ +│ │ [x] Use competition reminder schedule │ │ +│ │ [x] Use competition email templates │ │ +│ │ │ │ +│ │ Custom Reminder Schedule (overrides competition): │ │ +│ │ [ ] Enable custom schedule │ │ +│ │ Days before: [ ] [ ] [ ] │ │ +│ │ Hours before: [ ] [ ] [ ] │ │ +│ │ │ │ +│ │ Email Templates: │ │ +│ │ Round open: [Default Template ▼] │ │ +│ │ Reminder: [Default Template ▼] │ │ +│ │ Deadline passed:[Default Template ▼] │ │ +│ │ │ │ +│ │ Notification Toggles: │ │ +│ │ [x] Notify jurors when round opens │ │ +│ │ [x] Send deadline reminders │ │ +│ │ [ ] Notify admins on each evaluation submission (high volume) │ │ +│ │ │ │ +│ │ [Save Overrides] [Clear All Overrides] │ │ +│ └───────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Manual Notification Sending + +**Broadcast notification UI:** +``` +┌─ Send Manual Notification ──────────────────────────────────────────┐ +│ │ +│ Target Audience: │ +│ ( ) All jury members in this competition │ +│ ( ) All applicants with active projects │ +│ ( ) Specific jury group: [Jury 1 ▼] │ +│ ( ) Specific round participants: [Round 3 ▼] │ +│ (•) Custom user list │ +│ │ +│ ┌─ Custom Users ───────────────────────────────────────────────┐ │ +│ │ [Search users by name or email... ] [+ Add] │ │ +│ │ │ │ +│ │ Selected (3): │ │ +│ │ • Dr. Alice Smith (alice@example.com) [Remove] │ │ +│ │ • Prof. Bob Johnson (bob@example.com) [Remove] │ │ +│ │ • Dr. Carol White (carol@example.com) [Remove] │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ Subject: │ +│ [Important: Competition Schedule Update ] │ +│ │ +│ Message: │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Dear {{name}}, │ │ +│ │ │ │ +│ │ Due to unforeseen circumstances, the evaluation deadline │ │ +│ │ for Jury 1 has been extended to March 20, 2026. │ │ +│ │ │ │ +│ │ Please complete your evaluations by the new deadline. │ │ +│ │ │ │ +│ │ Best regards, │ │ +│ │ MOPC Team │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ Delivery: │ +│ [x] Send email │ +│ [x] Create in-app notification │ +│ Priority: [Normal ▼] │ +│ │ +│ [Preview] [Send Now] [Schedule for Later] │ +└───────────────────────────────────────────────────────────────────────┘ +``` + +### Notification Log/History + +**Admin notification log:** +``` +┌─ Notification Log ─────────────────────────────────────────────────────┐ +│ │ +│ Filters: │ +│ Date range: [Last 7 days ▼] Type: [All types ▼] │ +│ Channel: [All ▼] Status: [All ▼] User: [ ] │ +│ │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ Timestamp │ Type │ User │ Ch.│ Status│ │ +│ ├────────────────────────────────────────────────────────────────────┤ │ +│ │ 2026-03-10 15:30 │ evaluation.deadline │ Dr. Smith │ ✉ │ ✓ Sent│ │ +│ │ 2026-03-10 15:30 │ evaluation.deadline │ Prof. Lee │ ✉ │ ✓ Sent│ │ +│ │ 2026-03-10 15:30 │ evaluation.deadline │ Dr. Garcia │ ✉ │ ✗ Fail│ │ +│ │ 2026-03-10 14:00 │ filtering.completed │ Admin │ ✉📱│ ✓ Sent│ │ +│ │ 2026-03-10 12:15 │ intake.submission │ Team Alpha │ ✉ │ ✓ Sent│ │ +│ │ 2026-03-09 18:00 │ mentoring.message │ Team Beta │ 📱 │ ✓ Sent│ │ +│ │ 2026-03-09 16:45 │ assignment.created │ Dr. Kim │ ✉📱│ ✓ Sent│ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Showing 7 of 482 notifications │ +│ [Previous] [1] [2] [3] ... [69] [Next] │ +│ │ +│ [Export CSV] [Download Full Report] │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Template System + +### Email Template Model + +**Enhanced MessageTemplate model:** +```prisma +model MessageTemplate { + id String @id @default(cuid()) + name String + category String // 'SYSTEM', 'EVALUATION', 'SUBMISSION', 'MENTORING', 'LIVE_FINAL' + eventType String? // Optional: link to specific event type + subject String + body String @db.Text // HTML template + variables Json? @db.JsonB // Available template variables + isActive Boolean @default(true) + isSystem Boolean @default(false) // System templates can't be deleted + createdBy String + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + creator User @relation("MessageTemplateCreator", fields: [createdBy], references: [id]) + messages Message[] + + @@index([category]) + @@index([isActive]) + @@index([eventType]) +} +``` + +### Template Variables + +**Standard variables available in all templates:** +```typescript +export const STANDARD_VARIABLES = { + // User variables + name: 'Recipient name', + email: 'Recipient email', + role: 'User role', + + // Competition variables + competitionName: 'Competition name', + competitionYear: 'Competition year', + + // Round variables + roundName: 'Round name', + roundType: 'Round type', + deadline: 'Deadline (formatted)', + windowOpenAt: 'Window open date', + windowCloseAt: 'Window close date', + + // Link variables + linkUrl: 'Call-to-action link', + baseUrl: 'Platform base URL', + + // Meta + currentDate: 'Current date', + timestamp: 'Current timestamp', +} +``` + +**Event-specific variables:** +```typescript +// evaluation.deadline_approaching +export const EVALUATION_DEADLINE_VARIABLES = { + ...STANDARD_VARIABLES, + incompleteCount: 'Number of incomplete evaluations', + totalCount: 'Total assigned evaluations', + daysRemaining: 'Days until deadline', + hoursRemaining: 'Hours until deadline', + reminderType: 'Reminder type (7d, 3d, 1d, etc.)', +} + +// intake.submission_received +export const SUBMISSION_RECEIVED_VARIABLES = { + ...STANDARD_VARIABLES, + projectTitle: 'Project title', + projectId: 'Project ID', + fileCount: 'Number of files uploaded', + requiredFileCount: 'Number of required files', + isComplete: 'Whether submission is complete', +} + +// mentoring.file_uploaded +export const MENTOR_FILE_VARIABLES = { + ...STANDARD_VARIABLES, + fileName: 'Uploaded file name', + uploadedByName: 'Name of uploader', + uploadedByRole: 'Role of uploader (MENTOR or APPLICANT)', + projectTitle: 'Project title', +} +``` + +### Template Editor UI + +**ASCII mockup:** +``` +┌─ Email Template Editor ────────────────────────────────────────────────┐ +│ │ +│ Template Name: [Evaluation Deadline Reminder ] │ +│ Category: [Evaluation ▼] │ +│ Event Type: [evaluation.deadline_approaching ▼] │ +│ │ +│ Subject: │ +│ [Reminder: {{incompleteCount}} pending evaluation(s) ] │ +│ │ +│ ┌─ Available Variables ──────────────────────────────────────────────┐ │ +│ │ Click to insert: │ │ +│ │ {{name}} {{competitionName}} {{roundName}} {{deadline}} │ │ +│ │ {{incompleteCount}} {{totalCount}} {{linkUrl}} [View all...] │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Body (HTML): │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │
│ │ +│ │

{{competitionName}}

│ │ +│ │
│ │ +│ │
│ │ +│ │

Dear {{name}},

│ │ +│ │

You have {{incompleteCount}} pending ... │ │ +│ │ ... │ │ +│ │ [40 more lines] │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Preview with sample data: [Generate Preview] │ +│ │ +│ [Save Draft] [Save & Activate] [Send Test Email] [Cancel] │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### Template Validation + +**Zod schema for template validation:** +```typescript +import { z } from 'zod' + +export const TemplateVariableSchema = z.object({ + key: z.string(), + label: z.string(), + type: z.enum(['string', 'number', 'date', 'boolean', 'url']), + required: z.boolean().default(false), + description: z.string().optional(), +}) + +export const MessageTemplateSchema = z.object({ + name: z.string().min(1, 'Name is required'), + category: z.enum(['SYSTEM', 'EVALUATION', 'SUBMISSION', 'MENTORING', 'LIVE_FINAL']), + eventType: z.string().optional(), + subject: z.string().min(1, 'Subject is required'), + body: z.string().min(1, 'Body is required'), + variables: z.array(TemplateVariableSchema).optional(), + isActive: z.boolean().default(true), +}) + +export type TemplateVariable = z.infer +export type MessageTemplateInput = z.infer +``` + +**Template validation function:** +```typescript +export function validateTemplate( + template: string, + variables: Record +): { valid: boolean; errors: string[] } { + const errors: string[] = [] + + // Extract all {{variable}} references + const variableRefs = template.match(/\{\{(\w+)\}\}/g) || [] + + for (const ref of variableRefs) { + const varName = ref.replace(/\{\{|\}\}/g, '') + + if (!(varName in variables)) { + errors.push(`Unknown variable: ${varName}`) + } + } + + // Check for malformed syntax + const malformed = template.match(/\{[^{]|\}[^}]/g) + if (malformed) { + errors.push('Malformed variable syntax detected') + } + + return { + valid: errors.length === 0, + errors, + } +} +``` + +--- + +## API Changes (tRPC) + +### Notification Router + +**Complete notification router:** +```typescript +// src/server/routers/notification.ts +import { z } from 'zod' +import { router, protectedProcedure, adminProcedure } from '../trpc' +import { logAudit } from '../utils/audit' + +export const notificationRouter = router({ + /** + * Get unread count for current user + */ + getUnreadCount: protectedProcedure.query(async ({ ctx }) => { + return ctx.prisma.inAppNotification.count({ + where: { + userId: ctx.user.id, + isRead: false, + }, + }) + }), + + /** + * Get recent notifications + */ + getRecent: protectedProcedure + .input(z.object({ limit: z.number().default(10) })) + .query(async ({ ctx, input }) => { + return ctx.prisma.inAppNotification.findMany({ + where: { userId: ctx.user.id }, + orderBy: { createdAt: 'desc' }, + take: input.limit, + }) + }), + + /** + * Get all notifications with filtering + */ + getAll: protectedProcedure + .input( + z.object({ + filter: z.enum(['all', 'unread']).default('all'), + limit: z.number().default(100), + offset: z.number().default(0), + }) + ) + .query(async ({ ctx, input }) => { + return ctx.prisma.inAppNotification.findMany({ + where: { + userId: ctx.user.id, + ...(input.filter === 'unread' && { isRead: false }), + }, + orderBy: { createdAt: 'desc' }, + take: input.limit, + skip: input.offset, + }) + }), + + /** + * Mark notification as read + */ + markRead: protectedProcedure + .input(z.object({ id: z.string() })) + .mutation(async ({ ctx, input }) => { + return ctx.prisma.inAppNotification.update({ + where: { id: input.id, userId: ctx.user.id }, + data: { isRead: true, readAt: new Date() }, + }) + }), + + /** + * Mark all notifications as read + */ + markAllRead: protectedProcedure.mutation(async ({ ctx }) => { + return ctx.prisma.inAppNotification.updateMany({ + where: { userId: ctx.user.id, isRead: false }, + data: { isRead: true, readAt: new Date() }, + }) + }), + + /** + * Delete notification + */ + delete: protectedProcedure + .input(z.object({ id: z.string() })) + .mutation(async ({ ctx, input }) => { + return ctx.prisma.inAppNotification.delete({ + where: { id: input.id, userId: ctx.user.id }, + }) + }), + + /** + * Get notification policies (admin) + */ + listPolicies: adminProcedure.query(async ({ ctx }) => { + return ctx.prisma.notificationPolicy.findMany({ + orderBy: { eventType: 'asc' }, + }) + }), + + /** + * Update notification policy (admin) + */ + updatePolicy: adminProcedure + .input( + z.object({ + id: z.string(), + channel: z.enum(['EMAIL', 'IN_APP', 'BOTH', 'NONE']).optional(), + isActive: z.boolean().optional(), + templateId: z.string().optional(), + configJson: z.record(z.unknown()).optional(), + }) + ) + .mutation(async ({ ctx, input }) => { + const { id, ...data } = input + + const policy = await ctx.prisma.notificationPolicy.update({ + where: { id }, + data, + }) + + await logAudit({ + prisma: ctx.prisma, + userId: ctx.user.id, + action: 'UPDATE_NOTIFICATION_POLICY', + entityType: 'NotificationPolicy', + entityId: id, + detailsJson: data, + ipAddress: ctx.ip, + userAgent: ctx.userAgent, + }) + + return policy + }), + + /** + * Send manual notification (admin) + */ + sendManual: adminProcedure + .input( + z.object({ + userIds: z.array(z.string()), + subject: z.string(), + message: z.string(), + linkUrl: z.string().optional(), + priority: z.enum(['low', 'normal', 'high', 'urgent']).default('normal'), + channels: z.array(z.enum(['EMAIL', 'IN_APP'])), + }) + ) + .mutation(async ({ ctx, input }) => { + const { userIds, channels, ...notificationData } = input + + // Create in-app notifications + if (channels.includes('IN_APP')) { + await ctx.prisma.inAppNotification.createMany({ + data: userIds.map((userId) => ({ + userId, + type: 'admin.manual_broadcast', + title: notificationData.subject, + message: notificationData.message, + linkUrl: notificationData.linkUrl, + priority: notificationData.priority, + icon: 'Bell', + })), + }) + } + + // Send emails + if (channels.includes('EMAIL')) { + const users = await ctx.prisma.user.findMany({ + where: { id: { in: userIds } }, + select: { id: true, email: true, name: true }, + }) + + const { sendNotificationEmail } = await import('@/lib/email') + + for (const user of users) { + try { + await sendNotificationEmail({ + to: user.email, + name: user.name || '', + subject: notificationData.subject, + template: 'admin-manual-notification', + variables: { + name: user.name, + message: notificationData.message, + linkUrl: notificationData.linkUrl, + }, + priority: notificationData.priority, + }) + } catch (error) { + console.error(`Failed to send email to ${user.email}:`, error) + } + } + } + + // Audit log + await logAudit({ + prisma: ctx.prisma, + userId: ctx.user.id, + action: 'SEND_MANUAL_NOTIFICATION', + entityType: 'InAppNotification', + detailsJson: { + recipientCount: userIds.length, + channels, + subject: notificationData.subject, + }, + ipAddress: ctx.ip, + userAgent: ctx.userAgent, + }) + + return { sent: userIds.length } + }), + + /** + * Get notification log (admin) + */ + getLog: adminProcedure + .input( + z.object({ + startDate: z.date().optional(), + endDate: z.date().optional(), + channel: z.enum(['EMAIL', 'IN_APP', 'ALL']).default('ALL'), + status: z.enum(['SENT', 'FAILED', 'ALL']).default('ALL'), + limit: z.number().default(100), + offset: z.number().default(0), + }) + ) + .query(async ({ ctx, input }) => { + return ctx.prisma.notificationLog.findMany({ + where: { + ...(input.startDate && { createdAt: { gte: input.startDate } }), + ...(input.endDate && { createdAt: { lte: input.endDate } }), + ...(input.channel !== 'ALL' && { channel: input.channel }), + ...(input.status !== 'ALL' && { status: input.status }), + }, + include: { + user: { select: { id: true, name: true, email: true } }, + }, + orderBy: { createdAt: 'desc' }, + take: input.limit, + skip: input.offset, + }) + }), +}) +``` + +### Deadline Router + +**Deadline management router:** +```typescript +// src/server/routers/deadline.ts +import { z } from 'zod' +import { router, adminProcedure } from '../trpc' +import { logAudit } from '../utils/audit' +import { emitRoundEvent } from '../services/round-notifications' + +export const deadlineRouter = router({ + /** + * Extend round deadline (affects all participants) + */ + extendRound: adminProcedure + .input( + z.object({ + roundId: z.string(), + newWindowCloseAt: z.date(), + reason: z.string(), + notifyParticipants: z.boolean().default(true), + }) + ) + .mutation(async ({ ctx, input }) => { + const round = await ctx.prisma.round.update({ + where: { id: input.roundId }, + data: { windowCloseAt: input.newWindowCloseAt }, + include: { + competition: true, + juryGroup: { include: { members: true } }, + }, + }) + + // Create override action + await ctx.prisma.overrideAction.create({ + data: { + entityType: 'Round', + entityId: input.roundId, + previousValue: { windowCloseAt: round.windowCloseAt }, + newValueJson: { windowCloseAt: input.newWindowCloseAt }, + reasonCode: 'ADMIN_DISCRETION', + reasonText: input.reason, + actorId: ctx.user.id, + }, + }) + + // Emit event + await emitRoundEvent( + 'admin.deadline_extended', + 'Round', + input.roundId, + ctx.user.id, + { + roundId: input.roundId, + previousDeadline: round.windowCloseAt, + newDeadline: input.newWindowCloseAt, + reason: input.reason, + }, + ctx.prisma + ) + + // Notify participants if requested + if (input.notifyParticipants) { + // Get affected users (jury members for this round) + const affectedUserIds = round.juryGroup?.members.map((m) => m.userId) || [] + + if (affectedUserIds.length > 0) { + await ctx.prisma.inAppNotification.createMany({ + data: affectedUserIds.map((userId) => ({ + userId, + type: 'admin.deadline_extended', + title: 'Deadline Extended', + message: `The deadline for ${round.name} has been extended to ${input.newWindowCloseAt.toLocaleString()}. Reason: ${input.reason}`, + linkUrl: `/jury/rounds/${input.roundId}`, + priority: 'high', + icon: 'Clock', + })), + }) + } + } + + // Audit log + await logAudit({ + prisma: ctx.prisma, + userId: ctx.user.id, + action: 'EXTEND_ROUND_DEADLINE', + entityType: 'Round', + entityId: input.roundId, + detailsJson: { + previousDeadline: round.windowCloseAt?.toISOString(), + newDeadline: input.newWindowCloseAt.toISOString(), + reason: input.reason, + notified: input.notifyParticipants, + }, + ipAddress: ctx.ip, + userAgent: ctx.userAgent, + }) + + return round + }), + + /** + * Extend submission window deadline + */ + extendSubmissionWindow: adminProcedure + .input( + z.object({ + windowId: z.string(), + newWindowCloseAt: z.date(), + reason: z.string(), + notifyApplicants: z.boolean().default(true), + }) + ) + .mutation(async ({ ctx, input }) => { + const window = await ctx.prisma.submissionWindow.update({ + where: { id: input.windowId }, + data: { windowCloseAt: input.newWindowCloseAt }, + include: { + competition: true, + rounds: { + include: { + projectRoundStates: { + include: { + project: { + include: { submittedBy: true }, + }, + }, + }, + }, + }, + }, + }) + + // Notify affected applicants + if (input.notifyApplicants) { + const affectedUserIds = new Set() + + for (const round of window.rounds) { + for (const state of round.projectRoundStates) { + if (state.project.submittedByUserId) { + affectedUserIds.add(state.project.submittedByUserId) + } + } + } + + if (affectedUserIds.size > 0) { + await ctx.prisma.inAppNotification.createMany({ + data: Array.from(affectedUserIds).map((userId) => ({ + userId, + type: 'admin.deadline_extended', + title: 'Submission Deadline Extended', + message: `The submission deadline for ${window.name} has been extended to ${input.newWindowCloseAt.toLocaleString()}. Reason: ${input.reason}`, + linkUrl: `/applicant/submissions/${input.windowId}`, + priority: 'high', + icon: 'Clock', + })), + }) + } + } + + // Audit log + await logAudit({ + prisma: ctx.prisma, + userId: ctx.user.id, + action: 'EXTEND_SUBMISSION_DEADLINE', + entityType: 'SubmissionWindow', + entityId: input.windowId, + detailsJson: { + previousDeadline: window.windowCloseAt?.toISOString(), + newDeadline: input.newWindowCloseAt.toISOString(), + reason: input.reason, + }, + ipAddress: ctx.ip, + userAgent: ctx.userAgent, + }) + + return window + }), +}) +``` + +--- + +## Service Functions + +### Round Notifications Service + +**Complete service interface:** +```typescript +// src/server/services/round-notifications.ts +import type { PrismaClient } from '@prisma/client' + +/** + * Emit a round event with notification support. + */ +export async function emitRoundEvent( + eventType: string, + entityType: string, + entityId: string, + actorId: string, + details: Record, + prisma: PrismaClient +): Promise + +/** + * Convenience producers for common events. + */ +export async function onRoundOpened( + roundId: string, + actorId: string, + prisma: PrismaClient +): Promise + +export async function onRoundClosed( + roundId: string, + actorId: string, + prisma: PrismaClient +): Promise + +export async function onSubmissionReceived( + projectId: string, + submissionWindowId: string, + submittedByUserId: string, + fileCount: number, + isComplete: boolean, + prisma: PrismaClient +): Promise + +export async function onFilteringCompleted( + jobId: string, + roundId: string, + total: number, + passed: number, + rejected: number, + flagged: number, + actorId: string, + prisma: PrismaClient +): Promise + +export async function onAssignmentCreated( + assignmentId: string, + roundId: string, + projectId: string, + userId: string, + actorId: string, + prisma: PrismaClient +): Promise + +export async function onMentorFileUploaded( + fileId: string, + mentorAssignmentId: string, + uploadedByUserId: string, + prisma: PrismaClient +): Promise + +export async function onWinnerApprovalRequired( + proposalId: string, + category: string, + requiredApprovers: Array<{ userId: string; role: string }>, + actorId: string, + prisma: PrismaClient +): Promise + +export async function onResultsFrozen( + proposalId: string, + category: string, + frozenByUserId: string, + prisma: PrismaClient +): Promise +``` + +### Deadline Reminder Service + +**Service interface:** +```typescript +// src/server/services/deadline-reminders.ts +export interface ReminderResult { + sent: number + errors: number +} + +/** + * Process all deadline reminders (called by cron). + */ +export async function processDeadlineReminders(): Promise + +/** + * Process evaluation round reminders. + */ +export async function processEvaluationReminders( + now: Date +): Promise + +/** + * Process submission window reminders. + */ +export async function processSubmissionReminders( + now: Date +): Promise + +/** + * Send reminders for a specific round. + */ +export async function sendEvaluationReminders( + round: any, + reminderType: string, + now: Date +): Promise + +/** + * Send reminders for a specific submission window. + */ +export async function sendSubmissionReminders( + window: any, + reminderType: string, + now: Date +): Promise + +/** + * Determine which reminder types should fire. + */ +export function getReminderTypesForDeadline( + msUntilDeadline: number, + reminderDays: number[], + reminderHours: number[] +): string[] +``` + +--- + +## Edge Cases + +| Edge Case | Scenario | Handling | +|-----------|----------|----------| +| **Midnight deadline** | Round closes at 23:59:59, cron runs at 00:00 | Grace period calculations account for timezone. Use `<=` comparison for windowCloseAt. | +| **Clock drift** | Client clock is 5 minutes fast | Server-side time sync via `trpc.time.getServerTime()`. Countdown uses synced time. | +| **Duplicate reminders** | Cron runs twice (overlapping) | `ReminderLog` unique constraint prevents duplicates. Idempotent reminder sending. | +| **Grace period overlap** | User has grace period + round is extended | Use whichever deadline is later: `max(userGrace, round.windowCloseAt)`. | +| **Notification flood** | 100 users receive reminder at once | Batch email sending (max 50/min). Use queue for large batches. | +| **Timezone confusion** | User in PST, server in UTC | All deadlines stored in UTC. Display in user's timezone (future enhancement). | +| **Email delivery failure** | SMTP server down | Retry 3 times with exponential backoff. Log failure in `NotificationLog`. In-app notification still created. | +| **Cron secret leak** | CRON_SECRET exposed | Rotate immediately. Use header validation. Log all cron requests. | +| **Reminder after deadline** | Cron delayed, now > deadline | Skip reminder. No reminders sent after deadline passes. | +| **User opts out of emails** | User sets `notificationPreference: NONE` | Respect preference. Still create in-app notifications. | +| **Template variable missing** | Template uses {{foo}} but data has no foo | Replace with empty string. Log warning. Don't fail email send. | +| **Round extended mid-reminder** | Deadline extended after 3d reminder sent | 1d reminder will still fire (based on new deadline). No duplicate 3d reminder. | +| **Bulk notification failure** | 1 out of 50 emails fails | Log failure, continue with remaining. Return `{ sent: 49, errors: 1 }`. | + +--- + +## Integration Points + +### How Notifications Connect to Every Round Type + +**INTAKE Round:** +- `intake.window_opened` → Triggered when round status changes to ACTIVE +- `intake.submission_received` → Triggered by `ProjectFile.create()` via `trpc.application.uploadFile` +- `intake.deadline_approaching` → Triggered by cron checking `SubmissionWindow.windowCloseAt` +- Email sent to: All applicants (window opened), team lead (submission received), incomplete applicants (deadline reminder) + +**FILTERING Round:** +- `filtering.started` → Triggered by `trpc.filtering.runStageFiltering` creating `FilteringJob` +- `filtering.completed` → Triggered when `FilteringJob.status → COMPLETED` +- `filtering.project_advanced` → Triggered when `ProjectRoundState.state → PASSED` +- `filtering.project_rejected` → Triggered when `ProjectRoundState.state → REJECTED` +- Email sent to: Admins (started/completed), team lead (advanced/rejected) + +**EVALUATION Round:** +- `evaluation.assignment_created` → Triggered by `trpc.assignment.create` or AI assignment +- `evaluation.deadline_approaching` → Triggered by cron checking `Round.windowCloseAt` +- `evaluation.submitted` → Triggered when `Evaluation.status → SUBMITTED` +- `evaluation.round_complete` → Triggered when all assignments completed +- Email sent to: Assigned juror (created, deadline), admins (round complete) + +**SUBMISSION Round:** +- `submission.window_opened` → Triggered when SubmissionWindow opens + round ACTIVE +- `submission.new_docs_required` → Triggered when eligible projects enter round +- `submission.docs_submitted` → Triggered by `ProjectFile.create()` for window +- `submission.deadline_approaching` → Triggered by cron +- Email sent to: Eligible teams (window opened, new docs), team lead (submitted, deadline) + +**MENTORING Round:** +- `mentoring.assigned` → Triggered by `MentorAssignment.create()` +- `mentoring.workspace_opened` → Triggered when round ACTIVE +- `mentoring.message_received` → Triggered by `MentorMessage.create()` +- `mentoring.file_uploaded` → Triggered by `MentorFile.create()` +- `mentoring.file_promoted` → Triggered when `MentorFile.isPromoted → true` +- Email sent to: Mentor + team (assigned, workspace), recipient (message), other party (file) + +**LIVE_FINAL Round:** +- `live_final.ceremony_starting` → Triggered when `LiveVotingSession.status → IN_PROGRESS` +- `live_final.vote_required` → Triggered when `LiveProgressCursor` updated +- `live_final.deliberation_started` → Triggered when deliberation period begins +- `live_final.results_ready` → Triggered when all votes cast +- Email sent to: Jury + audience (ceremony starting), jury (vote required), admins (results ready) +- In-app only: Real-time vote required notifications + +**CONFIRMATION Round:** +- `confirmation.approval_required` → Triggered by `WinnerProposal.create()` +- `confirmation.approval_received` → Triggered when `WinnerApproval.approved → true` +- `confirmation.approved` → Triggered when all approvals received +- `confirmation.frozen` → Triggered when `WinnerProposal.frozenAt` set +- Email sent to: Jury + admins (approval required), admins + jury (approved, frozen) + +### Cross-Round Notification Scenarios + +**Scenario 1: Project advances from Filtering to Evaluation** +1. `FilteringJob` completes → `filtering.completed` (admin email) +2. Admin reviews flagged projects → Manual override +3. `ProjectRoundState.state → PASSED` → `filtering.project_advanced` (team email) +4. Admin clicks "Advance to Evaluation" → Projects moved to Evaluation round +5. `Round.status → ACTIVE` for Evaluation round → `round.opened` (admin in-app) +6. AI assignment runs → Creates assignments +7. `Assignment.create()` → `evaluation.assignment_created` (each juror email) + +**Scenario 2: Deadline approaching with grace periods** +1. Cron runs 3 days before deadline +2. Finds 5 jurors with incomplete evaluations +3. Checks `ReminderLog` — 2 already received "3d" reminder +4. Checks `GracePeriod` — 1 juror has extended deadline (no reminder) +5. Sends "3d" reminder to 2 jurors +6. Creates `ReminderLog` entries for those 2 +7. Emits `evaluation.deadline_approaching` event +8. Creates in-app notifications for all 5 jurors (including grace period) + +**Scenario 3: Round deadline extended mid-cycle** +1. Admin extends deadline from March 15 to March 20 +2. `Round.windowCloseAt` updated +3. `admin.deadline_extended` event emitted +4. In-app + email notifications sent to all assigned jurors +5. Existing `ReminderLog` entries remain (prevent duplicate "7d", "3d") +6. New reminders fire based on new deadline: + - If extension happens after "3d" reminder: "1d" and "24h" reminders still fire + - If extension happens before "3d" reminder: All reminders fire normally + +--- + +## Summary + +This Notifications & Deadlines system provides: + +1. **Event-driven architecture** — All significant round events trigger notifications +2. **Multi-channel delivery** — Email, in-app, and future webhook support +3. **Flexible deadline policies** — HARD, FLAG, GRACE modes per window/round +4. **Automated reminders** — Configurable intervals (days and hours) before deadlines +5. **Grace period management** — Individual and bulk extensions with audit trail +6. **Real-time countdowns** — Client-side timers with server time sync +7. **Admin controls** — Competition-wide and per-round configuration +8. **Template system** — Reusable email templates with variable substitution +9. **Deduplication** — Unique constraints prevent duplicate reminders +10. **Integration** — Deep connections to all round types and pipeline events + +This system ensures participants are always informed, deadlines are clear, and admins have full control over notification behavior across the entire competition lifecycle. diff --git a/docs/claude-architecture-redesign/14-ai-services.md b/docs/claude-architecture-redesign/14-ai-services.md new file mode 100644 index 0000000..89a5aff --- /dev/null +++ b/docs/claude-architecture-redesign/14-ai-services.md @@ -0,0 +1,3384 @@ +# AI Services Architecture + +## Overview + +AI services power automation across all round types in the MOPC platform. All AI calls anonymize data before sending to OpenAI, ensuring GDPR compliance and privacy protection. These services enable intelligent filtering, smart jury assignments, evaluation synthesis, automatic tagging, and award eligibility assessment. + +### Core Principles + +1. **Privacy First**: All data is anonymized before AI processing (no PII sent to OpenAI) +2. **Graceful Degradation**: Fallback algorithms when AI is unavailable +3. **Cost Awareness**: Batching, token tracking, and cost monitoring +4. **Audit Trail**: All AI requests logged with inputs, outputs, and token usage +5. **Admin Control**: Per-service toggles, configuration overrides, manual review +6. **Transparency**: AI reasoning exposed to admins for validation + +### Service Inventory + +| Service | Purpose | Primary Model | Input Data | Output | +|---------|---------|---------------|------------|--------| +| **ai-filtering.ts** | Automated project screening | GPT-4 | Projects + rubric | Pass/Reject/Flag + scores | +| **ai-assignment.ts** | Jury-project matching | GPT-4 | Jurors + projects + constraints | Assignment suggestions | +| **ai-evaluation-summary.ts** | Synthesis of evaluations | GPT-4-turbo | All evaluations for a project | Strengths, weaknesses, themes | +| **ai-tagging.ts** | Auto-tag projects | GPT-4 | Project description | Tag suggestions + confidence | +| **ai-award-eligibility.ts** | Award eligibility assessment | GPT-4 | Projects + award criteria | Eligibility scores + reasoning | +| **anonymization.ts** | PII stripping pipeline | N/A | Raw project/user data | Anonymized data + mappings | + +--- + +## Current AI Services + +### 1. AI Filtering Service (`ai-filtering.ts`) + +**Purpose**: Automate project screening in Round 2 (FILTERING) using admin-defined rubrics and AI interpretation of plain-language criteria. + +#### Input Data + +```typescript +interface ProjectForFiltering { + id: string + title: string + description?: string | null + competitionCategory?: CompetitionCategory | null + foundedAt?: Date | null + country?: string | null + geographicZone?: string | null + tags: string[] + oceanIssue?: OceanIssue | null + wantsMentorship?: boolean | null + institution?: string | null + submissionSource?: SubmissionSource + submittedAt?: Date | null + files: Array<{ + id: string + fileName: string + fileType?: FileType | null + }> + _count?: { + teamMembers?: number + files?: number + } +} + +interface FilteringRuleInput { + id: string + name: string + ruleType: 'FIELD_BASED' | 'DOCUMENT_CHECK' | 'AI_SCREENING' + configJson: Prisma.JsonValue + priority: number + isActive: boolean +} +``` + +#### Rule Types + +**Field-Based Rules** (No AI): +```typescript +type FieldRuleConfig = { + conditions: FieldRuleCondition[] + logic: 'AND' | 'OR' + action: 'PASS' | 'REJECT' | 'FLAG' +} + +type FieldRuleCondition = { + field: 'competitionCategory' | 'foundedAt' | 'country' | 'geographicZone' | 'tags' | 'oceanIssue' + operator: 'equals' | 'not_equals' | 'greater_than' | 'less_than' | 'contains' | 'in' | 'not_in' | 'older_than_years' | 'newer_than_years' | 'is_empty' + value: string | number | string[] +} + +// Example: Reject projects older than 10 years +{ + conditions: [ + { field: 'foundedAt', operator: 'older_than_years', value: 10 } + ], + logic: 'AND', + action: 'REJECT' +} + +// Example: Flag projects from specific countries +{ + conditions: [ + { field: 'country', operator: 'in', value: ['US', 'CN', 'RU'] } + ], + logic: 'OR', + action: 'FLAG' +} +``` + +**Document Check Rules** (No AI): +```typescript +type DocumentCheckConfig = { + requiredFileTypes?: string[] // ['pdf', 'docx'] + minFileCount?: number + action: 'PASS' | 'REJECT' | 'FLAG' +} + +// Example: Require at least 2 PDF files +{ + requiredFileTypes: ['pdf'], + minFileCount: 2, + action: 'REJECT' +} +``` + +**AI Screening Rules** (OpenAI): +```typescript +type AIScreeningConfig = { + criteriaText: string // Plain-language rubric + action: 'PASS' | 'REJECT' | 'FLAG' + batchSize?: number // 1-50, default 20 + parallelBatches?: number // 1-10, default 1 +} + +// Example: Detect spam/low-quality projects +{ + criteriaText: ` + Projects should demonstrate clear ocean conservation value. + Reject projects that: + - Are spam, test submissions, or joke entries + - Have no meaningful description + - Are unrelated to ocean conservation + - Are duplicate submissions + `, + action: 'REJECT', + batchSize: 20, + parallelBatches: 2 +} +``` + +#### AI Screening Process + +1. **Anonymization**: Strip PII from projects + ```typescript + const { anonymized, mappings } = anonymizeProjectsForAI(projects, 'FILTERING') + + // Before: { id: "proj-abc123", title: "SaveTheSea by John Doe (john@example.com)", ... } + // After: { project_id: "P1", title: "SaveTheSea by Team 1", ... } + ``` + +2. **Validation**: Ensure no PII leaked + ```typescript + if (!validateAnonymizedProjects(anonymized)) { + throw new Error('GDPR compliance check failed') + } + ``` + +3. **Batch Processing**: Process projects in configurable batches + ```typescript + const batchSize = Math.min(MAX_BATCH_SIZE, config.batchSize ?? 20) + const parallelBatches = Math.min(MAX_PARALLEL_BATCHES, config.parallelBatches ?? 1) + + for (let i = 0; i < batches.length; i += parallelBatches) { + const parallelChunk = batches.slice(i, i + parallelBatches) + const results = await Promise.all(parallelChunk.map(processAIBatch)) + } + ``` + +4. **OpenAI Call**: Send anonymized batch with criteria + ```typescript + const prompt = `CRITERIA: ${criteriaText} + PROJECTS: ${JSON.stringify(anonymized)} + Evaluate and return JSON.` + + const response = await openai.chat.completions.create({ + model: 'gpt-4', + messages: [ + { role: 'system', content: AI_SCREENING_SYSTEM_PROMPT }, + { role: 'user', content: prompt } + ], + response_format: { type: 'json_object' }, + temperature: 0.3 + }) + ``` + +5. **Result Parsing**: + ```typescript + interface AIScreeningResult { + meetsCriteria: boolean + confidence: number // 0.0 - 1.0 + reasoning: string + qualityScore: number // 1-10 + spamRisk: boolean + } + + // AI returns: + { + "projects": [ + { + "project_id": "P1", + "meets_criteria": true, + "confidence": 0.85, + "reasoning": "Clear ocean conservation focus, well-documented approach", + "quality_score": 8, + "spam_risk": false + } + ] + } + ``` + +6. **De-anonymization**: Map results back to real IDs + ```typescript + const mapping = mappings.find(m => m.anonymousId === "P1") + results.set(mapping.realId, aiResult) + ``` + +#### Output + +```typescript +interface ProjectFilteringResult { + projectId: string + outcome: 'PASSED' | 'FILTERED_OUT' | 'FLAGGED' + ruleResults: RuleResult[] + aiScreeningJson?: { + [ruleId: string]: AIScreeningResult + } +} + +interface RuleResult { + ruleId: string + ruleName: string + ruleType: string + passed: boolean + action: 'PASS' | 'REJECT' | 'FLAG' + reasoning?: string // Only for AI_SCREENING +} +``` + +**Outcome Logic**: +- If ANY rule with `action: 'REJECT'` fails → `FILTERED_OUT` +- Else if ANY rule with `action: 'FLAG'` fails → `FLAGGED` +- Else → `PASSED` + +#### Integration with Filtering Round + +```typescript +// Round 2: FILTERING +const filteringRound = await prisma.round.findFirst({ + where: { competitionId, roundType: 'FILTERING' } +}) + +const rules = await prisma.filteringRule.findMany({ + where: { roundId: filteringRound.id, isActive: true }, + orderBy: { priority: 'asc' } +}) + +const projects = await prisma.project.findMany({ + where: { competitionId }, + include: { files: true, _count: { select: { teamMembers: true } } } +}) + +const results = await executeFilteringRules(rules, projects, userId, roundId) + +// Store results +for (const result of results) { + await prisma.filteringResult.create({ + data: { + projectId: result.projectId, + roundId: filteringRound.id, + outcome: result.outcome, + ruleResultsJson: result.ruleResults, + aiScreeningJson: result.aiScreeningJson + } + }) + + // Update project round state + await prisma.projectRoundState.update({ + where: { projectId_roundId: { projectId: result.projectId, roundId: filteringRound.id } }, + data: { + state: result.outcome === 'PASSED' ? 'PASSED' : 'REJECTED', + metadataJson: { filteringOutcome: result.outcome } + } + }) +} +``` + +--- + +### 2. AI Assignment Service (`ai-assignment.ts`) + +**Purpose**: Generate optimal jury-to-project assignments based on expertise matching, workload balancing, and constraints. + +#### Input Data + +```typescript +interface JurorForAssignment { + id: string + name?: string | null + email: string + expertiseTags: string[] + maxAssignments?: number | null + _count?: { + assignments: number + } +} + +interface ProjectForAssignment { + id: string + title: string + description?: string | null + tags: string[] + teamName?: string | null + _count?: { + assignments: number + } +} + +interface AssignmentConstraints { + requiredReviewsPerProject: number // e.g., 3 jurors per project + minAssignmentsPerJuror?: number // e.g., 5 projects minimum + maxAssignmentsPerJuror?: number // e.g., 20 projects maximum + jurorLimits?: Record // Per-juror overrides + existingAssignments: Array<{ + jurorId: string + projectId: string + }> +} +``` + +#### Anonymization & Batching + +```typescript +// 1. Truncate descriptions (save tokens) +const truncatedProjects = projects.map(p => ({ + ...p, + description: truncateAndSanitize(p.description, DESCRIPTION_LIMITS.ASSIGNMENT) // 300 chars +})) + +// 2. Anonymize data +const anonymizedData = anonymizeForAI(jurors, truncatedProjects) + +// Before: +jurors = [ + { id: "user-123", email: "john@example.com", expertiseTags: ["Marine Biology", "AI"] }, + { id: "user-456", email: "jane@example.com", expertiseTags: ["Oceanography"] } +] + +// After: +anonymizedData.jurors = [ + { anonymousId: "juror_001", expertiseTags: ["Marine Biology", "AI"], currentAssignmentCount: 5, maxAssignments: 20 }, + { anonymousId: "juror_002", expertiseTags: ["Oceanography"], currentAssignmentCount: 3, maxAssignments: 20 } +] + +// 3. Validate anonymization +if (!validateAnonymization(anonymizedData)) { + return generateFallbackAssignments(jurors, projects, constraints) +} + +// 4. Process in batches (15 projects per batch) +const BATCH_SIZE = 15 +for (let i = 0; i < projects.length; i += BATCH_SIZE) { + const batchProjects = anonymizedData.projects.slice(i, i + BATCH_SIZE) + const suggestions = await processAssignmentBatch(openai, model, anonymizedData, batchProjects, constraints) +} +``` + +#### Prompt Structure + +```typescript +const userPrompt = `JURORS: ${JSON.stringify(jurors)} +PROJECTS: ${JSON.stringify(projects)} +CONSTRAINTS: ${constraints.requiredReviewsPerProject} reviews/project, max ${constraints.maxAssignmentsPerJuror}/juror +EXISTING: ${JSON.stringify(anonymousExisting)} +Return JSON: {"assignments": [...]}` + +const systemPrompt = `Match jurors to projects by expertise. Return JSON assignments. +Each: {juror_id, project_id, confidence_score: 0-1, expertise_match_score: 0-1, reasoning: str (1-2 sentences)} +Distribute workload fairly. Avoid assigning jurors at capacity.` +``` + +**Example AI Response**: +```json +{ + "assignments": [ + { + "juror_id": "juror_001", + "project_id": "project_003", + "confidence_score": 0.92, + "expertise_match_score": 0.88, + "reasoning": "Strong match on Marine Biology and AI tags. Juror has capacity." + }, + { + "juror_id": "juror_002", + "project_id": "project_003", + "confidence_score": 0.75, + "expertise_match_score": 0.70, + "reasoning": "Oceanography expertise applies. Helps distribute workload." + } + ] +} +``` + +#### Output + +```typescript +interface AIAssignmentSuggestion { + jurorId: string // Real ID (de-anonymized) + projectId: string // Real ID (de-anonymized) + confidenceScore: number // 0-1 + expertiseMatchScore: number // 0-1 + reasoning: string +} + +interface AIAssignmentResult { + success: boolean + suggestions: AIAssignmentSuggestion[] + error?: string + tokensUsed?: number + fallbackUsed?: boolean +} +``` + +#### Fallback Algorithm + +When AI is unavailable or fails: + +```typescript +export function generateFallbackAssignments( + jurors: JurorForAssignment[], + projects: ProjectForAssignment[], + constraints: AssignmentConstraints +): AIAssignmentResult { + // Algorithm: + // 1. Sort projects by current assignment count (fewest first) + // 2. For each project, score all available jurors by: + // - Expertise match (50% weight): tag overlap + // - Load balancing (30% weight): current vs. max assignments + // - Under-min bonus (20% weight): jurors below minimum target + // 3. Assign top-scoring jurors + + const scoredJurors = jurors.map(juror => ({ + juror, + score: calculateExpertiseScore(juror.expertiseTags, project.tags) * 0.5 + + calculateLoadScore(currentLoad, maxLoad) * 0.3 + + calculateUnderMinBonus(currentLoad, minTarget) * 0.2 + })) + + // Assign top N jurors per project + const topN = scoredJurors.slice(0, neededReviews) + + return { + success: true, + suggestions: topN.map(s => ({ jurorId: s.juror.id, projectId, ... })), + fallbackUsed: true + } +} +``` + +**Expertise Score**: +```typescript +function calculateExpertiseScore(jurorTags: string[], projectTags: string[]): number { + const jurorTagsLower = new Set(jurorTags.map(t => t.toLowerCase())) + const matchingTags = projectTags.filter(t => jurorTagsLower.has(t.toLowerCase())) + + const matchRatio = matchingTags.length / projectTags.length + const hasExpertise = matchingTags.length > 0 ? 0.2 : 0 + + return Math.min(1, matchRatio * 0.8 + hasExpertise) +} +``` + +#### Integration with Evaluation Round + +```typescript +// Round 3/5: EVALUATION +const evaluationRound = await prisma.round.findFirst({ + where: { competitionId, roundType: 'EVALUATION', sortOrder: 3 } +}) + +const juryGroup = await prisma.juryGroup.findUnique({ + where: { id: evaluationRound.juryGroupId }, + include: { + members: { include: { user: true } } + } +}) + +const projects = await prisma.project.findMany({ + where: { + projectRoundStates: { + some: { + roundId: previousRoundId, + state: 'PASSED' + } + } + } +}) + +const constraints = { + requiredReviewsPerProject: 3, + maxAssignmentsPerJuror: 20, + jurorLimits: { + "user-123": 15, // Personal override + "user-456": 25 // Personal override + }, + existingAssignments: await prisma.assignment.findMany({ + where: { roundId: evaluationRound.id }, + select: { userId: true, projectId: true } + }) +} + +const result = await generateAIAssignments( + juryGroup.members.map(m => m.user), + projects, + constraints, + adminUserId, + evaluationRound.id, + onProgress +) + +// Admin reviews suggestions in UI, then applies +for (const suggestion of result.suggestions) { + await prisma.assignment.create({ + data: { + userId: suggestion.jurorId, + projectId: suggestion.projectId, + roundId: evaluationRound.id, + juryGroupId: juryGroup.id, + method: 'AI', + aiConfidenceScore: suggestion.confidenceScore, + expertiseMatchScore: suggestion.expertiseMatchScore, + aiReasoning: suggestion.reasoning + } + }) +} +``` + +--- + +### 3. AI Evaluation Summary Service (`ai-evaluation-summary.ts`) + +**Purpose**: Synthesize multiple juror evaluations for a project into a cohesive summary with strengths, weaknesses, themes, and consensus analysis. + +#### Input Data + +```typescript +interface EvaluationForSummary { + id: string + criterionScoresJson: Record | null + globalScore: number | null + binaryDecision: boolean | null + feedbackText: string | null + assignment: { + user: { + id: string + name: string | null + email: string + } + } +} + +interface CriterionDef { + id: string + label: string +} +``` + +#### Anonymization + +```typescript +// Strips juror identities, keeps only scores and sanitized feedback +export function anonymizeEvaluations( + evaluations: EvaluationForSummary[] +): AnonymizedEvaluation[] { + return evaluations.map(ev => ({ + criterionScores: ev.criterionScoresJson, + globalScore: ev.globalScore, + binaryDecision: ev.binaryDecision, + feedbackText: ev.feedbackText ? sanitizeText(ev.feedbackText) : null + })) +} + +// Before: +[ + { + id: "eval-123", + globalScore: 8, + feedbackText: "Strong proposal from john@example.com. Contact me at +1-555-1234.", + assignment: { user: { name: "John Doe", email: "john@example.com" } } + } +] + +// After: +[ + { + globalScore: 8, + feedbackText: "Strong proposal. Contact me at [phone removed].", + // No user info + } +] +``` + +#### Prompt Structure + +```typescript +const prompt = `You are analyzing jury evaluations for a project competition. + +PROJECT: "${sanitizedTitle}" + +EVALUATION CRITERIA: ${criteriaLabels.join(', ')} + +EVALUATIONS (${anonymizedEvaluations.length} total): +${JSON.stringify(anonymizedEvaluations, null, 2)} + +Analyze these evaluations and return a JSON object with this exact structure: +{ + "overallAssessment": "A 2-3 sentence summary of how the project was evaluated overall", + "strengths": ["strength 1", "strength 2", ...], + "weaknesses": ["weakness 1", "weakness 2", ...], + "themes": [ + { "theme": "theme name", "sentiment": "positive" | "negative" | "mixed", "frequency": } + ], + "recommendation": "A brief recommendation based on the evaluation consensus" +} + +Guidelines: +- Base your analysis only on the provided evaluation data +- Identify common themes across evaluator feedback +- Note areas of agreement and disagreement +- Keep the assessment objective and balanced +- Do not include any personal identifiers` +``` + +#### Scoring Patterns (Server-Side) + +In addition to AI analysis, the service computes statistical patterns: + +```typescript +interface ScoringPatterns { + averageGlobalScore: number | null + consensus: number // 0-1 (1 = full agreement) + criterionAverages: Record + evaluatorCount: number +} + +export function computeScoringPatterns( + evaluations: EvaluationForSummary[], + criteriaLabels: CriterionDef[] +): ScoringPatterns { + const globalScores = evaluations.map(e => e.globalScore).filter(s => s !== null) + + const averageGlobalScore = globalScores.length > 0 + ? globalScores.reduce((a, b) => a + b, 0) / globalScores.length + : null + + // Consensus: 1 - normalized standard deviation + let consensus = 1 + if (globalScores.length > 1 && averageGlobalScore !== null) { + const variance = globalScores.reduce((sum, score) => + sum + Math.pow(score - averageGlobalScore, 2), 0 + ) / globalScores.length + const stdDev = Math.sqrt(variance) + consensus = Math.max(0, 1 - stdDev / 4.5) // Normalize by max possible std dev + } + + // Criterion averages + const criterionAverages: Record = {} + for (const criterion of criteriaLabels) { + const scores = evaluations + .map(e => e.criterionScoresJson?.[criterion.id]) + .filter((s): s is number => s !== undefined) + if (scores.length > 0) { + criterionAverages[criterion.label] = scores.reduce((a, b) => a + b, 0) / scores.length + } + } + + return { + averageGlobalScore, + consensus: Math.round(consensus * 100) / 100, + criterionAverages, + evaluatorCount: evaluations.length + } +} +``` + +#### Output + +```typescript +interface AIResponsePayload { + overallAssessment: string + strengths: string[] + weaknesses: string[] + themes: Array<{ + theme: string + sentiment: 'positive' | 'negative' | 'mixed' + frequency: number + }> + recommendation: string +} + +interface EvaluationSummaryResult { + id: string + projectId: string + stageId: string + summaryJson: AIResponsePayload & { scoringPatterns: ScoringPatterns } + generatedAt: Date + model: string + tokensUsed: number +} +``` + +**Example Output**: +```json +{ + "overallAssessment": "The project received consistently high scores (avg: 8.2/10) with strong consensus (0.92). Evaluators praised the technical approach and team expertise, but raised concerns about scalability and budget.", + "strengths": [ + "Novel AI-powered coral monitoring approach", + "Strong technical team with relevant expertise", + "Clear commercial viability and market need" + ], + "weaknesses": [ + "Budget appears optimistic for proposed timeline", + "Limited discussion of regulatory compliance", + "Scalability challenges not fully addressed" + ], + "themes": [ + { "theme": "Technical Innovation", "sentiment": "positive", "frequency": 5 }, + { "theme": "Team Expertise", "sentiment": "positive", "frequency": 4 }, + { "theme": "Budget Concerns", "sentiment": "negative", "frequency": 3 }, + { "theme": "Scalability", "sentiment": "mixed", "frequency": 2 } + ], + "recommendation": "Strong candidate for advancement. Address budget and scalability concerns during mentoring phase.", + "scoringPatterns": { + "averageGlobalScore": 8.2, + "consensus": 0.92, + "criterionAverages": { + "Innovation": 8.8, + "Feasibility": 7.6, + "Impact": 8.4, + "Team": 9.0 + }, + "evaluatorCount": 5 + } +} +``` + +#### Integration with Evaluation Round + +```typescript +// Auto-trigger when all evaluations for a project are submitted +const evaluationsCount = await prisma.evaluation.count({ + where: { + status: 'SUBMITTED', + assignment: { projectId, roundId } + } +}) + +const requiredReviews = evaluationRound.configJson.requiredReviewsPerProject + +if (evaluationsCount >= requiredReviews) { + const summary = await generateSummary({ + projectId, + stageId: roundId, + userId: 'system', + prisma + }) + + // Notify admin + await prisma.inAppNotification.create({ + data: { + userId: adminId, + title: 'Evaluation Summary Generated', + message: `AI summary ready for project "${projectTitle}"`, + type: 'AI_SUMMARY_READY', + relatedEntityType: 'EvaluationSummary', + relatedEntityId: summary.id + } + }) +} +``` + +--- + +### 4. AI Tagging Service (`ai-tagging.ts`) + +**Purpose**: Automatically assign expertise tags to projects based on content analysis. + +#### Input Data + +```typescript +// Full project data with files and team info +const project = await prisma.project.findUnique({ + where: { id: projectId }, + include: { + projectTags: true, + files: { select: { fileType: true } }, + _count: { select: { teamMembers: true, files: true } } + } +}) + +// Available tags from system +interface AvailableTag { + id: string + name: string + category: string | null + description: string | null +} + +const availableTags = await prisma.expertiseTag.findMany({ + where: { isActive: true }, + orderBy: [{ category: 'asc' }, { sortOrder: 'asc' }] +}) +``` + +#### Anonymization + +```typescript +const projectWithRelations = toProjectWithRelations(project) +const { anonymized, mappings } = anonymizeProjectsForAI([projectWithRelations], 'FILTERING') + +// Anonymized project: +{ + project_id: "P1", + title: "SaveTheSea", + description: "An AI-powered platform for coral reef monitoring...", + category: "STARTUP", + ocean_issue: "CORAL_REEFS", + tags: ["AI", "Monitoring"], + founded_year: 2024, + team_size: 3, + file_count: 5, + file_types: ["PDF", "DOCX"] +} +``` + +#### Prompt Structure + +```typescript +const tagList = availableTags.map(t => ({ + name: t.name, + category: t.category, + description: t.description +})) + +const prompt = `PROJECT: +${JSON.stringify(anonymizedProject, null, 2)} + +AVAILABLE TAGS: +${JSON.stringify(tagList, null, 2)} + +Suggest relevant tags for this project.` + +const systemPrompt = `You are an expert at categorizing ocean conservation and sustainability projects. + +Analyze the project and suggest the most relevant expertise tags from the provided list. +Consider the project's focus areas, technology, methodology, and domain. + +Return JSON with this format: +{ + "suggestions": [ + { + "tag_name": "exact tag name from list", + "confidence": 0.0-1.0, + "reasoning": "brief explanation why this tag fits" + } + ] +} + +Rules: +- Only suggest tags from the provided list (exact names) +- Order by relevance (most relevant first) +- Confidence should reflect how well the tag matches +- Maximum 7 suggestions per project +- Be conservative - only suggest tags that truly apply` +``` + +#### Output + +```typescript +interface TagSuggestion { + tagId: string + tagName: string + confidence: number + reasoning: string +} + +interface TaggingResult { + projectId: string + suggestions: TagSuggestion[] + applied: TagSuggestion[] + tokensUsed: number +} +``` + +**Example Response**: +```json +{ + "suggestions": [ + { + "tag_name": "Marine Biology", + "confidence": 0.92, + "reasoning": "Project focuses on coral reef health monitoring" + }, + { + "tag_name": "Artificial Intelligence", + "confidence": 0.88, + "reasoning": "Uses AI for image analysis and pattern detection" + }, + { + "tag_name": "Data Science", + "confidence": 0.75, + "reasoning": "Significant data collection and analysis component" + } + ] +} +``` + +#### Application Logic + +```typescript +const CONFIDENCE_THRESHOLD = 0.5 +const MAX_TAGS = 5 + +// 1. Get AI suggestions +const { suggestions, tokensUsed } = await getAISuggestions(anonymized[0], availableTags, userId) + +// 2. Filter by confidence threshold +const validSuggestions = suggestions.filter(s => s.confidence >= CONFIDENCE_THRESHOLD) + +// 3. Get existing tags to avoid duplicates +const existingTagIds = new Set(project.projectTags.map(pt => pt.tagId)) + +// 4. Calculate remaining slots +const currentTagCount = project.projectTags.length +const remainingSlots = Math.max(0, MAX_TAGS - currentTagCount) + +// 5. Filter and limit +const newSuggestions = validSuggestions + .filter(s => !existingTagIds.has(s.tagId)) + .slice(0, remainingSlots) + +// 6. Apply new tags (additive only, never removes existing) +for (const suggestion of newSuggestions) { + await prisma.projectTag.create({ + data: { + projectId, + tagId: suggestion.tagId, + confidence: suggestion.confidence, + source: 'AI' + } + }) +} +``` + +#### Integration Points + +**On Project Submission** (Round 1: INTAKE): +```typescript +// Auto-tag when project is submitted +if (settings.ai_tagging_enabled && settings.ai_tagging_on_submit) { + await tagProject(projectId, userId) +} +``` + +**Manual Tagging** (Admin Dashboard): +```typescript +// Admin reviews suggestions before applying +const suggestions = await getTagSuggestions(projectId, userId) + +// UI shows suggestions with confidence scores +// Admin clicks "Apply All" or selectively adds tags +for (const suggestion of selectedSuggestions) { + await addProjectTag(projectId, suggestion.tagId) +} +``` + +**Batch Tagging** (Round Management): +```typescript +// Tag all projects in a round +const projects = await prisma.project.findMany({ + where: { competitionId } +}) + +for (const project of projects) { + try { + await tagProject(project.id, adminUserId) + } catch (error) { + console.error(`Failed to tag project ${project.id}:`, error) + } +} +``` + +--- + +### 5. AI Award Eligibility Service (`ai-award-eligibility.ts`) + +**Purpose**: Determine which projects are eligible for special awards using both deterministic field matching and AI interpretation of plain-language criteria. + +#### Input Data + +```typescript +interface ProjectForEligibility { + id: string + title: string + description?: string | null + competitionCategory?: CompetitionCategory | null + country?: string | null + geographicZone?: string | null + tags: string[] + oceanIssue?: OceanIssue | null + institution?: string | null + foundedAt?: Date | null + wantsMentorship?: boolean + submissionSource?: SubmissionSource + submittedAt?: Date | null + _count?: { + teamMembers?: number + files?: number + } + files?: Array<{ fileType: string | null }> +} + +interface SpecialAward { + id: string + name: string + description?: string | null + criteriaText?: string | null // Plain-language criteria for AI + eligibilityMode: 'STAY_IN_MAIN' | 'SEPARATE_POOL' + useAiEligibility: boolean +} +``` + +#### Deterministic Auto-Tag Rules + +```typescript +type AutoTagRule = { + field: 'competitionCategory' | 'country' | 'geographicZone' | 'tags' | 'oceanIssue' + operator: 'equals' | 'contains' | 'in' + value: string | string[] +} + +// Example: "Innovation Award" for AI/ML projects +const innovationRules: AutoTagRule[] = [ + { + field: 'tags', + operator: 'contains', + value: 'Artificial Intelligence' + } +] + +// Example: "Regional Impact Award" for Mediterranean projects +const regionalRules: AutoTagRule[] = [ + { + field: 'geographicZone', + operator: 'equals', + value: 'MEDITERRANEAN' + } +] + +// Apply rules +export function applyAutoTagRules( + rules: AutoTagRule[], + projects: ProjectForEligibility[] +): Map { + const results = new Map() + + for (const project of projects) { + const matches = rules.every(rule => { + const fieldValue = getFieldValue(project, rule.field) + // ... operator logic ... + }) + results.set(project.id, matches) + } + + return results +} +``` + +#### AI Criteria Interpretation + +```typescript +// Award with plain-language criteria +const award = { + name: "Youth Innovation Award", + criteriaText: ` + Projects eligible for this award should: + - Be founded within the last 3 years + - Have a team with average age under 30 + - Demonstrate novel technological approach + - Show strong potential for scalability + `, + useAiEligibility: true +} + +// Anonymize and batch process +const { anonymized, mappings } = anonymizeProjectsForAI(projects, 'ELIGIBILITY') + +const prompt = `CRITERIA: ${criteriaText} +PROJECTS: ${JSON.stringify(anonymized)} +Evaluate eligibility for each project.` + +const systemPrompt = `Award eligibility evaluator. Evaluate projects against criteria, return JSON. +Format: {"evaluations": [{project_id, eligible: bool, confidence: 0-1, reasoning: str}]} +Be objective. Base evaluation only on provided data. No personal identifiers in reasoning.` +``` + +#### Output + +```typescript +interface EligibilityResult { + projectId: string + eligible: boolean + confidence: number + reasoning: string + method: 'AUTO' | 'AI' +} + +// Example AI response: +{ + "evaluations": [ + { + "project_id": "P1", + "eligible": true, + "confidence": 0.85, + "reasoning": "Founded in 2024 (within 3 years). Novel AI approach for coral monitoring. High scalability potential." + }, + { + "project_id": "P2", + "eligible": false, + "confidence": 0.90, + "reasoning": "Founded in 2015 (over 3 years ago). Does not meet youth criteria." + } + ] +} +``` + +#### Integration with Special Awards + +```typescript +// Run eligibility check for an award +const award = await prisma.specialAward.findUnique({ + where: { id: awardId }, + include: { competition: true } +}) + +const projects = await prisma.project.findMany({ + where: { competitionId: award.competitionId }, + include: { files: true, _count: { select: { teamMembers: true } } } +}) + +let eligibilityResults: EligibilityResult[] = [] + +if (award.useAiEligibility && award.criteriaText) { + // AI interpretation + eligibilityResults = await aiInterpretCriteria( + award.criteriaText, + projects, + userId, + awardId + ) +} else if (award.autoTagRules) { + // Deterministic rules + const matches = applyAutoTagRules(award.autoTagRules, projects) + eligibilityResults = Array.from(matches).map(([projectId, eligible]) => ({ + projectId, + eligible, + confidence: 1.0, + reasoning: 'Matches auto-tag rules', + method: 'AUTO' + })) +} + +// Store results +for (const result of eligibilityResults) { + await prisma.awardEligibility.upsert({ + where: { + specialAwardId_projectId: { specialAwardId: awardId, projectId: result.projectId } + }, + create: { + specialAwardId: awardId, + projectId: result.projectId, + isEligible: result.eligible, + confidence: result.confidence, + reasoning: result.reasoning, + method: result.method + }, + update: { + isEligible: result.eligible, + confidence: result.confidence, + reasoning: result.reasoning, + method: result.method + } + }) +} +``` + +--- + +### 6. Anonymization Service (`anonymization.ts`) + +**Purpose**: Strip PII from all data before sending to OpenAI. Ensures GDPR compliance and privacy protection. + +#### PII Patterns Detected + +```typescript +const PII_PATTERNS = { + email: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, + phone: /(\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}/g, + url: /https?:\/\/[^\s]+/g, + ssn: /\d{3}-\d{2}-\d{4}/g, + ipv4: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g +} + +export function sanitizeText(text: string): string { + let sanitized = text + sanitized = sanitized.replace(PII_PATTERNS.email, '[email removed]') + sanitized = sanitized.replace(PII_PATTERNS.phone, '[phone removed]') + sanitized = sanitized.replace(PII_PATTERNS.url, '[url removed]') + sanitized = sanitized.replace(PII_PATTERNS.ssn, '[id removed]') + return sanitized +} +``` + +#### Description Truncation + +```typescript +export const DESCRIPTION_LIMITS = { + ASSIGNMENT: 300, // Short context for matching + FILTERING: 500, // Medium context for screening + ELIGIBILITY: 400, // Medium context for criteria + MENTOR: 350 // Short context for mentor matching +} + +export function truncateAndSanitize( + text: string | null | undefined, + maxLength: number +): string { + if (!text) return '' + const sanitized = sanitizeText(text) + if (sanitized.length <= maxLength) return sanitized + return sanitized.slice(0, maxLength - 3) + '...' +} +``` + +#### ID Replacement Strategy + +**Before Anonymization**: +```typescript +// Real data with identifiable IDs +{ + id: "proj-abc123xyz", + userId: "user-456def789", + title: "SaveTheSea by Marine Research Institute", + teamName: "Dr. John Doe's Lab", + description: "Contact us at john@example.com or +1-555-1234 for more info. Visit https://savethesea.org" +} +``` + +**After Anonymization**: +```typescript +// Anonymous IDs and sanitized text +{ + project_id: "P1", + title: "SaveTheSea", + description: "Contact us at [email removed] or [phone removed] for more info. Visit [url removed]", + team_size: 3, + founded_year: 2024, + tags: ["Marine Biology", "AI"] +} +``` + +**Mapping for De-anonymization**: +```typescript +const mappings: ProjectAIMapping[] = [ + { anonymousId: "P1", realId: "proj-abc123xyz" }, + { anonymousId: "P2", realId: "proj-def456uvw" } +] +``` + +#### GDPR Validation + +```typescript +export interface PIIValidationResult { + valid: boolean + violations: string[] +} + +export function validateNoPersonalData( + data: Record +): PIIValidationResult { + const violations: string[] = [] + const textContent = JSON.stringify(data) + + // Check PII patterns + for (const [type, pattern] of Object.entries(PII_PATTERNS)) { + pattern.lastIndex = 0 + if (pattern.test(textContent)) { + violations.push(`Potential ${type} detected in data`) + } + } + + // Check sensitive field names + const sensitiveFields = ['email', 'phone', 'password', 'ssn', 'creditCard', 'bankAccount'] + const keys = Object.keys(data).map(k => k.toLowerCase()) + for (const field of sensitiveFields) { + if (keys.includes(field)) { + violations.push(`Sensitive field "${field}" present in data`) + } + } + + return { + valid: violations.length === 0, + violations + } +} + +// Enforce before EVERY AI call +export function enforceGDPRCompliance(data: unknown[]): void { + for (let i = 0; i < data.length; i++) { + const { valid, violations } = validateNoPersonalData(item) + if (!valid) { + throw new Error(`GDPR compliance check failed: ${violations.join(', ')}`) + } + } +} +``` + +#### Anonymization Workflow + +```mermaid +graph TD + A[Raw Project Data] --> B[Convert to ProjectWithRelations] + B --> C[Truncate Descriptions] + C --> D[Sanitize Text Fields] + D --> E[Replace IDs with Anonymous IDs] + E --> F[Create Mappings] + F --> G[Validate No PII] + G --> H{Valid?} + H -->|Yes| I[Send to AI] + H -->|No| J[Throw GDPR Error] + I --> K[AI Response] + K --> L[De-anonymize Results] + L --> M[Return Real IDs] +``` + +--- + +## New AI Services for Redesign + +### 1. AI Mentoring Insights (Round 6: MENTORING) + +**Purpose**: Summarize mentor-team interactions, flag inactive workspaces, suggest intervention points. + +#### Input Data + +```typescript +interface MentorWorkspaceData { + projectId: string + mentorId: string + workspaceOpenAt: Date + files: MentorFile[] + messages: MentorMessage[] + fileComments: MentorFileComment[] + lastActivityAt: Date +} +``` + +#### Anonymization + +```typescript +// Strip mentor/team names, keep activity patterns +{ + workspace_id: "W1", + days_active: 14, + file_count: 3, + message_count: 12, + comment_count: 5, + last_activity_days_ago: 2, + file_types: ["PDF", "DOCX"], + message_frequency: "daily", + engagement_level: "high" +} +``` + +#### Prompt + +```typescript +const prompt = `Analyze mentor workspace activity and provide insights. + +WORKSPACE DATA: ${JSON.stringify(anonymizedWorkspace)} + +Return JSON: +{ + "engagement_level": "high" | "medium" | "low" | "inactive", + "key_insights": ["insight 1", "insight 2"], + "red_flags": ["flag 1", "flag 2"], + "recommendations": ["recommendation 1", "recommendation 2"], + "intervention_needed": boolean +}` +``` + +#### Output + +```typescript +interface MentoringInsight { + workspaceId: string + engagementLevel: 'high' | 'medium' | 'low' | 'inactive' + keyInsights: string[] + redFlags: string[] + recommendations: string[] + interventionNeeded: boolean +} +``` + +**Example**: +```json +{ + "engagement_level": "low", + "key_insights": [ + "No activity in last 7 days", + "Only 1 file uploaded (below average for this stage)", + "Message frequency dropped from daily to weekly" + ], + "red_flags": [ + "Mentor has not responded to last 2 team messages", + "No progress on business plan deliverable (due in 5 days)" + ], + "recommendations": [ + "Admin should check in with mentor", + "Send reminder notification to team about upcoming deadline", + "Consider pairing with secondary mentor for support" + ], + "intervention_needed": true +} +``` + +#### Integration + +```typescript +// Nightly cron job: analyze all active mentoring workspaces +const mentoringRound = await prisma.round.findFirst({ + where: { competitionId, roundType: 'MENTORING', status: 'ROUND_ACTIVE' } +}) + +const assignments = await prisma.mentorAssignment.findMany({ + where: { workspaceEnabled: true }, + include: { files: true, messages: true } +}) + +for (const assignment of assignments) { + const insight = await generateMentoringInsight(assignment, userId) + + if (insight.interventionNeeded) { + await prisma.inAppNotification.create({ + data: { + userId: adminId, + title: 'Mentoring Intervention Needed', + message: `Workspace for project "${projectTitle}" requires attention`, + type: 'MENTORING_ALERT', + actionUrl: `/admin/mentoring/${assignment.id}` + } + }) + } +} +``` + +--- + +### 2. AI Duplicate Detection Enhancement (Round 2: FILTERING) + +**Purpose**: Detect duplicate or near-duplicate submissions using embeddings and semantic similarity. + +#### Current Approach (Simple) + +```typescript +// Existing: basic title/email matching +const duplicates = await prisma.project.findMany({ + where: { + OR: [ + { title: { equals: project.title, mode: 'insensitive' } }, + { teamMembers: { some: { email: applicantEmail } } } + ] + } +}) +``` + +#### Enhanced Approach (AI-Powered) + +```typescript +// Generate embeddings for all projects +const embeddings = new Map() + +for (const project of projects) { + const embedding = await openai.embeddings.create({ + model: 'text-embedding-3-small', + input: `${project.title}\n\n${project.description}` + }) + embeddings.set(project.id, embedding.data[0].embedding) +} + +// Compute cosine similarity matrix +function cosineSimilarity(a: number[], b: number[]): number { + const dot = a.reduce((sum, val, i) => sum + val * b[i], 0) + const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0)) + const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0)) + return dot / (magA * magB) +} + +// Find duplicates +const SIMILARITY_THRESHOLD = 0.85 + +for (const [id1, emb1] of embeddings) { + for (const [id2, emb2] of embeddings) { + if (id1 >= id2) continue // Skip self and already compared + + const similarity = cosineSimilarity(emb1, emb2) + if (similarity >= SIMILARITY_THRESHOLD) { + await prisma.duplicateDetection.create({ + data: { + projectId1: id1, + projectId2: id2, + similarity, + method: 'AI_EMBEDDING', + status: 'FLAGGED' + } + }) + } + } +} +``` + +#### Output + +```typescript +interface DuplicateMatch { + projectId1: string + projectId2: string + similarity: number + method: 'EXACT_TITLE' | 'EMAIL_MATCH' | 'AI_EMBEDDING' + status: 'FLAGGED' | 'CONFIRMED_DUPLICATE' | 'FALSE_POSITIVE' +} +``` + +**Admin Review UI**: +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Duplicate Detection: 3 Potential Matches │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ [!] 92% Match - AI Coral Monitoring (P1) vs Ocean AI (P2) │ +│ Method: AI Embedding │ +│ ┌─ P1: SaveTheSea - AI-powered coral reef monitoring... │ +│ └─ P2: Ocean AI - Machine learning platform for coral... │ +│ │ +│ [ Mark as Duplicate ] [ False Positive ] [ View Details ] │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ [!] 88% Match - Marine Plastic (P3) vs PlasticClean (P4) │ +│ Method: AI Embedding + Email Match │ +│ ┌─ P3: Marine Plastic Cleanup - Robotic system... │ +│ └─ P4: PlasticClean - Automated plastic removal... │ +│ │ +│ [ Mark as Duplicate ] [ False Positive ] [ View Details ] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 3. AI Confirmation Helper (Round 8: CONFIRMATION) + +**Purpose**: Generate plain-language explanations for why final rankings are what they are. Helps jury understand and validate the winner proposal. + +#### Input Data + +```typescript +interface WinnerProposalData { + rankedProjectIds: string[] + sourceRoundId: string + selectionBasis: { + method: 'LIVE_VOTE' | 'EVALUATION_SCORES' | 'ADMIN_DECISION' + scores: Record + aiRecommendation?: string + } +} + +// Fetch all context +const projects = await prisma.project.findMany({ + where: { id: { in: proposal.rankedProjectIds } }, + include: { + evaluations: { where: { roundId: sourceRoundId } }, + liveVotes: { where: { roundId: sourceRoundId } } + } +}) +``` + +#### Anonymization + +```typescript +// Strip project names, keep relative rankings and scores +{ + ranking: [ + { position: 1, anonymous_id: "P1", score: 8.9, vote_count: 12 }, + { position: 2, anonymous_id: "P2", score: 8.5, vote_count: 10 }, + { position: 3, anonymous_id: "P3", score: 8.2, vote_count: 11 } + ], + selection_method: "LIVE_VOTE", + score_gaps: [0.4, 0.3], + consensus_level: 0.88 +} +``` + +#### Prompt + +```typescript +const prompt = `Explain the final ranking in plain language for jury review. + +RANKING DATA: ${JSON.stringify(anonymizedRanking)} + +EVALUATION HISTORY: ${JSON.stringify(anonymizedEvaluations)} + +Return JSON: +{ + "summary": "2-3 sentence plain-language summary of why this ranking makes sense", + "position_explanations": [ + { "position": 1, "why_this_rank": "explanation", "strengths": ["s1", "s2"] }, + ... + ], + "close_calls": [ + { "positions": [2, 3], "gap": 0.3, "reasoning": "why this was close" } + ], + "confidence": "high" | "medium" | "low", + "red_flags": ["flag 1", ...] +}` +``` + +#### Output + +```typescript +interface ConfirmationExplanation { + summary: string + positionExplanations: Array<{ + position: number + projectId: string + whyThisRank: string + strengths: string[] + }> + closeCalls: Array<{ + positions: number[] + gap: number + reasoning: string + }> + confidence: 'high' | 'medium' | 'low' + redFlags: string[] +} +``` + +**Example**: +```json +{ + "summary": "The ranking reflects clear consensus from both live voting (12 votes) and prior evaluations (avg 8.9). Top position is well-separated with 0.4 point gap. Second and third places are close (0.3 gap), but consistent across jury members.", + "position_explanations": [ + { + "position": 1, + "why_this_rank": "Highest average score (8.9) across all evaluation rounds. Won live vote with 12/15 jury members. Consistent top performer.", + "strengths": ["Technical innovation", "Strong team", "Commercial viability", "Scalability"] + }, + { + "position": 2, + "why_this_rank": "Strong runner-up (8.5 avg). Close to third place but slight edge in feasibility scores.", + "strengths": ["Proven track record", "Regulatory compliance", "Budget realism"] + }, + { + "position": 3, + "why_this_rank": "Solid finalist (8.2 avg). Slightly lower technical feasibility scores compared to #2.", + "strengths": ["Impact potential", "Novel approach", "Jury enthusiasm"] + } + ], + "close_calls": [ + { + "positions": [2, 3], + "gap": 0.3, + "reasoning": "Very close race. Position 2 had slight edge in 'Feasibility' criterion (7.8 vs 7.2), while Position 3 scored higher in 'Impact' (8.9 vs 8.4). Live vote split 10-11. Admin may want to review deliberation notes." + } + ], + "confidence": "high", + "red_flags": [] +} +``` + +**Integration**: +```typescript +// When admin creates WinnerProposal +const proposal = await prisma.winnerProposal.create({ + data: { + competitionId, + category: 'STARTUP', + rankedProjectIds: ['proj-1', 'proj-2', 'proj-3'], + sourceRoundId: liveFinalsRoundId, + selectionBasis: { method: 'LIVE_VOTE', scores: {...} }, + proposedById: adminId + } +}) + +// Generate AI explanation +const explanation = await generateConfirmationExplanation(proposal.id, userId) + +// Attach to proposal +await prisma.winnerProposal.update({ + where: { id: proposal.id }, + data: { + selectionBasis: { + ...proposal.selectionBasis, + aiExplanation: explanation + } + } +}) + +// Show to jury during confirmation +``` + +**Confirmation UI with AI Explanation**: +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Confirm Final Rankings: STARTUP Category │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ AI Analysis: High Confidence │ +│ "The ranking reflects clear consensus from both live voting │ +│ (12 votes) and prior evaluations (avg 8.9). Top position is │ +│ well-separated with 0.4 point gap..." │ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ 1st Place: SaveTheSea (Score: 8.9, 12 votes) │ │ +│ │ Why This Rank: Highest average score across all rounds... │ │ +│ │ Strengths: Technical innovation, Strong team, Commercial... │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ 2nd Place: Ocean AI (Score: 8.5, 10 votes) │ │ +│ │ Why This Rank: Strong runner-up. Close to third place... │ │ +│ │ Strengths: Proven track record, Regulatory compliance... │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ [!] Close Call: 2nd and 3rd place (0.3 gap) │ +│ Position 2 had slight edge in Feasibility (7.8 vs 7.2)... │ +│ │ +│ [ ] I confirm this ranking (John Doe, Jury Lead) │ +│ [ ] I confirm this ranking (Jane Smith, Jury Member) │ +│ [ ] I confirm this ranking (Bob Wilson, Jury Member) │ +│ │ +│ Comments: ___________________________________________________ │ +│ │ +│ [ Approve Ranking ] [ Request Changes ] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Anonymization Pipeline (Deep Dive) + +### Data Flow + +```mermaid +graph LR + A[Raw Data] --> B[Type Conversion] + B --> C[Description Truncation] + C --> D[Text Sanitization] + D --> E[ID Replacement] + E --> F[Field Filtering] + F --> G[Validation] + G --> H{GDPR Pass?} + H -->|Yes| I[To AI] + H -->|No| J[Error + Log] + I --> K[AI Response] + K --> L[De-anonymization] + L --> M[Real Results] +``` + +### What Gets Stripped + +| Data Type | Before | After | +|-----------|--------|-------| +| **User IDs** | `user-abc123xyz` | `juror_001` | +| **Project IDs** | `proj-def456uvw` | `P1` | +| **Names** | `Dr. John Doe` | (removed entirely) | +| **Emails** | `john@example.com` | `[email removed]` | +| **Phone Numbers** | `+1-555-1234` | `[phone removed]` | +| **URLs** | `https://example.com` | `[url removed]` | +| **Team Names** | `Marine Research Institute` | `Team 1` | +| **Descriptions** | Full 2000-char text | Truncated to 300-500 chars | +| **Dates** | `2024-02-15T14:30:00Z` | `2024` (year only) or `2024-02-15` (date only) | + +### Replacement Strategy + +**Sequential Anonymous IDs**: +- Projects: `P1`, `P2`, `P3`, ... +- Jurors: `juror_001`, `juror_002`, `juror_003`, ... +- Workspaces: `W1`, `W2`, `W3`, ... + +**Rationale**: Sequential IDs are easier for AI to reference and for humans to debug. Random UUIDs would be harder to correlate in logs. + +**Generic Team Names**: +- `Team 1`, `Team 2`, `Team 3`, ... + +**Rationale**: Preserves the concept of "team" without revealing institutional affiliation. + +### De-anonymization Mapping + +```typescript +// Stored in memory during AI call (never persisted to DB) +const mappings: ProjectAIMapping[] = [ + { anonymousId: "P1", realId: "proj-abc123xyz" }, + { anonymousId: "P2", realId: "proj-def456uvw" }, + { anonymousId: "P3", realId: "proj-ghi789rst" } +] + +// After AI returns results for "P1", map back to real ID +const realProjectId = mappings.find(m => m.anonymousId === "P1")?.realId +``` + +### Anonymization for Different Data Types + +#### Projects + +```typescript +// INPUT (ProjectWithRelations) +{ + id: "proj-abc123", + title: "SaveTheSea - Marine Conservation by Dr. John Doe", + description: "Contact john@example.com or call +1-555-1234. Visit https://savethesea.org for more info.", + teamName: "Marine Research Institute", + competitionCategory: "STARTUP", + country: "France", + geographicZone: "MEDITERRANEAN", + tags: ["Marine Biology", "AI", "Conservation"], + foundedAt: new Date("2024-01-15T00:00:00Z"), + institution: "University of Monaco", + wantsMentorship: true, + submissionSource: "WEB_FORM", + submittedAt: new Date("2024-02-15T14:30:00Z"), + _count: { teamMembers: 3, files: 5 }, + files: [ + { fileType: "PDF" }, + { fileType: "PDF" }, + { fileType: "DOCX" } + ] +} + +// OUTPUT (AnonymizedProjectForAI) +{ + project_id: "P1", + title: "SaveTheSea", // PII stripped + description: "Contact [email removed] or call [phone removed]. Visit [url removed] for more info.", // Sanitized + truncated + category: "STARTUP", + ocean_issue: null, + country: "France", + region: "MEDITERRANEAN", + institution: "University of Monaco", // Kept (non-PII institutional data) + tags: ["Marine Biology", "AI", "Conservation"], + founded_year: 2024, // Date reduced to year only + team_size: 3, + has_description: true, + file_count: 5, + file_types: ["PDF", "DOCX"], + wants_mentorship: true, + submission_source: "WEB_FORM", + submitted_date: "2024-02-15" // Date only, no time +} +``` + +#### Jurors + +```typescript +// INPUT (JurorForAssignment) +{ + id: "user-456def", + name: "Dr. Jane Smith", + email: "jane.smith@university.edu", + expertiseTags: ["Marine Biology", "Oceanography"], + maxAssignments: 20, + _count: { assignments: 5 } +} + +// OUTPUT (AnonymizedJuror) +{ + anonymousId: "juror_001", + expertiseTags: ["Marine Biology", "Oceanography"], + currentAssignmentCount: 5, + maxAssignments: 20 + // Name and email completely removed +} +``` + +#### Evaluations + +```typescript +// INPUT (EvaluationForSummary) +{ + id: "eval-789ghi", + criterionScoresJson: { "Innovation": 9, "Feasibility": 7, "Impact": 8 }, + globalScore: 8, + binaryDecision: true, + feedbackText: "Excellent proposal from Dr. John Doe (john@example.com). Strong technical approach but budget seems optimistic. Call me at +1-555-9876 to discuss.", + assignment: { + user: { + id: "user-123abc", + name: "Dr. Alice Johnson", + email: "alice@university.edu" + } + } +} + +// OUTPUT (AnonymizedEvaluation) +{ + criterionScores: { "Innovation": 9, "Feasibility": 7, "Impact": 8 }, + globalScore: 8, + binaryDecision: true, + feedbackText: "Excellent proposal. Strong technical approach but budget seems optimistic. Call me at [phone removed] to discuss." + // User info completely removed + // PII sanitized from feedback +} +``` + +### GDPR Validation Workflow + +```typescript +// 1. Anonymize data +const { anonymized, mappings } = anonymizeProjectsForAI(projects, 'FILTERING') + +// 2. Validate BEFORE sending to AI +if (!validateAnonymizedProjects(anonymized)) { + console.error('[AI Service] GDPR validation failed') + + // Log violation + await prisma.auditLog.create({ + data: { + action: 'AI_GDPR_VIOLATION', + entityType: 'AIService', + details: { service: 'filtering', error: 'PII detected in anonymized data' } + } + }) + + throw new Error('GDPR compliance check failed: PII detected in anonymized data') +} + +// 3. Only if validation passes, send to AI +const response = await openai.chat.completions.create(params) + +// 4. De-anonymize results +const realResults = mappings.map(mapping => { + const aiResult = response.find(r => r.project_id === mapping.anonymousId) + return { + projectId: mapping.realId, + ...aiResult + } +}) +``` + +--- + +## Prompt Engineering + +### System Prompt Templates + +#### Filtering Prompt + +```typescript +const AI_SCREENING_SYSTEM_PROMPT = `Project screening assistant. Evaluate against criteria, return JSON. +Format: {"projects": [{project_id, meets_criteria: bool, confidence: 0-1, reasoning: str, quality_score: 1-10, spam_risk: bool}]} +Be objective. Base evaluation only on provided data. No personal identifiers in reasoning.` +``` + +**Design Principles**: +- **Compact**: 3 sentences instead of 10 paragraphs (saves tokens) +- **JSON Schema**: Explicit output format prevents parsing errors +- **Objectivity**: Reminds AI to avoid bias +- **Privacy**: Explicitly forbids personal identifiers in output + +#### Assignment Prompt + +```typescript +const ASSIGNMENT_SYSTEM_PROMPT = `Match jurors to projects by expertise. Return JSON assignments. +Each: {juror_id, project_id, confidence_score: 0-1, expertise_match_score: 0-1, reasoning: str (1-2 sentences)} +Distribute workload fairly. Avoid assigning jurors at capacity.` +``` + +**Design Principles**: +- **Constraint Awareness**: Reminds AI about workload balancing +- **Brevity Requirement**: "1-2 sentences" for reasoning (saves tokens) +- **Dual Scores**: Separates confidence (how sure AI is) from expertise match (how good the fit is) + +#### Evaluation Summary Prompt + +```typescript +const EVALUATION_SUMMARY_PROMPT = `You are analyzing jury evaluations for a project competition. + +PROJECT: "${sanitizedTitle}" + +EVALUATION CRITERIA: ${criteriaLabels.join(', ')} + +EVALUATIONS (${count} total): +${JSON.stringify(anonymizedEvaluations, null, 2)} + +Analyze these evaluations and return a JSON object with this exact structure: +{ + "overallAssessment": "A 2-3 sentence summary of how the project was evaluated overall", + "strengths": ["strength 1", "strength 2", ...], + "weaknesses": ["weakness 1", "weakness 2", ...], + "themes": [ + { "theme": "theme name", "sentiment": "positive" | "negative" | "mixed", "frequency": } + ], + "recommendation": "A brief recommendation based on the evaluation consensus" +} + +Guidelines: +- Base your analysis only on the provided evaluation data +- Identify common themes across evaluator feedback +- Note areas of agreement and disagreement +- Keep the assessment objective and balanced +- Do not include any personal identifiers` +``` + +**Design Principles**: +- **Structured Output**: JSON schema enforces consistency +- **Sentiment Analysis**: Themes include positive/negative/mixed classification +- **Consensus Detection**: Frequency count shows how many evaluators mentioned each theme +- **Explicit Guidelines**: 5 bullet points ensure quality output + +### Dynamic Context Injection + +```typescript +// Build prompts dynamically based on available data +function buildFilteringPrompt( + criteriaText: string, + projects: AnonymizedProjectForAI[], + context?: { + previousRound?: { passRate: number }, + categoryDistribution?: { STARTUP: number, BUSINESS_CONCEPT: number } + } +): string { + let prompt = `CRITERIA: ${criteriaText}\nPROJECTS: ${JSON.stringify(projects)}\n` + + if (context?.previousRound) { + prompt += `\nPREVIOUS ROUND: Pass rate was ${context.previousRound.passRate}%. Apply similar rigor.\n` + } + + if (context?.categoryDistribution) { + prompt += `\nCATEGORY BALANCE: Aim for roughly ${context.categoryDistribution.STARTUP}% startups, ${context.categoryDistribution.BUSINESS_CONCEPT}% concepts.\n` + } + + prompt += `\nEvaluate and return JSON.` + return prompt +} +``` + +### Output Format Enforcement + +```typescript +// Use JSON mode for all AI calls +const params = buildCompletionParams(model, { + messages: [ + { role: 'system', content: systemPrompt }, + { role: 'user', content: userPrompt } + ], + jsonMode: true, // Enforces JSON output + temperature: 0.3, + maxTokens: 4000 +}) + +// Validate response structure +const parsed = JSON.parse(content) as ExpectedStructure + +if (!isValidStructure(parsed)) { + throw createParseError('AI returned invalid JSON structure') +} +``` + +### Token Limit Management + +```typescript +// Description limits by context +export const DESCRIPTION_LIMITS = { + ASSIGNMENT: 300, // Short - only need general topic + FILTERING: 500, // Medium - need enough detail for quality assessment + ELIGIBILITY: 400, // Medium - need criteria matching + MENTOR: 350 // Short - expertise matching +} + +// Calculate estimated token count before API call +function estimateTokens(text: string): number { + // Rough estimate: 1 token ≈ 4 characters + return Math.ceil(text.length / 4) +} + +// Warn if approaching limits +const promptTokens = estimateTokens(userPrompt) +if (promptTokens > 3000) { + console.warn(`[AI Service] Large prompt detected: ${promptTokens} tokens`) +} + +// Set maxTokens based on expected output +const maxTokens = { + FILTERING: 4000, // Batch of 20 projects + ASSIGNMENT: 4000, // Batch of 15 projects + SUMMARY: 2000, // Single summary + TAGGING: 1000 // Tag suggestions +}[serviceType] +``` + +### Retry and Fallback Strategies + +```typescript +async function callAIWithRetry( + apiCall: () => Promise, + fallback: () => T, + maxRetries = 3 +): Promise { + let lastError: Error + + for (let attempt = 1; attempt <= maxRetries; attempt++) { + try { + return await apiCall() + } catch (error) { + lastError = error + + const classified = classifyAIError(error) + + // Don't retry on validation errors or rate limits + if (classified.type === 'VALIDATION' || classified.type === 'RATE_LIMIT') { + break + } + + // Wait before retry (exponential backoff) + if (attempt < maxRetries) { + await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt))) + } + } + } + + // Fall back to algorithm + console.warn(`[AI Service] Failed after ${maxRetries} attempts, using fallback`, lastError) + return fallback() +} +``` + +--- + +## OpenAI Integration + +### Model Selection + +```typescript +// lib/openai.ts +export const AI_MODELS = { + STRONG: 'gpt-4', // Complex reasoning (filtering, assignment) + QUICK: 'gpt-4-turbo', // Fast analysis (summaries, tagging) + CHEAP: 'gpt-3.5-turbo', // Simple tasks (deprecated for this platform) + EMBEDDING: 'text-embedding-3-small' // For duplicate detection +} + +// Get configured model from settings +export async function getConfiguredModel(preference?: string): Promise { + const settings = await prisma.systemSettings.findUnique({ + where: { key: 'ai_model' } + }) + + const model = preference || settings?.value || AI_MODELS.STRONG + + // Validate model exists + if (!Object.values(AI_MODELS).includes(model)) { + console.warn(`[OpenAI] Unknown model "${model}", falling back to ${AI_MODELS.STRONG}`) + return AI_MODELS.STRONG + } + + return model +} +``` + +**Model Usage by Service**: +| Service | Model | Rationale | +|---------|-------|-----------| +| Filtering | `gpt-4` | Needs strong reasoning for nuanced criteria interpretation | +| Assignment | `gpt-4` | Complex constraint balancing (expertise + load + COI) | +| Summary | `gpt-4-turbo` | Fast synthesis, less reasoning required | +| Tagging | `gpt-4-turbo` | Simple categorization task | +| Eligibility | `gpt-4` | Plain-language criteria need strong comprehension | +| Mentoring Insights | `gpt-4-turbo` | Pattern detection, less critical reasoning | + +### Rate Limiting + +```typescript +// Rate limiter middleware +class AIRateLimiter { + private requestQueue: Array<() => Promise> = [] + private isProcessing = false + private requestsPerMinute = 60 // GPT-4 tier 1 limit + + async add(fn: () => Promise): Promise { + return new Promise((resolve, reject) => { + this.requestQueue.push(async () => { + try { + const result = await fn() + resolve(result) + } catch (error) { + reject(error) + } + }) + + if (!this.isProcessing) { + this.process() + } + }) + } + + private async process() { + this.isProcessing = true + + while (this.requestQueue.length > 0) { + const fn = this.requestQueue.shift()! + await fn() + + // Wait to respect rate limit + await new Promise(resolve => setTimeout(resolve, 60000 / this.requestsPerMinute)) + } + + this.isProcessing = false + } +} + +const rateLimiter = new AIRateLimiter() + +// Use in services +const result = await rateLimiter.add(() => openai.chat.completions.create(params)) +``` + +### Cost Tracking + +```typescript +// Token pricing (as of 2024) +const TOKEN_PRICING = { + 'gpt-4': { input: 0.03, output: 0.06 }, // per 1K tokens + 'gpt-4-turbo': { input: 0.01, output: 0.03 }, + 'text-embedding-3-small': { input: 0.0001, output: 0 } +} + +// Calculate cost +function calculateCost( + model: string, + promptTokens: number, + completionTokens: number +): number { + const pricing = TOKEN_PRICING[model] || TOKEN_PRICING['gpt-4'] + + const inputCost = (promptTokens / 1000) * pricing.input + const outputCost = (completionTokens / 1000) * pricing.output + + return inputCost + outputCost +} + +// Log usage with cost +await logAIUsage({ + userId, + action: 'FILTERING', + model, + promptTokens, + completionTokens, + totalTokens, + estimatedCost: calculateCost(model, promptTokens, completionTokens), + status: 'SUCCESS' +}) + +// Admin dashboard: show cumulative costs +const totalCost = await prisma.aIUsageLog.aggregate({ + where: { createdAt: { gte: startOfMonth } }, + _sum: { estimatedCost: true } +}) +``` + +### Error Handling + +```typescript +// ai-errors.ts +export type AIErrorType = + | 'RATE_LIMIT' + | 'AUTHENTICATION' + | 'NETWORK' + | 'TIMEOUT' + | 'VALIDATION' + | 'PARSE_ERROR' + | 'MODEL_NOT_FOUND' + | 'UNKNOWN' + +export interface ClassifiedAIError { + type: AIErrorType + message: string + retryable: boolean + userMessage: string +} + +export function classifyAIError(error: unknown): ClassifiedAIError { + const errorMsg = error instanceof Error ? error.message : String(error) + + // Rate limit + if (errorMsg.includes('rate_limit') || errorMsg.includes('429')) { + return { + type: 'RATE_LIMIT', + message: errorMsg, + retryable: true, + userMessage: 'AI service is currently at capacity. Please try again in a few minutes.' + } + } + + // Authentication + if (errorMsg.includes('authentication') || errorMsg.includes('401') || errorMsg.includes('api key')) { + return { + type: 'AUTHENTICATION', + message: errorMsg, + retryable: false, + userMessage: 'OpenAI API key is invalid or missing. Please check Settings > AI Configuration.' + } + } + + // Model not found + if (errorMsg.includes('model') && errorMsg.includes('does not exist')) { + return { + type: 'MODEL_NOT_FOUND', + message: errorMsg, + retryable: false, + userMessage: 'The configured AI model does not exist. Please check Settings > AI Configuration.' + } + } + + // Network + if (errorMsg.includes('ECONNREFUSED') || errorMsg.includes('ETIMEDOUT') || errorMsg.includes('network')) { + return { + type: 'NETWORK', + message: errorMsg, + retryable: true, + userMessage: 'Unable to reach OpenAI servers. Please check your internet connection.' + } + } + + // Timeout + if (errorMsg.includes('timeout')) { + return { + type: 'TIMEOUT', + message: errorMsg, + retryable: true, + userMessage: 'AI request timed out. Please try again or reduce batch size.' + } + } + + // Validation + if (errorMsg.includes('validation') || errorMsg.includes('invalid')) { + return { + type: 'VALIDATION', + message: errorMsg, + retryable: false, + userMessage: 'Invalid request to AI service. Please contact support.' + } + } + + // Parse error + if (error instanceof SyntaxError || errorMsg.includes('parse') || errorMsg.includes('JSON')) { + return { + type: 'PARSE_ERROR', + message: errorMsg, + retryable: false, + userMessage: 'AI response could not be understood. This has been logged for review.' + } + } + + // Unknown + return { + type: 'UNKNOWN', + message: errorMsg, + retryable: true, + userMessage: 'An unexpected error occurred with the AI service. Please try again.' + } +} + +export function logAIError(service: string, operation: string, error: ClassifiedAIError): void { + console.error(`[AI Error] ${service}.${operation}:`, { + type: error.type, + message: error.message, + retryable: error.retryable + }) + + // Log to database for admin review + prisma.auditLog.create({ + data: { + action: 'AI_ERROR', + entityType: 'AIService', + details: { + service, + operation, + errorType: error.type, + message: error.message + } + } + }).catch(console.error) +} +``` + +### Streaming vs Non-Streaming + +**Current Implementation**: Non-streaming (wait for full response) + +```typescript +const response = await openai.chat.completions.create({ + model: 'gpt-4', + messages: [...], + stream: false // Wait for complete response +}) + +const content = response.choices[0]?.message?.content +``` + +**Future Enhancement**: Streaming for long summaries + +```typescript +// For evaluation summaries, stream to UI as tokens arrive +const stream = await openai.chat.completions.create({ + model: 'gpt-4', + messages: [...], + stream: true +}) + +for await (const chunk of stream) { + const delta = chunk.choices[0]?.delta?.content || '' + + // Send to frontend via SSE + res.write(`data: ${JSON.stringify({ delta })}\n\n`) +} +``` + +--- + +## Privacy & Security + +### Data Minimization + +**Principle**: Send only the minimum data required for the AI task. + +| Service | Data Sent | Data NOT Sent | +|---------|-----------|---------------| +| **Filtering** | Project title, description (truncated), category, tags, file types, team size | Team names, emails, phone numbers, full descriptions, user IDs | +| **Assignment** | Juror expertise tags, current assignment count, max assignments, project tags | Juror names, emails, user IDs, juror institutions | +| **Summary** | Evaluation scores, sanitized feedback text | Juror names, emails, user IDs | +| **Tagging** | Project title, description (truncated), category, tags | Team names, emails, phone numbers, user IDs | +| **Eligibility** | Project category, tags, country, founded year | Team names, emails, phone numbers, full descriptions | + +### PII Stripping Workflow + +```mermaid +graph TD + A[Raw Data] --> B{Contains PII?} + B -->|Yes| C[Sanitize Text] + B -->|No| D[Validate] + C --> E[Replace IDs] + E --> F[Truncate Descriptions] + F --> D + D --> G{GDPR Pass?} + G -->|No| H[Reject + Log] + G -->|Yes| I[Send to AI] + I --> J[AI Response] + J --> K[De-anonymize] + K --> L[Return Real Results] +``` + +### Audit Logging + +```typescript +// All AI requests logged with full context +await logAIUsage({ + userId: 'admin-123', + action: 'FILTERING', + entityType: 'Round', + entityId: 'round-456', + model: 'gpt-4', + promptTokens: 1234, + completionTokens: 567, + totalTokens: 1801, + batchSize: 20, + itemsProcessed: 20, + status: 'SUCCESS', + estimatedCost: 0.0891, + metadata: { + criteriaText: 'Reject spam projects...', + passRate: 0.75 + } +}) + +// Failed requests also logged +await logAIUsage({ + userId: 'admin-123', + action: 'ASSIGNMENT', + model: 'gpt-4', + status: 'ERROR', + errorMessage: 'Rate limit exceeded', + metadata: { + jurorCount: 15, + projectCount: 45 + } +}) +``` + +### Data Retention Policy + +```typescript +// AI usage logs retained for 90 days, then archived +export async function archiveOldAILogs(): Promise { + const cutoffDate = new Date() + cutoffDate.setDate(cutoffDate.getDate() - 90) + + const oldLogs = await prisma.aIUsageLog.findMany({ + where: { createdAt: { lt: cutoffDate } } + }) + + // Move to archive storage (S3, cold storage, etc.) + await archiveService.store('ai-logs', oldLogs) + + // Delete from hot database + await prisma.aIUsageLog.deleteMany({ + where: { createdAt: { lt: cutoffDate } } + }) +} + +// Run nightly via cron +``` + +### Opt-Out Capabilities + +```typescript +// Per-service opt-out in settings +interface AISettings { + ai_enabled: boolean // Master toggle + ai_filtering_enabled: boolean + ai_assignment_enabled: boolean + ai_summary_enabled: boolean + ai_tagging_enabled: boolean + ai_eligibility_enabled: boolean +} + +// Check before each AI call +export async function isAIServiceEnabled(service: AIServiceType): Promise { + const masterEnabled = await getSystemSetting('ai_enabled') + if (!masterEnabled) return false + + const serviceEnabled = await getSystemSetting(`ai_${service}_enabled`) + return serviceEnabled !== 'false' +} + +// Graceful fallback when disabled +if (!await isAIServiceEnabled('assignment')) { + return generateFallbackAssignments(jurors, projects, constraints) +} +``` + +--- + +## Admin AI Controls + +### AI Configuration Dashboard + +``` +┌────────────────────────────────────────────────────────────────────┐ +│ Settings > AI Configuration │ +├────────────────────────────────────────────────────────────────────┤ +│ │ +│ General Settings │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ OpenAI API Key: [sk-proj-••••••••••••••••••••••••••] [ Test ] │ +│ ✓ Connected (last verified: 2024-02-15 14:30) │ +│ │ +│ Default Model: [ gpt-4 ▼ ] │ +│ Estimated cost: $0.03 per 1K tokens (input) │ +│ │ +│ [ ] Enable AI Services ← Master toggle │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Service-Specific Settings │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [✓] AI Filtering │ +│ Batch Size: [ 20 ] projects per API call │ +│ Parallel Batches: [ 2 ] concurrent requests │ +│ Model Override: [ (use default) ▼ ] │ +│ │ +│ [✓] AI Assignment │ +│ Batch Size: [ 15 ] projects per API call │ +│ Model Override: [ (use default) ▼ ] │ +│ │ +│ [✓] AI Evaluation Summaries │ +│ Auto-generate: [✓] When all evaluations submitted │ +│ Model Override: [ gpt-4-turbo ▼ ] (faster for summaries) │ +│ │ +│ [✓] AI Tagging │ +│ Confidence Threshold: [ 0.5 ] (0.0 - 1.0) │ +│ Max Tags per Project: [ 5 ] │ +│ Auto-tag on Submit: [✓] Apply tags when project submitted │ +│ │ +│ [✓] AI Award Eligibility │ +│ Model Override: [ (use default) ▼ ] │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Usage & Cost Tracking │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ This Month: 1,234,567 tokens | Est. Cost: $42.18 │ +│ Last Month: 987,654 tokens | Est. Cost: $31.45 │ +│ │ +│ [ View Detailed Usage Log ] │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [ Save Changes ] [ Reset to Defaults ] │ +│ │ +└────────────────────────────────────────────────────────────────────┘ +``` + +### Rubric Editor for Filtering + +``` +┌────────────────────────────────────────────────────────────────────┐ +│ Round 2: FILTERING > AI Screening Rules │ +├────────────────────────────────────────────────────────────────────┤ +│ │ +│ Rule: Spam & Quality Check │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Criteria (Plain Language): │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ Projects should demonstrate clear ocean conservation value. │ │ +│ │ │ │ +│ │ Reject projects that: │ │ +│ │ - Are spam, test submissions, or joke entries │ │ +│ │ - Have no meaningful description (< 100 words) │ │ +│ │ - Are unrelated to ocean conservation │ │ +│ │ - Are duplicate submissions │ │ +│ │ │ │ +│ │ Flag for manual review: │ │ +│ │ - Projects with unclear focus or vague descriptions │ │ +│ │ - Projects that may be legitimate but borderline │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ Action: ( ) PASS (•) REJECT ( ) FLAG │ +│ │ +│ Priority: [ 1 ] (1 = highest, 10 = lowest) │ +│ │ +│ [ ] Active │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Preview & Test │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Test this rule on sample projects: │ +│ │ +│ [✓] SaveTheSea - AI-powered coral reef monitoring │ +│ Result: PASS (confidence: 0.92) │ +│ Reasoning: Clear ocean conservation focus, detailed approach │ +│ │ +│ [✓] Test Project - Just testing the form │ +│ Result: REJECT (confidence: 0.98) │ +│ Reasoning: Appears to be a test submission with no real value │ +│ │ +│ [✓] Marine Plastic Solution (vague description) │ +│ Result: FLAG (confidence: 0.65) │ +│ Reasoning: Ocean-related but description lacks detail │ +│ │ +│ [ Run Test on 10 Random Projects ] │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [ Save Rule ] [ Delete Rule ] [ Cancel ] │ +│ │ +└────────────────────────────────────────────────────────────────────┘ +``` + +### AI Results Review Interface + +``` +┌────────────────────────────────────────────────────────────────────┐ +│ Round 2: FILTERING > AI Results Review │ +├────────────────────────────────────────────────────────────────────┤ +│ │ +│ AI Screening Complete │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Processed: 120 projects │ +│ Passed: 87 (72.5%) │ +│ Rejected: 21 (17.5%) │ +│ Flagged: 12 (10.0%) │ +│ │ +│ Tokens Used: 45,678 | Est. Cost: $1.37 │ +│ Model: gpt-4 | Batches: 6 of 20 projects each │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Flagged Projects (Require Manual Review) │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [ ] Marine Plastic Solution │ +│ Confidence: 0.65 │ +│ AI Reasoning: Ocean-related but description lacks sufficient │ +│ detail. Unclear commercial model. May be early- │ +│ stage concept that needs more development. │ +│ Quality Score: 6/10 │ +│ Spam Risk: No │ +│ │ +│ Admin Decision: ( ) PASS ( ) REJECT ( ) Keep Flagged │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [ ] Ocean Cleanup AI │ +│ Confidence: 0.58 │ +│ AI Reasoning: Uses AI buzzwords extensively but lacks technical│ +│ specifics. May be over-promising. Borderline. │ +│ Quality Score: 5/10 │ +│ Spam Risk: No │ +│ │ +│ Admin Decision: ( ) PASS ( ) REJECT ( ) Keep Flagged │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [ Review All Flagged (12) ] [ Bulk Approve ] [ Bulk Reject ] │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Rejected Projects (Can Override) │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [✓] Test Submission │ +│ Confidence: 0.98 │ +│ AI Reasoning: Obvious test submission with placeholder text. │ +│ Override: [ ] Approve This Project │ +│ │ +│ [✓] Spam Project 123 │ +│ Confidence: 0.95 │ +│ AI Reasoning: Unrelated to ocean conservation, generic content.│ +│ Override: [ ] Approve This Project │ +│ │ +│ [ Show All Rejected (21) ] │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ [ Finalize Results ] [ Export CSV ] [ Re-run AI Screening ] │ +│ │ +└────────────────────────────────────────────────────────────────────┘ +``` + +### Cost Monitoring Dashboard + +``` +┌────────────────────────────────────────────────────────────────────┐ +│ Analytics > AI Usage & Costs │ +├────────────────────────────────────────────────────────────────────┤ +│ │ +│ Overview (February 2024) │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Total API Calls: 1,234 │ +│ Total Tokens: 4,567,890 │ +│ Estimated Cost: $137.04 │ +│ Avg Cost per Call: $0.11 │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Cost Breakdown by Service │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Filtering: $45.67 (33%) ████████░░░ │ +│ Assignment: $38.21 (28%) ███████░░░░ │ +│ Evaluation Summary: $28.90 (21%) █████░░░░░░ │ +│ Tagging: $15.12 (11%) ███░░░░░░░░ │ +│ Award Eligibility: $9.14 (7%) ██░░░░░░░░░ │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Token Usage Trend │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ 500K ┤ ╭─ │ +│ 400K ┤ ╭────────╯ │ +│ 300K ┤ ╭────────────╯ │ +│ 200K ┤ ╭─────────────╯ │ +│ 100K ┤ ╭────────╯ │ +│ 0 ┼───┴──────────────────────────────────────────────────── │ +│ Feb 1 Feb 8 Feb 15 Feb 22 Feb 29 │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Recent API Calls │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ 2024-02-15 14:30 | Filtering | Round 2 | 20 projects │ +│ gpt-4 | 3,456 tokens | $0.10 | SUCCESS │ +│ │ +│ 2024-02-15 14:15 | Assignment | Round 3 | 15 projects │ +│ gpt-4 | 4,123 tokens | $0.12 | SUCCESS │ +│ │ +│ 2024-02-15 13:45 | Summary | Proj-123 | 5 evaluations │ +│ gpt-4-turbo | 1,890 tokens | $0.02 | ✓ │ +│ │ +│ [ View All Logs ] [ Export CSV ] [ Set Budget Alert ] │ +│ │ +└────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## API Changes + +### New tRPC Procedures + +#### AI Router (`src/server/routers/ai.ts`) + +```typescript +export const aiRouter = createTRPCRouter({ + + // Test OpenAI connection + testConnection: adminProcedure + .mutation(async ({ ctx }) => { + const openai = await getOpenAI() + if (!openai) { + throw new TRPCError({ code: 'PRECONDITION_FAILED', message: 'OpenAI not configured' }) + } + + try { + await openai.models.list() + return { connected: true, message: 'OpenAI connection successful' } + } catch (error) { + return { connected: false, message: error.message } + } + }), + + // Get AI usage stats + getUsageStats: adminProcedure + .input(z.object({ + startDate: z.date(), + endDate: z.date() + })) + .query(async ({ ctx, input }) => { + const logs = await ctx.prisma.aIUsageLog.findMany({ + where: { + createdAt: { + gte: input.startDate, + lte: input.endDate + } + } + }) + + const totalTokens = logs.reduce((sum, log) => sum + log.totalTokens, 0) + const totalCost = logs.reduce((sum, log) => sum + (log.estimatedCost || 0), 0) + + const byService = logs.reduce((acc, log) => { + const service = log.action + if (!acc[service]) { + acc[service] = { count: 0, tokens: 0, cost: 0 } + } + acc[service].count++ + acc[service].tokens += log.totalTokens + acc[service].cost += log.estimatedCost || 0 + return acc + }, {} as Record) + + return { + totalCalls: logs.length, + totalTokens, + totalCost, + avgCostPerCall: totalCost / logs.length, + byService + } + }), + + // Tag a single project + tagProject: adminProcedure + .input(z.object({ + projectId: z.string() + })) + .mutation(async ({ ctx, input }) => { + const result = await tagProject(input.projectId, ctx.session.user.id) + return result + }), + + // Get tag suggestions (preview only, don't apply) + getTagSuggestions: adminProcedure + .input(z.object({ + projectId: z.string() + })) + .query(async ({ ctx, input }) => { + const suggestions = await getTagSuggestions(input.projectId, ctx.session.user.id) + return suggestions + }), + + // Generate evaluation summary + generateEvaluationSummary: adminProcedure + .input(z.object({ + projectId: z.string(), + roundId: z.string() + })) + .mutation(async ({ ctx, input }) => { + const summary = await generateSummary({ + projectId: input.projectId, + stageId: input.roundId, + userId: ctx.session.user.id, + prisma: ctx.prisma + }) + return summary + }), + + // Generate AI assignments + generateAssignments: adminProcedure + .input(z.object({ + roundId: z.string(), + constraints: z.object({ + requiredReviewsPerProject: z.number(), + minAssignmentsPerJuror: z.number().optional(), + maxAssignmentsPerJuror: z.number().optional() + }) + })) + .mutation(async ({ ctx, input }) => { + const round = await ctx.prisma.round.findUnique({ + where: { id: input.roundId }, + include: { + juryGroup: { + include: { + members: { include: { user: true } } + } + } + } + }) + + if (!round?.juryGroup) { + throw new TRPCError({ code: 'NOT_FOUND', message: 'Round or jury group not found' }) + } + + const projects = await ctx.prisma.project.findMany({ + where: { + projectRoundStates: { + some: { + roundId: input.roundId, + state: 'PASSED' + } + } + }, + include: { _count: { select: { assignments: true } } } + }) + + const existingAssignments = await ctx.prisma.assignment.findMany({ + where: { roundId: input.roundId }, + select: { userId: true, projectId: true } + }) + + const result = await generateAIAssignments( + round.juryGroup.members.map(m => m.user), + projects, + { + ...input.constraints, + existingAssignments + }, + ctx.session.user.id, + input.roundId + ) + + return result + }), + + // Run filtering on a round + runFiltering: adminProcedure + .input(z.object({ + roundId: z.string() + })) + .mutation(async ({ ctx, input }) => { + const round = await ctx.prisma.round.findUnique({ + where: { id: input.roundId } + }) + + if (round?.roundType !== 'FILTERING') { + throw new TRPCError({ code: 'BAD_REQUEST', message: 'Not a filtering round' }) + } + + const rules = await ctx.prisma.filteringRule.findMany({ + where: { roundId: input.roundId, isActive: true }, + orderBy: { priority: 'asc' } + }) + + const projects = await ctx.prisma.project.findMany({ + where: { + projectRoundStates: { + some: { roundId: input.roundId } + } + }, + include: { + files: true, + _count: { select: { teamMembers: true } } + } + }) + + const results = await executeFilteringRules( + rules, + projects, + ctx.session.user.id, + input.roundId + ) + + // Store results + for (const result of results) { + await ctx.prisma.filteringResult.upsert({ + where: { + projectId_roundId: { + projectId: result.projectId, + roundId: input.roundId + } + }, + create: { + projectId: result.projectId, + roundId: input.roundId, + outcome: result.outcome, + ruleResultsJson: result.ruleResults, + aiScreeningJson: result.aiScreeningJson + }, + update: { + outcome: result.outcome, + ruleResultsJson: result.ruleResults, + aiScreeningJson: result.aiScreeningJson + } + }) + } + + return { + total: results.length, + passed: results.filter(r => r.outcome === 'PASSED').length, + rejected: results.filter(r => r.outcome === 'FILTERED_OUT').length, + flagged: results.filter(r => r.outcome === 'FLAGGED').length + } + }), + + // Check award eligibility + checkAwardEligibility: adminProcedure + .input(z.object({ + awardId: z.string() + })) + .mutation(async ({ ctx, input }) => { + const award = await ctx.prisma.specialAward.findUnique({ + where: { id: input.awardId } + }) + + if (!award?.useAiEligibility || !award.criteriaText) { + throw new TRPCError({ code: 'BAD_REQUEST', message: 'AI eligibility not enabled for this award' }) + } + + const projects = await ctx.prisma.project.findMany({ + where: { competitionId: award.competitionId }, + include: { + files: true, + _count: { select: { teamMembers: true } } + } + }) + + const results = await aiInterpretCriteria( + award.criteriaText, + projects, + ctx.session.user.id, + award.id + ) + + // Store results + for (const result of results) { + await ctx.prisma.awardEligibility.upsert({ + where: { + specialAwardId_projectId: { + specialAwardId: award.id, + projectId: result.projectId + } + }, + create: { + specialAwardId: award.id, + projectId: result.projectId, + isEligible: result.eligible, + confidence: result.confidence, + reasoning: result.reasoning, + method: result.method + }, + update: { + isEligible: result.eligible, + confidence: result.confidence, + reasoning: result.reasoning, + method: result.method + } + }) + } + + return { + total: results.length, + eligible: results.filter(r => r.eligible).length, + ineligible: results.filter(r => !r.eligible).length + } + }) +}) +``` + +--- + +## Service Functions + +### Complete Function Signatures + +```typescript +// ai-filtering.ts +export function evaluateFieldRule( + config: FieldRuleConfig, + project: ProjectForFiltering +): { passed: boolean; action: 'PASS' | 'REJECT' | 'FLAG' } + +export function evaluateDocumentRule( + config: DocumentCheckConfig, + project: ProjectForFiltering +): { passed: boolean; action: 'PASS' | 'REJECT' | 'FLAG' } + +export async function executeAIScreening( + config: AIScreeningConfig, + projects: ProjectForFiltering[], + userId?: string, + entityId?: string, + onProgress?: ProgressCallback +): Promise> + +export async function executeFilteringRules( + rules: FilteringRuleInput[], + projects: ProjectForFiltering[], + userId?: string, + stageId?: string, + onProgress?: ProgressCallback +): Promise + +// ai-assignment.ts +export async function generateAIAssignments( + jurors: JurorForAssignment[], + projects: ProjectForAssignment[], + constraints: AssignmentConstraints, + userId?: string, + entityId?: string, + onProgress?: AssignmentProgressCallback +): Promise + +export function generateFallbackAssignments( + jurors: JurorForAssignment[], + projects: ProjectForAssignment[], + constraints: AssignmentConstraints +): AIAssignmentResult + +// ai-evaluation-summary.ts +export function anonymizeEvaluations( + evaluations: EvaluationForSummary[] +): AnonymizedEvaluation[] + +export function buildSummaryPrompt( + anonymizedEvaluations: AnonymizedEvaluation[], + projectTitle: string, + criteriaLabels: string[] +): string + +export function computeScoringPatterns( + evaluations: EvaluationForSummary[], + criteriaLabels: CriterionDef[] +): ScoringPatterns + +export async function generateSummary({ + projectId, + stageId, + userId, + prisma +}: { + projectId: string + stageId: string + userId: string + prisma: PrismaClient +}): Promise + +// ai-tagging.ts +export async function getTaggingSettings(): Promise<{ + enabled: boolean + maxTags: number +}> + +export async function getAvailableTags(): Promise + +export async function tagProject( + projectId: string, + userId?: string +): Promise + +export async function getTagSuggestions( + projectId: string, + userId?: string +): Promise + +export async function addProjectTag( + projectId: string, + tagId: string +): Promise + +export async function removeProjectTag( + projectId: string, + tagId: string +): Promise + +// ai-award-eligibility.ts +export function applyAutoTagRules( + rules: AutoTagRule[], + projects: ProjectForEligibility[] +): Map + +export async function aiInterpretCriteria( + criteriaText: string, + projects: ProjectForEligibility[], + userId?: string, + awardId?: string +): Promise + +// anonymization.ts +export function sanitizeText(text: string): string + +export function truncateAndSanitize( + text: string | null | undefined, + maxLength: number +): string + +export function anonymizeForAI( + jurors: JurorInput[], + projects: ProjectInput[] +): AnonymizationResult + +export function anonymizeProjectForAI( + project: ProjectWithRelations, + index: number, + context: DescriptionContext +): AnonymizedProjectForAI + +export function anonymizeProjectsForAI( + projects: ProjectWithRelations[], + context: DescriptionContext +): { + anonymized: AnonymizedProjectForAI[] + mappings: ProjectAIMapping[] +} + +export function deanonymizeResults( + results: T[], + jurorMappings: JurorMapping[], + projectMappings: ProjectMapping[] +): (T & { realJurorId: string; realProjectId: string })[] + +export function validateNoPersonalData( + data: Record +): PIIValidationResult + +export function enforceGDPRCompliance(data: unknown[]): void + +export function validateAnonymization(data: AnonymizationResult): boolean + +export function validateAnonymizedProjects( + projects: AnonymizedProjectForAI[] +): boolean + +export function toProjectWithRelations(project: unknown): ProjectWithRelations +``` + +--- + +## Edge Cases + +| Scenario | Behavior | Fallback | +|----------|----------|----------| +| **OpenAI API key missing** | AI services disabled | Use algorithm-based fallbacks | +| **OpenAI rate limit hit** | Queue requests, retry with exponential backoff | Fail gracefully after 3 retries | +| **AI returns invalid JSON** | Parse error logged, flagged for manual review | Mark items as "needs review" | +| **AI model doesn't exist** | Throw clear error with model name | Suggest checking Settings > AI Config | +| **Anonymization validation fails** | Throw error, log GDPR violation | Reject AI call, require manual review | +| **All projects rejected by AI** | Admin gets warning notification | Admin reviews AI reasoning | +| **Zero tag suggestions** | Return empty array | No error, just no tags applied | +| **Confidence too low (<0.5)** | Tag not applied automatically | Admin can manually apply | +| **Duplicate project detected (>0.85 similarity)** | Flagged for admin review | Admin marks as duplicate or false positive | +| **Mentor workspace inactive (>14 days)** | Intervention alert sent to admin | Admin reaches out to mentor | +| **Winner ranking unclear (close gap <0.3)** | AI flags as "close call", suggests review | Jury deliberates again | +| **Batch size too large (>50)** | Clamped to 50 projects per batch | Automatically split into multiple batches | +| **Description too long (>500 chars)** | Truncated with "..." | AI works with truncated text | +| **PII in feedback text** | Sanitized before sending to AI | Emails/phones replaced with `[email removed]` | +| **Juror has no expertise tags** | Scored as 0.5 (neutral) in assignment | Fallback algorithm includes them for load balancing | +| **Project has no description** | AI flags as low quality | Admin decides whether to reject | +| **All jurors at capacity** | Assignment fails with clear error | Admin adjusts caps or adds more jurors | +| **Award criteria too vague** | AI gives low-confidence results | Admin refines criteria and re-runs | +| **Evaluation summary with <3 evaluations** | AI summary still generated, marked as "limited data" | Admin aware that consensus may be weak | +| **Streaming response timeout** | Fall back to non-streaming request | Complete response returned after wait | + +--- + +## Integration Map + +### AI Services × Round Types + +```mermaid +graph TD + R1[Round 1: INTAKE] --> T[ai-tagging.ts] + T --> TAG[Auto-tag on submit] + + R2[Round 2: FILTERING] --> F[ai-filtering.ts] + F --> SCREEN[AI screening + rules] + F --> DUP[ai-duplicate-detection] + DUP --> EMBED[Embedding similarity] + + R3[Round 3: EVALUATION] --> A[ai-assignment.ts] + A --> ASSIGN[Generate assignments] + A --> E[ai-evaluation-summary.ts] + E --> SUM[Summarize evaluations] + + R4[Round 4: SUBMISSION] --> NONE1[No AI service] + + R5[Round 5: EVALUATION] --> A + A --> E + + R6[Round 6: MENTORING] --> M[ai-mentoring-insights.ts] + M --> INSIGHT[Workspace analysis] + + R7[Round 7: LIVE_FINAL] --> NONE2[No AI service] + + R8[Round 8: CONFIRMATION] --> C[ai-confirmation-helper.ts] + C --> EXPLAIN[Ranking explanation] + + AWARDS[Special Awards] --> AE[ai-award-eligibility.ts] + AE --> ELIG[Eligibility check] +``` + +### Data Flow Diagram + +```mermaid +sequenceDiagram + participant Admin + participant API + participant Service + participant Anonymization + participant OpenAI + participant DB + + Admin->>API: Trigger AI service + API->>Service: Call service function + Service->>DB: Fetch data + DB-->>Service: Raw data + Service->>Anonymization: Anonymize data + Anonymization->>Anonymization: Strip PII + Anonymization->>Anonymization: Replace IDs + Anonymization->>Anonymization: Validate GDPR + Anonymization-->>Service: Anonymized + mappings + Service->>OpenAI: API call + OpenAI-->>Service: AI response + Service->>Anonymization: De-anonymize results + Anonymization-->>Service: Real IDs + Service->>DB: Store results + DB-->>Service: Confirmation + Service->>DB: Log AI usage + Service-->>API: Results + API-->>Admin: Success + data +``` + +--- + +This completes the extremely detailed AI Services documentation covering all current services, new services for the redesign, anonymization pipeline, prompt engineering, OpenAI integration, privacy/security, admin controls, API changes, service functions, edge cases, and integration map. + +Total lines: 2,900+ diff --git a/docs/claude-architecture-redesign/15-admin-ui.md b/docs/claude-architecture-redesign/15-admin-ui.md new file mode 100644 index 0000000..28396bd --- /dev/null +++ b/docs/claude-architecture-redesign/15-admin-ui.md @@ -0,0 +1,761 @@ +# Admin UI Redesign + +## Overview + +The admin interface is the control plane for the entire MOPC competition. It must surface the redesigned Competition→Round model, jury group management, multi-round submissions, mentoring oversight, and winner confirmation — all through an intuitive, efficient interface. + +### Design Principles + +| Principle | Application | +|-----------|-------------| +| **Progressive disclosure** | Show essentials first; details on drill-down | +| **Linear-first navigation** | Round list is a flat, ordered timeline — not nested trees | +| **Status at a glance** | Color-coded badges, progress bars, countdowns on every card | +| **Override everywhere** | Every automated decision has an admin override within reach | +| **Audit transparency** | Every action logged; audit trail accessible from any entity | + +### Tech Stack (UI) + +- **Framework:** Next.js 15 App Router (Server Components default, `'use client'` where needed) +- **Styling:** Tailwind CSS 4, mobile-first breakpoints (`md:`, `lg:`) +- **Components:** shadcn/ui as base (Button, Card, Dialog, Sheet, Table, Tabs, Select, etc.) +- **Data fetching:** tRPC React Query hooks (`trpc.competition.getById.useQuery()`) +- **Brand:** Primary Red `#de0f1e`, Dark Blue `#053d57`, White `#fefefe`, Teal `#557f8c` +- **Typography:** Montserrat (600/700 headings, 300/400 body) + +--- + +## Current Admin UI Audit + +### Existing Pages + +``` +/admin/ +├── page.tsx — Dashboard (stats cards, quick actions) +├── rounds/ +│ ├── pipelines/page.tsx — Pipeline list +│ ├── new-pipeline/page.tsx — Create new pipeline +│ └── pipeline/[id]/ +│ ├── page.tsx — Pipeline detail (tracks + stages) +│ ├── edit/page.tsx — Edit pipeline settings +│ ├── wizard/page.tsx — Pipeline setup wizard +│ └── advanced/page.tsx — Advanced config (JSON editor) +├── awards/ +│ ├── page.tsx — Award list +│ ├── new/page.tsx — Create award +│ └── [id]/ +│ ├── page.tsx — Award detail +│ └── edit/page.tsx — Edit award +├── members/ +│ ├── page.tsx — User list +│ ├── invite/page.tsx — Invite user +│ └── [id]/page.tsx — User detail +├── mentors/ +│ ├── page.tsx — Mentor list +│ └── [id]/page.tsx — Mentor detail +├── projects/ — Project management +├── audit/page.tsx — Audit log viewer +├── messages/ +│ ├── page.tsx — Message center +│ └── templates/page.tsx — Email templates +├── programs/ — Program management +├── settings/ — System settings +├── reports/ — Reports +├── partners/ — Partner management +└── learning/ — Learning resources +``` + +### Current Limitations + +| Page | Limitation | +|------|-----------| +| Pipeline list | Shows pipelines as opaque cards. No inline status | +| Pipeline detail | Nested Track→Stage tree is confusing. Must drill into each stage | +| Pipeline wizard | Generic JSON config per stage type. Not type-aware | +| Award management | Awards are separate from pipeline. No jury group link | +| Member management | No jury group concept. Can't see "Jury 1 members" | +| Mentor oversight | Basic list only. No workspace visibility | +| No confirmation UI | Winner confirmation doesn't exist | + +--- + +## Redesigned Navigation + +### New Admin Sitemap + +``` +/admin/ +├── page.tsx — Dashboard (competition overview) +├── competition/ +│ ├── page.tsx — Competition list +│ ├── new/page.tsx — Create competition wizard +│ └── [id]/ +│ ├── page.tsx — Competition dashboard (round timeline) +│ ├── settings/page.tsx — Competition-wide settings +│ ├── rounds/ +│ │ ├── page.tsx — All rounds (timeline view) +│ │ ├── new/page.tsx — Add round +│ │ └── [roundId]/ +│ │ ├── page.tsx — Round detail (type-specific view) +│ │ ├── edit/page.tsx — Edit round config +│ │ ├── projects/page.tsx — Projects in this round +│ │ ├── assignments/page.tsx — Assignments (EVALUATION rounds) +│ │ ├── filtering/page.tsx — Filtering dashboard (FILTERING) +│ │ ├── submissions/page.tsx — Submission status (INTAKE/SUBMISSION) +│ │ ├── mentoring/page.tsx — Mentoring overview (MENTORING) +│ │ ├── stage-manager/page.tsx — Live stage manager (LIVE_FINAL) +│ │ └── confirmation/page.tsx — Confirmation (CONFIRMATION) +│ ├── jury-groups/ +│ │ ├── page.tsx — All jury groups +│ │ ├── new/page.tsx — Create jury group +│ │ └── [groupId]/ +│ │ ├── page.tsx — Jury group detail + members +│ │ └── edit/page.tsx — Edit group settings +│ ├── submission-windows/ +│ │ ├── page.tsx — All submission windows +│ │ └── [windowId]/ +│ │ ├── page.tsx — Window detail + requirements +│ │ └── edit/page.tsx — Edit window +│ ├── awards/ +│ │ ├── page.tsx — Special awards for this competition +│ │ ├── new/page.tsx — Create award +│ │ └── [awardId]/ +│ │ ├── page.tsx — Award detail +│ │ └── edit/page.tsx — Edit award +│ └── results/ +│ └── page.tsx — Final results + export +├── members/ — User management (unchanged) +├── audit/page.tsx — Audit log (enhanced) +├── messages/ — Messaging (unchanged) +├── programs/ — Program management +└── settings/ — System settings +``` + +--- + +## Competition Dashboard + +The central hub for managing a competition. Replaces the old Pipeline detail page. + +### Layout + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ MOPC 2026 Competition Status: ACTIVE [Edit] │ +│ Program: Monaco Ocean Protection Challenge 2026 │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ── Quick Stats ──────────────────────────────────────────────────── │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │ +│ │ 127 │ │ 23 │ │ 8 │ │ Round 3 of 8 │ │ +│ │ Applications│ │ Advancing │ │ Jury Groups│ │ Jury 1 Evaluation │ │ +│ │ │ │ │ │ 22 members │ │ ███████░░░ 68% │ │ +│ └────────────┘ └────────────┘ └────────────┘ └────────────────────┘ │ +│ │ +│ ── Round Timeline ───────────────────────────────────────────────── │ +│ │ +│ ✓ R1 ✓ R2 ● R3 ○ R4 ○ R5 ○ R6 ○ R7 ○ R8 │ +│ Intake Filter Jury 1 Submn 2 Jury 2 Mentor Finals Confirm │ +│ DONE DONE ACTIVE PENDING PENDING PENDING PENDING PENDING │ +│ 127 98→23 23/23 │ │ +│ eval'd │ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ Round 3: Jury 1 — Semi-finalist Selection [Manage →] │ │ +│ │ Type: EVALUATION | Jury: Jury 1 (8 members) │ │ +│ │ Status: ACTIVE | Started: Feb 1 | Deadline: Mar 15 │ │ +│ │ │ │ +│ │ ████████████████████████████████████░░░░░░░░░░░░ 68% │ │ +│ │ Evaluations: 186 / 276 complete │ │ +│ │ │ │ +│ │ ┌──────────────┬──────────────┬──────────────┬────────────┐ │ │ +│ │ │ Assigned: 276│ Complete: 186│ Pending: 90 │ COI: 12 │ │ │ +│ │ └──────────────┴──────────────┴──────────────┴────────────┘ │ │ +│ │ │ │ +│ │ [ View Assignments ] [ View Results ] [ Advance Projects ] │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ── Sidebar: Jury Groups ─────────────────────────────────────────── │ +│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │ +│ │ Jury 1 (8 members) [→] │ │ Jury 2 (6 members) [→] │ │ +│ │ Avg load: 15.3 / 20 │ │ Not yet assigned │ │ +│ │ ████████████████░░░░ │ │ ░░░░░░░░░░░░░░░░░░░░ │ │ +│ └─────────────────────────────┘ └─────────────────────────────┘ │ +│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │ +│ │ Jury 3 (5 members) [→] │ │ Innovation Jury (4) [→] │ │ +│ │ Assigned to R7 + R8 │ │ Award jury │ │ +│ └─────────────────────────────┘ └─────────────────────────────┘ │ +│ │ +│ ── Sidebar: Special Awards ──────────────────────────────────────── │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ Innovation Award STAY_IN_MAIN Jury: Innovation Jury [→] │ │ +│ │ Impact Award SEPARATE_POOL Jury: Impact Jury [→] │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### Key Components + +| Component | Description | +|-----------|-------------| +| `` | 4 stat cards showing key metrics | +| `` | Horizontal timeline with round status badges | +| `` | Expanded card for the currently active round | +| `` | Grid of jury group summary cards | +| `` | List of special awards with status | + +--- + +## Competition Setup Wizard + +Replaces the old Pipeline Wizard. A multi-step form that creates the entire competition structure. + +### Wizard Steps + +``` +Step 1: Basics → Competition name, program, categories +Step 2: Round Builder → Add/reorder rounds (type picker) +Step 3: Jury Groups → Create jury groups, assign to rounds +Step 4: Submission Windows → Define file requirements per window +Step 5: Special Awards → Configure awards (optional) +Step 6: Notifications → Deadline reminders, email settings +Step 7: Review & Create → Summary of everything, create button +``` + +### Step 1: Basics + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Create Competition — Step 1 of 7: Basics │ +│ ●───○───○───○───○───○───○ │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Competition Name: │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ MOPC 2026 Competition │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ Program: [MOPC 2026 ▼] │ +│ │ +│ Category Mode: │ +│ ● Shared — Both Startups and Concepts in same flow │ +│ ○ Split — Separate finalist counts per category │ +│ │ +│ Finalist Counts: │ +│ Startups: [3 ] Concepts: [3 ] │ +│ │ +│ [ Cancel ] [ Next → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 2: Round Builder + +The core of the wizard — a drag-and-drop round sequencer. + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Create Competition — Step 2 of 7: Round Builder │ +│ ○───●───○───○───○───○───○ │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Build your competition flow by adding rounds: │ +│ │ +│ ┌────┬──────────────────────────────┬──────────────┬────────┐ │ +│ │ # │ Round │ Type │ Actions│ │ +│ ├────┼──────────────────────────────┼──────────────┼────────┤ │ +│ │ 1 │ ≡ Application Window │ INTAKE │ ✎ ✕ │ │ +│ │ 2 │ ≡ AI Screening │ FILTERING │ ✎ ✕ │ │ +│ │ 3 │ ≡ Jury 1 - Semi-finalist │ EVALUATION │ ✎ ✕ │ │ +│ │ 4 │ ≡ Semi-finalist Documents │ SUBMISSION │ ✎ ✕ │ │ +│ │ 5 │ ≡ Jury 2 - Finalist │ EVALUATION │ ✎ ✕ │ │ +│ │ 6 │ ≡ Finalist Mentoring │ MENTORING │ ✎ ✕ │ │ +│ │ 7 │ ≡ Live Finals │ LIVE_FINAL │ ✎ ✕ │ │ +│ │ 8 │ ≡ Confirm Winners │ CONFIRMATION │ ✎ ✕ │ │ +│ └────┴──────────────────────────────┴──────────────┴────────┘ │ +│ │ +│ [ + Add Round ] │ +│ │ +│ Available Round Types: │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ INTAKE │ │ FILTERING │ │ EVALUATION │ │ SUBMISSION │ │ +│ │ Collect │ │ AI screen │ │ Jury score │ │ More docs │ │ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ MENTORING │ │ LIVE_FINAL │ │ CONFIRM │ │ +│ │ Workspace │ │ Live vote │ │ Cement │ │ +│ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ [ ← Back ] [ Next → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 2: Round Config Sheet + +When clicking ✎ on a round, a sheet slides out with type-specific config: + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Configure Round: Jury 1 - Semi-finalist (EVALUATION) │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Round Name: [Jury 1 - Semi-finalist Selection ] │ +│ │ +│ ── Jury Group ──────────────────────────────────────────────── │ +│ Assign jury group: [Jury 1 ▼] [ + Create New ] │ +│ │ +│ ── Assignment ──────────────────────────────────────────────── │ +│ Reviews per project: [3 ] │ +│ (Caps and quotas configured on the jury group) │ +│ │ +│ ── Scoring ─────────────────────────────────────────────────── │ +│ Evaluation form: [Standard Criteria Form ▼] │ +│ Scoring mode: ● Criteria-based ○ Global score ○ Binary │ +│ Score range: [1 ] to [10] │ +│ │ +│ ── Document Visibility ─────────────────────────────────────── │ +│ This round can see docs from: │ +│ ☑ Window 1: Application Documents │ +│ ☐ Window 2: Semi-finalist Documents (not yet created) │ +│ │ +│ ── Advancement ─────────────────────────────────────────────── │ +│ Advancement mode: │ +│ ● Top N by score │ +│ ○ Admin selection │ +│ ○ AI recommended │ +│ Advance top: [8 ] projects per category │ +│ │ +│ ── Deadline ────────────────────────────────────────────────── │ +│ Start date: [Feb 1, 2026 ] │ +│ End date: [Mar 15, 2026] │ +│ │ +│ [ Cancel ] [ Save Round ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 3: Jury Groups + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Create Competition — Step 3 of 7: Jury Groups │ +│ ○───○───●───○───○───○───○ │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Jury 1 — Semi-finalist Selection [Edit]│ │ +│ │ Linked to: Round 3 │ │ +│ │ Members: 0 (add after creation) │ │ +│ │ Default cap: 20 (SOFT +2) │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Jury 2 — Finalist Selection [Edit]│ │ +│ │ Linked to: Round 5 │ │ +│ │ Members: 0 (add after creation) │ │ +│ │ Default cap: 15 (HARD) │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Jury 3 — Live Finals + Confirmation [Edit]│ │ +│ │ Linked to: Round 7, Round 8 │ │ +│ │ Members: 0 (add after creation) │ │ +│ │ All finalists auto-assigned │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ [ + Create Jury Group ] │ +│ │ +│ Note: Add members to jury groups after competition is created. │ +│ │ +│ [ ← Back ] [ Next → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 4: Submission Windows + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Create Competition — Step 4 of 7: Submission Windows │ +│ ○───○───○───●───○───○───○ │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Window 1: Application Documents (linked to Round 1) │ │ +│ │ │ │ +│ │ File Requirements: │ │ +│ │ 1. Executive Summary (PDF, max 5MB, required) │ │ +│ │ 2. Business Plan (PDF, max 20MB, required) │ │ +│ │ 3. Team Bios (PDF, max 5MB, required) │ │ +│ │ 4. Supporting Documents (any, max 50MB, optional) │ │ +│ │ │ │ +│ │ Deadline: Jan 31, 2026 | Policy: GRACE (30 min) │ │ +│ │ [ + Add Requirement ] [Edit] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Window 2: Semi-finalist Documents (linked to Round 4) │ │ +│ │ │ │ +│ │ File Requirements: │ │ +│ │ 1. Updated Business Plan (PDF, max 20MB, required) │ │ +│ │ 2. Video Pitch (MP4, max 500MB, required) │ │ +│ │ 3. Financial Projections (PDF/XLSX, max 10MB, required) │ │ +│ │ │ │ +│ │ Deadline: Apr 30, 2026 | Policy: HARD │ │ +│ │ [ + Add Requirement ] [Edit] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ [ + Add Submission Window ] │ +│ [ ← Back ] [ Next → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 7: Review & Create + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Create Competition — Step 7 of 7: Review │ +│ ○───○───○───○───○───○───● │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Competition: MOPC 2026 Competition │ +│ Category Mode: SHARED (3 Startups + 3 Concepts) │ +│ │ +│ Rounds (8): │ +│ 1. Application Window (INTAKE) ─── Window 1 │ +│ 2. AI Screening (FILTERING) │ +│ 3. Jury 1 (EVALUATION) ─── Jury 1 │ +│ 4. Semi-finalist Docs (SUBMISSION) ─── Window 2 │ +│ 5. Jury 2 (EVALUATION) ─── Jury 2 │ +│ 6. Mentoring (MENTORING) │ +│ 7. Live Finals (LIVE_FINAL) ─── Jury 3 │ +│ 8. Confirm Winners (CONFIRMATION) ─── Jury 3 │ +│ │ +│ Jury Groups (3): Jury 1 (0 members), Jury 2 (0), Jury 3 (0) │ +│ Submission Windows (2): Application Docs, Semi-finalist Docs │ +│ Special Awards (2): Innovation Award, Impact Award │ +│ Notifications: Reminders at 7d, 3d, 1d before deadlines │ +│ │ +│ ⚠ Add jury members after creation. │ +│ │ +│ [ ← Back ] [ Create Competition ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Round Management + +### Round Detail — Type-Specific Views + +Each round type renders a specialized detail page: + +#### INTAKE Round Detail + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Round 1: Application Window Status: ACTIVE │ +│ Type: INTAKE | Deadline: Jan 31, 2026 (16 days) │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ 127 │ │ 98 │ │ 29 │ │ +│ │ Submitted │ │ Complete │ │ Draft │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ Category Breakdown: 72 Startups | 55 Concepts │ +│ │ +│ Submission Progress (by day): │ +│ ▁▂▃▃▄▅▆▇████████████▇▇▆▅▄▃▃▂▂▁ │ +│ Jan 1 Jan 31 │ +│ │ +│ Recent Submissions: │ +│ ┌─────────────────────────────┬──────────┬──────────┬────────┐ │ +│ │ Team │ Category │ Status │ Files │ │ +│ ├─────────────────────────────┼──────────┼──────────┼────────┤ │ +│ │ OceanClean AI │ STARTUP │ Complete │ 4/4 │ │ +│ │ DeepReef Monitoring │ STARTUP │ Complete │ 3/4 │ │ +│ │ BlueTide Analytics │ CONCEPT │ Draft │ 1/4 │ │ +│ └─────────────────────────────┴──────────┴──────────┴────────┘ │ +│ │ +│ [ View All Submissions ] [ Export CSV ] [ Extend Deadline ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +#### FILTERING Round Detail + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Round 2: AI Screening Status: ACTIVE │ +│ Type: FILTERING | Auto-advance: ON │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ 98 │ │ 23 │ │ 67 │ │ +│ │ Screened │ │ Passed │ │ Failed │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────┐ │ +│ │ 8 │ │ +│ │ Flagged │ ← Require manual review │ +│ └──────────┘ │ +│ │ +│ Flagged for Review: │ +│ ┌─────────────────────────┬──────────┬──────┬─────────────┐ │ +│ │ Project │ AI Score │ Flag │ Action │ │ +│ ├─────────────────────────┼──────────┼──────┼─────────────┤ │ +│ │ WaveEnergy Solutions │ 0.55 │ EDGE │ [✓] [✗] [?] │ │ +│ │ MarineData Hub │ 0.48 │ LOW │ [✓] [✗] [?] │ │ +│ │ CoralMapper (dup?) │ 0.82 │ DUP │ [✓] [✗] [?] │ │ +│ └─────────────────────────┴──────────┴──────┴─────────────┘ │ +│ │ +│ [ View All Results ] [ Re-run AI Screening ] [ Override ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +#### EVALUATION Round Detail + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Round 3: Jury 1 — Semi-finalist Status: ACTIVE │ +│ Type: EVALUATION | Jury: Jury 1 (8 members) │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ── Evaluation Progress ─────────────────────────────────────── │ +│ █████████████████████████████████░░░░░░░░░░░░░░░ 68% │ +│ 186 / 276 evaluations complete │ +│ │ +│ Per-Juror Progress: │ +│ Dr. Martin ██████████████████████████████████████ 18/18 ✓ │ +│ Prof. Dubois██████████████████████████████░░░░░░░ 15/20 │ +│ Ms. Chen █████████████████████████████████████████ 20/20 ✓ │ +│ Dr. Patel █████████████████████░░░░░░░░░░░░░░ 12/15 │ +│ Mr. Silva ████████████████████████████████░░░░ 16/20 │ +│ Dr. Yamada ███████████████████████████████████████ 19/20 │ +│ Ms. Hansen ██████████████████████████░░░░░░░░░ 14/20 │ +│ │ +│ ── Actions ─────────────────────────────────────────────────── │ +│ [ View Assignments ] [ View Results ] [ Send Reminder ] │ +│ [ Run AI Summary ] [ Advance Top N ] [ Override Decision ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +#### LIVE_FINAL Stage Manager + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ LIVE STAGE MANAGER — Round 7: Live Finals [● RECORDING] │ +│ Status: IN_PROGRESS | Category: STARTUP │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Now Presenting: OceanClean AI │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Status: Q_AND_A │ │ +│ │ Presentation: 12:00 ✓ | Q&A: ██████░░ 6:23 / 10:00 │ │ +│ │ │ │ +│ │ [ ▶ Start Voting ] [ ⏸ Pause ] [ ⏭ Skip ] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ── Jury Votes (5 jurors) ────────────────────────────────── │ +│ Dr. Martin: ○ waiting | Prof. Dubois: ○ waiting │ +│ Ms. Chen: ○ waiting | Dr. Patel: ○ waiting │ +│ Mr. Silva: ○ waiting | │ +│ │ +│ ── Audience Votes ───────────────────────────────────────── │ +│ Registered: 142 | Voted: 0 (voting not yet open) │ +│ │ +│ ── Queue ────────────────────────────────────────────────── │ +│ ┌─────┬──────────────────────┬──────────┬───────────────┐ │ +│ │ Ord │ Project │ Category │ Status │ │ +│ ├─────┼──────────────────────┼──────────┼───────────────┤ │ +│ │ ► 1 │ OceanClean AI │ STARTUP │ Q_AND_A │ │ +│ │ 2 │ DeepReef Monitoring │ STARTUP │ WAITING │ │ +│ │ 3 │ CoralGuard │ STARTUP │ WAITING │ │ +│ └─────┴──────────────────────┴──────────┴───────────────┘ │ +│ │ +│ [ Switch to CONCEPT Window ] [ End STARTUP Window ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +#### CONFIRMATION Round Detail + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Round 8: Confirm Winners Status: ACTIVE │ +│ Type: CONFIRMATION | Jury: Jury 3 │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ STARTUP Proposal │ │ +│ │ Status: APPROVED ✓ Approvals: 5/5 │ │ +│ │ 1st: OceanClean AI (92.4) │ │ +│ │ 2nd: DeepReef (88.7) │ │ +│ │ 3rd: CoralGuard (85.1) │ │ +│ │ [ Freeze Results ] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ CONCEPT Proposal │ │ +│ │ Status: PENDING Approvals: 3/5 │ │ +│ │ 1st: BlueTide Analytics (89.2) │ │ +│ │ 2nd: MarineData Hub (84.6) │ │ +│ │ 3rd: SeaWatch (81.3) │ │ +│ │ [ Send Reminder ] [ Override ] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ Freeze All Approved ] [ Export Results PDF ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Component Architecture + +### Shared Components + +| Component | Used In | Description | +|-----------|---------|-------------| +| `` | All /competition/[id]/* pages | Left sidebar with nav links | +| `` | Dashboard, round list | Horizontal visual timeline | +| `` | Everywhere | Color-coded status chip | +| `` | Round cards, jury progress | Animated progress bar | +| `` | Round detail, dashboard | Real-time countdown to deadline | +| `` | Projects, members, assignments | Sortable, filterable table | +| `` | Filtering, evaluation, confirmation | Override modal with reason input | +| `` | Any entity detail page | Slide-out audit log viewer | +| `` | Wizard, round config | Dropdown with create-new option | + +### Page Components (type-specific) + +| Component | Round Type | Description | +|-----------|-----------|-------------| +| `` | INTAKE | Submission stats, file status, deadline | +| `` | FILTERING | AI results, flagged queue, overrides | +| `` | EVALUATION | Juror progress, assignment stats, results | +| `` | SUBMISSION | Upload progress, locked windows | +| `` | MENTORING | Workspace activity, milestone progress | +| `` | LIVE_FINAL | Full stage manager with controls | +| `` | CONFIRMATION | Proposals, approvals, freeze | + +### Dynamic Round Detail Routing + +```typescript +// src/app/(admin)/admin/competition/[id]/rounds/[roundId]/page.tsx + +export default function RoundDetailPage({ params }) { + const { data: round } = trpc.competition.getRound.useQuery({ + roundId: params.roundId, + }); + + if (!round) return ; + + // Render type-specific component based on round type + switch (round.roundType) { + case 'INTAKE': + return ; + case 'FILTERING': + return ; + case 'EVALUATION': + return ; + case 'SUBMISSION': + return ; + case 'MENTORING': + return ; + case 'LIVE_FINAL': + return ; + case 'CONFIRMATION': + return ; + } +} +``` + +--- + +## Responsive Design + +| Breakpoint | Layout | +|------------|--------| +| `< md` (mobile) | Single column. Sidebar collapses to hamburger. Tables become cards. Stage manager simplified | +| `md` - `lg` (tablet) | Two column. Sidebar always visible. Tables with horizontal scroll | +| `> lg` (desktop) | Full layout. Sidebar + content + optional side panel | + +### Mobile Stage Manager + +The live stage manager has a simplified mobile view for admins controlling from a phone: + +``` +┌─────────────────────────┐ +│ LIVE CONTROL [● REC]│ +│ │ +│ Now: OceanClean AI │ +│ Status: Q_AND_A │ +│ Timer: 6:23 / 10:00 │ +│ │ +│ ┌──────────────────────┐ │ +│ │ [ Start Voting ] │ │ +│ │ [ Pause ] │ │ +│ │ [ Skip → Next ] │ │ +│ └──────────────────────┘ │ +│ │ +│ Jury: 0/5 voted │ +│ Audience: 0/142 voted │ +│ │ +│ Next: DeepReef Monitoring│ +└─────────────────────────┘ +``` + +--- + +## Accessibility + +| Feature | Implementation | +|---------|---------------| +| **Keyboard navigation** | All actions reachable via Tab/Enter. Focus rings visible | +| **Screen reader** | Semantic HTML, `aria-label` on badges, `role="status"` on live regions | +| **Color contrast** | All text meets WCAG 2.1 AA. Status badges use icons + color | +| **Motion** | Countdown timers respect `prefers-reduced-motion` | +| **Focus management** | Dialog focus trap, return focus on close | + +--- + +## Integration with tRPC + +### Key Data-Fetching Hooks + +```typescript +// Competition dashboard +const { data: competition } = trpc.competition.getById.useQuery({ id }); +const { data: rounds } = trpc.competition.listRounds.useQuery({ competitionId: id }); +const { data: juryGroups } = trpc.juryGroup.listByCompetition.useQuery({ competitionId: id }); + +// Round detail +const { data: round } = trpc.competition.getRound.useQuery({ roundId }); +const { data: projects } = trpc.competition.getProjectsInRound.useQuery({ roundId }); +const { data: assignments } = trpc.assignment.listByRound.useQuery({ roundId }); + +// Live stage manager (with polling) +const { data: ceremonyState } = trpc.liveControl.getCeremonyState.useQuery( + { roundId }, + { refetchInterval: 1000 } // poll every second +); + +// Confirmation +const { data: proposals } = trpc.winnerConfirmation.listProposals.useQuery({ competitionId: id }); +``` + +### Mutation Patterns + +```typescript +// Advance projects after evaluation +const advance = trpc.competition.advanceProjects.useMutation({ + onSuccess: () => { + utils.competition.getRound.invalidate({ roundId }); + utils.competition.getProjectsInRound.invalidate({ roundId }); + }, +}); + +// Freeze winner proposal +const freeze = trpc.winnerConfirmation.freezeProposal.useMutation({ + onSuccess: () => { + utils.winnerConfirmation.listProposals.invalidate({ competitionId }); + toast({ title: 'Results frozen', description: 'Official results are now locked.' }); + }, +}); +``` diff --git a/docs/claude-architecture-redesign/16-jury-ui.md b/docs/claude-architecture-redesign/16-jury-ui.md new file mode 100644 index 0000000..1c0c223 --- /dev/null +++ b/docs/claude-architecture-redesign/16-jury-ui.md @@ -0,0 +1,1806 @@ +# Jury UI Redesign — Multi-Jury Member Experience + +## 1. Overview + +The Jury UI redesign transforms the jury member experience from a single-stage, single-jury model to a **multi-jury, cross-round, document-aware** system. Jury members can now belong to multiple jury groups (Jury 1, Jury 2, award juries), see documents from multiple submission windows, and manage evaluations across different rounds seamlessly. + +### Design Principles + +1. **Multi-jury awareness** — Jurors can be on multiple juries; UI must clearly separate contexts +2. **Cross-round document visibility** — Jury 2 sees Round 1 + Round 2 docs; Jury 3 sees all +3. **Deadline-driven** — Prominent countdowns, overdue warnings, grace period indicators +4. **Mobile-responsive live voting** — Live finals must work on phones/tablets +5. **Zero cognitive load** — Clear CTAs, guided workflows, no guessing what to do next +6. **Accessibility-first** — WCAG AA compliance for scoring forms, keyboard nav, screen readers + +### Key User Journeys + +| Journey | Pages Involved | Frequency | +|---------|---------------|-----------| +| **Onboarding** | `/jury/onboarding/[groupId]` | Once per jury group | +| **Daily evaluation** | Dashboard → Assignments → Evaluate | Daily during window | +| **Live finals voting** | Dashboard → Live voting interface | Once (ceremony day) | +| **Winner confirmation** | Dashboard → Confirmation review | Once (post-finals) | +| **Award voting** | Dashboard → Award evaluation | Once per award | + +--- + +## 2. Current Jury UI Audit + +### Existing Pages (in `src/app/(jury)/`) + +| File | Purpose | Issues/Limitations | +|------|---------|-------------------| +| `jury/page.tsx` | Jury dashboard | Single-stage view, no multi-jury support | +| `jury/stages/page.tsx` | Stage list | Uses old Stage/Track terminology | +| `jury/stages/[stageId]/assignments/page.tsx` | Assignment list | No jury group filtering, no cross-round docs | +| `jury/stages/[stageId]/projects/[projectId]/page.tsx` | Project detail | Single submission window only | +| `jury/stages/[stageId]/projects/[projectId]/evaluate/page.tsx` | Evaluation form | No multi-window doc access | +| `jury/stages/[stageId]/projects/[projectId]/evaluation/page.tsx` | Evaluation results | Unclear separation from evaluate | +| `jury/stages/[stageId]/live/page.tsx` | Live voting | Exists but needs enhancement | +| `jury/stages/[stageId]/compare/page.tsx` | Project comparison | Useful but no multi-doc support | +| `jury/awards/page.tsx` | Awards list | Basic list, no voting interface | +| `jury/awards/[id]/page.tsx` | Award detail | Basic detail, no evaluation form | +| `jury/learning/page.tsx` | Learning resources | Good — preserve as-is | + +### What's Missing + +| Missing Feature | Impact | +|----------------|--------| +| **Multi-jury dashboard** | Jurors on Jury 1 + Jury 2 have no way to switch context | +| **Jury group switcher** | All assignments shown together — confusing | +| **Cross-round document viewer** | Jury 2 can't see Round 1 + Round 2 docs side-by-side | +| **Onboarding flow** | No expertise selection, COI pre-declaration, preferences | +| **Grace period indicators** | Jurors don't know if they have extended deadline | +| **Winner confirmation UI** | No digital signature interface | +| **Award evaluation form** | Award voting is separate from main evaluation | +| **Deadline countdown** | No prominent timer showing time remaining | +| **Next project CTA** | No "Continue Next Evaluation" quick action | +| **Assignment filters** | Can't filter by status (pending/draft/done), category | + +--- + +## 3. Jury Dashboard — Landing Page + +### Purpose + +The jury dashboard is the **mission control** for all jury activities. It shows active jury groups, pending work, deadlines, and quick actions. + +### Route + +`/jury/dashboard` + +### Data Requirements + +```typescript +// tRPC query +const { data: dashboardData } = trpc.jury.getDashboard.useQuery(); + +type DashboardData = { + juryGroups: { + id: string; + name: string; // "Jury 1", "Jury 2", "Innovation Award Jury" + description: string; + linkedRounds: { + id: string; + name: string; // "Round 3: Semi-finalist Selection" + status: RoundStatus; + windowCloseAt: Date | null; + daysRemaining: number | null; + }[]; + stats: { + totalAssignments: number; + completed: number; + inDraft: number; + pending: number; + overdue: number; + }; + nextAction: { + type: "continue_evaluation" | "start_live_voting" | "confirm_winners" | null; + projectId?: string; + roundId?: string; + url: string; + } | null; + }[]; + + upcomingDeadlines: { + roundId: string; + roundName: string; + juryGroupName: string; + deadline: Date; + daysRemaining: number; + isGracePeriod: boolean; + }[]; + + recentActivity: { + timestamp: Date; + type: "evaluation_submitted" | "live_vote_cast" | "coi_declared" | "confirmation_approved"; + projectTitle: string; + roundName: string; + }[]; +}; +``` + +### ASCII Mockup — Multi-Jury Dashboard + +``` +┌───────────────────────────────────────────────────────────────────────────┐ +│ Jury Dashboard — Welcome, Dr. Alice Martin │ +├───────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🔔 Upcoming Deadlines │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ ⏱ Jury 1 — Semi-finalist Selection │ April 30 │ ⚠️ 3 days left │ │ +│ │ ⏱ Innovation Award Voting │ May 15 │ 18 days left │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ +│ │ +│ Your Jury Groups │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ Jury 1 — Semi-finalist Selection ACTIVE│ │ +│ │ ────────────────────────────────────────────────────────────── │ │ +│ │ Round 3: Jury 1 Evaluation │ │ +│ │ ⏱ Closes April 30 (3 days remaining) │ │ +│ │ │ │ +│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ +│ │ │ 20 │ │ 12 │ │ 3 │ │ 5 │ │ │ +│ │ │ Total │ │ Complete │ │ In Draft │ │ Pending │ │ │ +│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ +│ │ │ │ +│ │ Progress: ████████████████░░░░ 60% (12/20 complete) │ │ +│ │ │ │ +│ │ [ Continue Next Evaluation → ] [ View All Assignments ] │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ Innovation Award Jury DRAFT│ │ +│ │ ────────────────────────────────────────────────────────────── │ │ +│ │ Innovation Award Voting │ │ +│ │ ⏱ Opens May 1 (not yet started) │ │ +│ │ │ │ +│ │ Awaiting assignment │ │ +│ │ │ │ +│ │ [ View Details ] │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ +│ │ +│ Recent Activity │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ ✅ Evaluation submitted — "OceanClean AI" (Jury 1) 2 hours ago │ │ +│ │ ✅ Evaluation submitted — "DeepReef Monitor" (Jury 1) 1 day ago │ │ +│ │ 🔒 COI declared — "WaveEnergy Solutions" (Jury 1) 3 days ago │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ +└───────────────────────────────────────────────────────────────────────────┘ +``` + +### Key Elements + +1. **Deadline banner** — Sorted by urgency, red for <5 days, orange for <10 days +2. **Jury group cards** — One card per jury group the user belongs to +3. **Progress stats** — Total, completed, in-draft, pending (with visual progress bar) +4. **Next action CTA** — "Continue Next Evaluation" jumps to first pending project +5. **Grace period indicator** — Shows if juror has extended deadline +6. **Recent activity feed** — Last 5-10 actions (evaluations, COI, live votes) + +### Interactions + +| Action | Behavior | +|--------|----------| +| Click "Continue Next Evaluation" | Navigate to first PENDING assignment's evaluation page | +| Click "View All Assignments" | Navigate to `/jury/groups/[groupId]/assignments` | +| Click jury group card header | Expand/collapse card (if multiple groups) | +| Click deadline item | Navigate to associated round's assignment page | + +--- + +## 4. Jury Group Context — Switcher & Breadcrumbs + +When a juror is on multiple juries, the UI must clearly show which jury context they're in. + +### Jury Group Switcher (Global Header) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ [MOPC Logo] │ Jury: [ Jury 1 ▼ ] │ 🔔 3 │ Dr. Martin ▼ │ +└───────────────────────────────────────────────────────────────────┘ + ↓ (dropdown) + ┌─────────────────────────┐ + │ ● Jury 1 (5 pending) │ + │ ○ Innovation Award Jury │ + │ ─────────────────────── │ + │ Switch Jury Group │ + └─────────────────────────┘ +``` + +### Breadcrumbs with Jury Context + +``` +Home > Jury 1 > Assignments > OceanClean AI > Evaluate + +Home > Innovation Award Jury > Award Voting > Innovation Award +``` + +--- + +## 5. Onboarding Flow — First-Time Setup + +When a juror is added to a new jury group, they must complete onboarding before evaluating. + +### Route + +`/jury/onboarding/[juryGroupId]` + +### Onboarding Steps + +``` +Step 1: Welcome +Step 2: Your Expertise & Preferences +Step 3: Conflict of Interest Declaration +Step 4: Confirmation +``` + +### Step 1: Welcome + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Welcome to Jury 1 — Semi-finalist Selection │ +│ │ +│ You've been selected to evaluate projects for the │ +│ Monaco Ocean Protection Challenge 2026. │ +│ │ +│ What to Expect: │ +│ ──────────────────────────────────────────────────────────── │ +│ • Evaluate up to 20 projects (Startups + Concepts) │ +│ • Evaluation window: April 1 – April 30, 2026 │ +│ • Scoring based on Innovation, Feasibility, Team, Relevance │ +│ • Submit by the deadline to ensure your input counts │ +│ │ +│ Time Commitment: ~30 minutes per project │ +│ Total estimated time: ~10 hours over 30 days │ +│ │ +│ [ Get Started → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 2: Expertise & Preferences + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Your Expertise & Preferences │ +│ ────────────────────────────────────────────────────────────── │ +│ │ +│ Select your areas of expertise (used for assignment matching): │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ ☑ Marine Biology ☑ Ocean Technology │ │ +│ │ ☐ Renewable Energy ☑ Environmental Policy │ │ +│ │ ☐ Finance/Investment ☐ Social Impact │ │ +│ │ ☐ Data Science ☐ Education │ │ +│ │ ☐ Business Development ☐ Engineering │ │ +│ │ │ │ +│ │ Other: [____________________________] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Language preferences: │ +│ ☑ English ☑ French ☐ Other: [________] │ +│ │ +│ Category preference (Startups vs Concepts): │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ Startups [==========●========] Concepts │ │ +│ │ 60% Startups / 40% Concepts │ │ +│ │ │ │ +│ │ This helps us assign projects that match your interests. │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Workload preference: │ +│ ○ Standard (up to 20 projects) │ +│ ● Reduced (up to 15 projects) — I have limited availability │ +│ ○ Increased (up to 25 projects) — I can handle more │ +│ │ +│ [ ← Back ] [ Next Step → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 3: Conflict of Interest Declaration + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Conflict of Interest Declaration │ +│ ────────────────────────────────────────────────────────────── │ +│ │ +│ Please review the project list and declare any conflicts of │ +│ interest. A COI exists if you have a personal, financial, or │ +│ professional relationship with a project team. │ +│ │ +│ ┌────────────────────────────────────────────┬───────────────┐ │ +│ │ Project │ COI? │ │ +│ ├────────────────────────────────────────────┼───────────────┤ │ +│ │ OceanClean AI (Startup) │ ○ None │ │ +│ │ DeepReef Monitoring (Startup) │ ● Declare COI │ │ +│ │ CoralGuard (Concept) │ ○ None │ │ +│ │ WaveEnergy Solutions (Startup) │ ○ None │ │ +│ │ BlueCarbonHub (Concept) │ ○ None │ │ +│ │ ... (15 more) │ │ │ +│ └────────────────────────────────────────────┴───────────────┘ │ +│ │ +│ COI Details for "DeepReef Monitoring": │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ Type: [Professional ▼] │ │ +│ │ Reason: │ │ +│ │ ┌────────────────────────────────────────────────────────┐ │ │ +│ │ │ Former colleague of team lead. Worked together at │ │ │ +│ │ │ Marine Institute 2022-2023. No financial ties. │ │ │ +│ │ └────────────────────────────────────────────────────────┘ │ │ +│ │ [ ✓ Save COI] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Note: You can declare additional conflicts later if needed. │ +│ │ +│ [ ← Back ] [ Next Step → ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Step 4: Confirmation + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Ready to Begin │ +│ ────────────────────────────────────────────────────────────── │ +│ │ +│ Summary of Your Setup: │ +│ ──────────────────────────────────────────────────────────── │ +│ • Jury Group: Jury 1 — Semi-finalist Selection │ +│ • Your expertise: Marine Biology, Ocean Tech, Env. Policy │ +│ • Workload: Up to 15 projects (reduced load) │ +│ • Category preference: 60% Startups / 40% Concepts │ +│ • COI declared: 1 project (DeepReef Monitoring) │ +│ │ +│ By confirming, you agree to: │ +│ ☑ Evaluate assigned projects fairly and impartially │ +│ ☑ Complete evaluations by the deadline (April 30, 2026) │ +│ ☑ Maintain confidentiality of all submissions │ +│ ☑ Report any additional conflicts of interest as they arise │ +│ │ +│ Evaluation deadline: April 30, 2026 │ +│ Grace period: +2 days if needed (request from admin) │ +│ │ +│ [ ← Back ] [ ✓ Confirm & Start ] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +After confirmation, juror is redirected to `/jury/groups/[juryGroupId]/assignments`. + +--- + +## 6. Assignment View — Project List + +### Route + +`/jury/groups/[juryGroupId]/assignments` + +### Purpose + +Show all assigned projects for a specific jury group, with filtering, sorting, and status tracking. + +### ASCII Mockup + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Jury 1 — Semi-finalist Selection │ +│ Assignments │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ ⏱ Evaluation Window: April 1 – April 30, 2026 (3 days remaining) │ +│ │ +│ Progress: 12/20 complete (60%) ████████████████░░░░ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐│ +│ │ Filters: [All Statuses ▼] [All Categories ▼] 🔍 Search ││ +│ │ Sort by: [Status ▼] ││ +│ └─────────────────────────────────────────────────────────────────┘│ +│ │ +│ Pending (5) │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ 📦 SeaWatch Monitor │ Startup │ ⬜ Pending │ │ +│ │ Smart monitoring for reef health │ │ +│ │ [Start Evaluation] │ │ +│ ├──────────────────────────────────────────────────────────────┤ │ +│ │ 📦 TidalEnergy Pro │ Startup │ ⬜ Pending │ │ +│ │ Tidal energy harvesting system │ │ +│ │ [Start Evaluation] │ │ +│ ├──────────────────────────────────────────────────────────────┤ │ +│ │ 📦 PlasticOcean Filter │ Concept │ ⬜ Pending │ │ +│ │ Novel microplastic filtration concept │ │ +│ │ [Start Evaluation] │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ In Draft (3) │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ 📦 BlueCarbon Hub │ Concept │ ⏳ Draft │ │ +│ │ Carbon credit marketplace for ocean restoration │ │ +│ │ Last saved 2 hours ago │ │ +│ │ [Continue Evaluation] │ │ +│ ├──────────────────────────────────────────────────────────────┤ │ +│ │ 📦 CoralGuard AI │ Startup │ ⏳ Draft │ │ +│ │ AI-powered coral reef protection │ │ +│ │ Last saved 1 day ago │ │ +│ │ [Continue Evaluation] │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ Completed (12) │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ 📦 OceanClean AI │ Startup │ ✅ Submitted │ │ +│ │ AI-powered ocean debris collection robot │ │ +│ │ Submitted 2 hours ago • Score: 4.2/5.0 │ │ +│ │ [View Evaluation] │ │ +│ ├──────────────────────────────────────────────────────────────┤ │ +│ │ 📦 DeepReef Monitor │ Startup │ 🔒 COI Declared │ │ +│ │ Deep-sea reef monitoring platform │ │ +│ │ Not evaluated — conflict of interest │ │ +│ │ [View COI Details] │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ ← Back to Dashboard ] [ Export List (.csv) ] │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### Filters & Sorting + +| Filter | Options | +|--------|---------| +| **Status** | All, Pending, In Draft, Submitted, COI Declared | +| **Category** | All, Startup, Concept | +| **Search** | Text search on project title | + +| Sort By | Options | +|---------|---------| +| Status (default) | Pending → Draft → Submitted | +| Deadline proximity | Projects needing evaluation first | +| Alphabetical | A-Z by project title | +| Category | Startup first, then Concept | + +### Card Elements + +Each project card shows: +- **Title** with category badge +- **Status indicator** (⬜ Pending, ⏳ Draft, ✅ Submitted, 🔒 COI) +- **Brief description** (first 80 chars) +- **Last action timestamp** for drafts +- **Score** for submitted evaluations +- **CTA button** (Start / Continue / View) + +--- + +## 7. Evaluation Interface — Core Workflow + +### Route + +`/jury/groups/[juryGroupId]/evaluate/[projectId]` + +### Purpose + +The heart of the jury experience. Jurors review project documents, score against criteria, and submit feedback. + +### Tab Structure + +``` +[📄 Documents] [📊 Scoring] [💬 Feedback] [ℹ️ Project Info] +``` + +### ASCII Mockup — Documents Tab + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Evaluating: OceanClean AI (Startup) — Jury 1 │ +│ ───────────────────────────────────────────────────────────────────│ +│ [📄 Documents] [📊 Scoring] [💬 Feedback] [ℹ️ Project Info] │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ ── Round 1 Application Documents ───────────────────────────────── │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ 📄 Executive Summary.pdf [Download] [View] │ │ +│ │ Uploaded: March 15, 2026 • 2.3 MB │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 📄 Business Plan.pdf [Download] [View] │ │ +│ │ Uploaded: March 15, 2026 • 5.1 MB │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 📄 Technical Specifications.pdf [Download] [View] │ │ +│ │ Uploaded: March 16, 2026 • 1.8 MB │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 🎥 Pitch Video.mp4 [Download] [Play] │ │ +│ │ Uploaded: March 17, 2026 • 45 MB │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ (For Jury 2, this section would also show:) │ +│ │ +│ ── Round 2 Semi-finalist Documents ────────────────────────────────│ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ 📄 Updated Business Plan.pdf [Download] [View] │ │ +│ │ Uploaded: April 20, 2026 • 6.2 MB │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 🎥 Enhanced Pitch Video.mp4 [Download] [Play] │ │ +│ │ Uploaded: April 21, 2026 • 52 MB │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Tip: Use browser's PDF viewer for inline review, or download to │ +│ annotate locally. │ +│ │ +│ [ ← Previous Project ] [ Next Project → ] │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### ASCII Mockup — Scoring Tab (Criteria Mode) + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Evaluating: OceanClean AI (Startup) — Jury 1 │ +│ ───────────────────────────────────────────────────────────────────│ +│ [📄 Documents] [📊 Scoring] [💬 Feedback] [ℹ️ Project Info] │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ Score each criterion on a scale of 1 (Poor) to 5 (Excellent) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐│ +│ │ Innovation & Impact (30%) ││ +│ │ How novel is the solution? What is the potential ocean impact? ││ +│ │ ││ +│ │ 1 2 3 4 5 ││ +│ │ ○ ○ ○ ● ○ ││ +│ │ Poor Fair Good Very Excellent ││ +│ │ Good ││ +│ │ ││ +│ │ Notes (optional): ││ +│ │ ┌─────────────────────────────────────────────────────────────┐ ││ +│ │ │ Strong use of AI for real-time debris detection. │ ││ +│ │ │ Innovative approach but scalability uncertain. │ ││ +│ │ └─────────────────────────────────────────────────────────────┘ ││ +│ └─────────────────────────────────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐│ +│ │ Feasibility & Execution (25%) ││ +│ │ Is the plan realistic? Can the team execute? ││ +│ │ ││ +│ │ 1 2 3 4 5 ││ +│ │ ○ ○ ● ○ ○ ││ +│ │ ││ +│ │ Notes: [_________________________________________________] ││ +│ └─────────────────────────────────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐│ +│ │ Team & Expertise (25%) ││ +│ │ Does the team have the right skills and experience? ││ +│ │ ││ +│ │ 1 2 3 4 5 ││ +│ │ ○ ○ ○ ● ○ ││ +│ └─────────────────────────────────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐│ +│ │ Ocean Relevance (20%) ││ +│ │ How directly does this address ocean protection? ││ +│ │ ││ +│ │ 1 2 3 4 5 ││ +│ │ ○ ○ ○ ○ ● ││ +│ └─────────────────────────────────────────────────────────────────┘│ +│ │ +│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ +│ │ +│ Overall Score: 3.8 / 5.0 (weighted average) │ +│ │ +│ Auto-saved 5 seconds ago │ +│ │ +│ [ ← Previous Project ] [💾 Save Draft] [ Next Project → ] │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### ASCII Mockup — Feedback Tab + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Evaluating: OceanClean AI (Startup) — Jury 1 │ +│ ───────────────────────────────────────────────────────────────────│ +│ [📄 Documents] [📊 Scoring] [💬 Feedback] [ℹ️ Project Info] │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ Overall Feedback (Required) │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Provide constructive feedback on this project's strengths and │ +│ areas for improvement. This will be shared with the team. │ +│ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ Strengths: │ │ +│ │ │ │ +│ │ The AI-powered debris detection is innovative and addresses │ │ +│ │ a critical ocean pollution challenge. The team has strong │ │ +│ │ technical expertise in robotics and machine learning. │ │ +│ │ │ │ +│ │ Areas for Improvement: │ │ +│ │ │ │ +│ │ The business model lacks clarity on scalability and revenue │ │ +│ │ streams. More detail needed on how the solution will be │ │ +│ │ deployed at scale across different ocean environments. │ │ +│ │ │ │ +│ │ Recommendations: │ │ +│ │ │ │ +│ │ Consider partnerships with maritime authorities and port │ │ +│ │ operators for pilot deployments. Explore subscription model │ │ +│ │ for data insights. │ │ +│ │ │ │ +│ │ (Character count: 523 / 2000 recommended) │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Confidential Notes (Optional — NOT shared with team) │ +│ ────────────────────────────────────────────────────────────────── │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ Team lead seems overconfident. May need mentoring on market │ │ +│ │ validation. │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Auto-saved 3 seconds ago │ +│ │ +│ [ ← Previous Project ] [💾 Save Draft] [✅ Submit Evaluation] │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### Scoring Modes + +| Mode | Interface | Use Case | +|------|-----------|----------| +| **Criteria** | Multiple 1-5 scales with weights | Jury 1, Jury 2 (detailed evaluation) | +| **Global** | Single 1-10 score + feedback | Quick screening or award voting | +| **Binary** | Yes/No decision + justification | Fast filtering or pre-screening | + +### COI Declaration (Blocking Dialog) + +If juror hasn't declared COI for this project yet: + +``` +┌──────────────────────────────────────────────────┐ +│ Conflict of Interest Declaration Required │ +│ │ +│ Before evaluating "OceanClean AI", please confirm│ +│ whether you have any conflict of interest. │ +│ │ +│ A COI exists if you have a personal, financial, │ +│ or professional relationship with the team. │ +│ │ +│ ○ No conflict — I can evaluate fairly │ +│ ○ Yes, I have a conflict: │ +│ Type: [Financial ▼] │ +│ Details: [_______________________________] │ +│ │ +│ [ Submit Declaration ] │ +│ │ +│ (Cannot proceed until COI is declared) │ +└──────────────────────────────────────────────────┘ +``` + +If COI is declared, juror is redirected back to assignment list and this project is marked "COI Declared" (no evaluation). + +### Auto-Save Behavior + +- **Trigger**: Every 30 seconds while form has unsaved changes +- **Indicator**: "Auto-saved X seconds ago" in footer +- **Status**: Evaluation status remains `DRAFT` until explicit "Submit Evaluation" +- **Recovery**: If browser crashes, draft is restored on next visit + +### Submit Evaluation + +When juror clicks "Submit Evaluation": + +1. **Validation**: + - All required criteria scored + - Feedback text provided (if `requireFeedback`) + - Window is open OR juror has grace period +2. **Confirmation dialog**: + ``` + ┌─────────────────────────────────────────┐ + │ Submit Evaluation? │ + │ │ + │ Once submitted, you cannot edit this │ + │ evaluation. Please review your scores │ + │ and feedback before proceeding. │ + │ │ + │ Overall Score: 3.8 / 5.0 │ + │ Feedback: 523 characters │ + │ │ + │ [ Cancel ] [ ✓ Confirm Submit ] │ + └─────────────────────────────────────────┘ + ``` +3. **On confirm**: + - Set `Evaluation.status = SUBMITTED` + - Set `Evaluation.submittedAt = now()` + - Set `Assignment.isCompleted = true` + - Show success toast: "Evaluation submitted ✓" + - Navigate to next pending assignment OR back to assignment list + +### Navigation + +| Action | Behavior | +|--------|----------| +| Previous Project | Jump to previous assignment in list (or disabled if first) | +| Next Project | Jump to next assignment in list (or disabled if last) | +| Save Draft | Explicit save (in addition to auto-save) | +| Submit Evaluation | Validate, confirm, submit, navigate to next | +| Close | Return to assignment list | + +--- + +## 8. Live Finals Voting — Real-Time Interface + +### Route + +`/jury/live/[roundId]` + +### Purpose + +During the live finals ceremony, jury members vote in real-time as projects are presented. + +### Desktop Interface + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Live Finals — Monaco OPC 2026 │ +│ Jury 3 Voting • Connected ● │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ NOW PRESENTING │ │ +│ │ │ │ +│ │ 🏆 Project 3 of 6 (Startups) │ │ +│ │ │ │ +│ │ OceanClean AI │ │ +│ │ AI-powered ocean debris collection robot │ │ +│ │ │ │ +│ │ Team: Dr. Sarah Chen, Prof. Marc Dubois │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ ⏱ Voting Window: 2:30 remaining │ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ YOUR SCORE │ │ +│ │ │ │ +│ │ Rate this presentation (1-10): │ │ +│ │ │ │ +│ │ [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] │ │ +│ │ ● │ │ +│ │ │ │ +│ │ Quick Notes (optional): │ │ +│ │ ┌─────────────────────────────────────────────────────────┐ │ │ +│ │ │ Strong presentation. Clear value prop. Good Q&A. │ │ │ +│ │ └─────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [✓ Submit Vote] [Skip This Project] │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ +│ │ +│ Progress (Startups): │ +│ [✓] Project 1 [✓] Project 2 [●] Project 3 [ ] Project 4 │ +│ │ +│ Up Next: TidalEnergy Pro │ +│ │ +│ [ Pause Voting ] [ View All Votes ] [ Connection: ● Live ] │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### Mobile Interface + +``` +┌────────────────────────────────────────┐ +│ Live Finals — Jury 3 │ +│ ●Connected ⏱ 2:30 left │ +├────────────────────────────────────────┤ +│ │ +│ NOW PRESENTING │ +│ ──────────────────────────────────── │ +│ OceanClean AI (Project 3/6) │ +│ AI ocean debris collection │ +│ │ +│ ┌────────────────────────────────┐ │ +│ │ Rate this presentation (1-10): │ │ +│ │ │ │ +│ │ [1] [2] [3] [4] [5] │ │ +│ │ [6] [7] [8] [9] [10] │ │ +│ │ ● │ │ +│ │ │ │ +│ │ Notes: │ │ +│ │ [___________________________] │ │ +│ │ │ │ +│ │ [✓ Submit Vote] │ │ +│ │ [Skip This Project] │ │ +│ └────────────────────────────────┘ │ +│ │ +│ Progress: ██████░░░ 3/6 │ +│ Up Next: TidalEnergy Pro │ +│ │ +└────────────────────────────────────────┘ +``` + +### Key Features + +| Feature | Implementation | +|---------|---------------| +| **Real-time sync** | WebSocket or server-sent events for cursor updates | +| **Voting timer** | Countdown clock, auto-closes voting window | +| **Connection status** | ●Live / ○Reconnecting / ✕Disconnected | +| **Progress tracker** | Visual indicator of which projects have been voted on | +| **Skip option** | Juror can skip if COI or missed presentation | +| **Auto-save** | Vote draft saved before submission in case of disconnect | + +### Voting States + +```typescript +type LiveVoteStatus = + | "not_started" // Ceremony hasn't begun + | "waiting_next" // Between presentations + | "voting_open" // Current project, voting window open + | "voting_closed" // Current project, window closed + | "ceremony_ended" // All projects presented + | "deliberation"; // Post-voting discussion period +``` + +### Voting Submission Flow + +``` +1. Juror selects score (1-10) +2. (Optional) Adds quick notes +3. Clicks "Submit Vote" +4. Confirmation: "Vote submitted for OceanClean AI ✓" +5. UI shows "Vote Submitted — Waiting for next project" +6. When admin advances cursor → next project loads +``` + +### Connection Loss Handling + +``` +┌────────────────────────────────────────┐ +│ ⚠️ Connection Lost │ +│ │ +│ Attempting to reconnect... │ +│ │ +│ Your draft vote has been saved locally.│ +│ It will sync when connection restores. │ +│ │ +│ [ Try Reconnect Now ] │ +└────────────────────────────────────────┘ +``` + +--- + +## 9. Winner Confirmation — Digital Signature + +### Route + +`/jury/confirmation/[proposalId]` + +### Purpose + +After live finals, jury members review and approve the proposed winner rankings. + +### ASCII Mockup + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Winner Confirmation — Monaco OPC 2026 │ +│ Jury 3 Digital Signature │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ Please review the proposed finalist rankings and confirm. │ +│ Your digital approval is required to finalize the results. │ +│ │ +│ ── STARTUP CATEGORY ───────────────────────────────────────────── │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ 🥇 1st Place: OceanClean AI │ │ +│ │ Avg Score: 8.6 / 10.0 │ │ +│ │ Jury votes: 9, 8, 9, 8, 9 │ │ +│ │ Audience vote: 8.4 (weight: 20%) │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 🥈 2nd Place: TidalEnergy Pro │ │ +│ │ Avg Score: 8.2 / 10.0 │ │ +│ │ Jury votes: 8, 8, 9, 7, 8 │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 🥉 3rd Place: SeaWatch Monitor │ │ +│ │ Avg Score: 7.8 / 10.0 │ │ +│ │ Jury votes: 8, 7, 8, 7, 9 │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ── CONCEPT CATEGORY ───────────────────────────────────────────── │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ 🥇 1st Place: BlueCarbon Hub │ │ +│ │ Avg Score: 8.4 / 10.0 │ │ +│ │ Jury votes: 9, 8, 8, 8, 9 │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 🥈 2nd Place: CoralGuard AI │ │ +│ │ Avg Score: 8.0 / 10.0 │ │ +│ │ Jury votes: 8, 8, 7, 9, 8 │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ 🥉 3rd Place: PlasticOcean Filter │ │ +│ │ Avg Score: 7.6 / 10.0 │ │ +│ │ Jury votes: 7, 8, 7, 8, 8 │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ +│ │ +│ Your Decision: │ +│ ○ Approve these results │ +│ ○ Request changes (provide feedback below) │ +│ │ +│ Comments (optional): │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ I agree with the rankings. The scores accurately reflect the │ │ +│ │ quality of presentations. │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ☑ I certify that these rankings are fair and accurate based on │ +│ the evaluation criteria. │ +│ │ +│ Digital Signature: Dr. Alice Martin │ +│ Date: May 20, 2026 │ +│ │ +│ [ ← Back ] [ ✓ Submit Confirmation ] │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### Confirmation States + +```typescript +type ConfirmationStatus = + | "pending" // Waiting for juror response + | "approved" // Juror approved rankings + | "rejected" // Juror requested changes + | "overridden"; // Admin overrode this juror's rejection +``` + +### What Happens After Submission + +``` +If ALL jury members approve: + → WinnerProposal.status = APPROVED + → Admin can freeze results (makes them official) + +If ANY jury member rejects: + → WinnerProposal.status = REJECTED + → Admin notified + → Admin can either: + a) Adjust rankings and re-propose + b) Use override to force approval + +If admin uses override: + → WinnerProposal.status = OVERRIDDEN + → WinnerProposal.overrideMode = "FORCE_MAJORITY" or "ADMIN_DECISION" + → Results frozen with override logged in audit trail +``` + +--- + +## 10. Award Voting + +### Route + +`/jury/awards/[awardId]/vote` + +### Purpose + +For jurors on award juries (e.g., Innovation Award Jury), vote on award winners. + +### ASCII Mockup — Award Voting (PICK_WINNER Mode) + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Innovation Award — Voting │ +│ Innovation Award Jury │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ Award Description: │ +│ Recognizing the most innovative ocean technology solution with │ +│ potential for global impact. │ +│ │ +│ Voting Window: May 1 – May 15, 2026 (5 days remaining) │ +│ │ +│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ +│ │ +│ Eligible Projects (AI-screened for innovation criteria): │ +│ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ ○ OceanClean AI (Startup) │ │ +│ │ AI-powered ocean debris collection robot │ │ +│ │ Innovation Score: 9.2 / 10.0 (AI assessment) │ │ +│ │ [View Full Submission] │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ ● DeepReef Monitor (Startup) — YOUR SELECTION │ │ +│ │ Autonomous deep-sea reef monitoring platform │ │ +│ │ Innovation Score: 9.0 / 10.0 (AI assessment) │ │ +│ │ [View Full Submission] │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ ○ CoralGuard AI (Concept) │ │ +│ │ AI-powered coral reef protection system │ │ +│ │ Innovation Score: 8.8 / 10.0 (AI assessment) │ │ +│ │ [View Full Submission] │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ ○ SeaWatch Monitor (Startup) │ │ +│ │ Smart monitoring for reef health │ │ +│ │ Innovation Score: 8.5 / 10.0 (AI assessment) │ │ +│ │ [View Full Submission] │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Justification (required): │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ DeepReef Monitor represents a breakthrough in autonomous │ │ +│ │ deep-sea monitoring, enabling data collection in previously │ │ +│ │ inaccessible environments. The innovation potential is highest.│ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Auto-saved 10 seconds ago │ +│ │ +│ [ ← Back to Awards ] [💾 Save Draft] [✅ Submit Vote] │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### Award Voting Modes + +| Mode | Interface | Description | +|------|-----------|-------------| +| **PICK_WINNER** | Radio buttons, pick one | Simple winner selection | +| **RANKED** | Drag-to-reorder list | Rank top N projects (e.g., top 3) | +| **SCORED** | 1-10 score per project | Score all eligible projects | + +### Award Vote Submission + +``` +1. Juror selects winner (or ranks/scores) +2. Provides justification text +3. Clicks "Submit Vote" +4. Confirmation: "Award vote submitted ✓" +5. Status: "Your vote has been recorded. Results will be announced after voting closes." +``` + +--- + +## 11. Navigation & Information Architecture + +### Full Sitemap + +``` +/jury/ +├── dashboard (Multi-jury overview, landing page) +│ +├── groups/[juryGroupId]/ +│ ├── overview (Jury group details, progress) +│ ├── assignments (List of assigned projects) +│ ├── evaluate/[projectId] (Evaluation form) +│ └── settings (Juror preferences, COI management) +│ +├── live/[roundId] (Live finals voting) +│ +├── confirmation/[proposalId] (Winner confirmation) +│ +├── awards/ +│ ├── index (List of awards juror is on) +│ └── [awardId]/vote (Award voting form) +│ +├── onboarding/[juryGroupId] (First-time setup per jury group) +│ +├── profile (Juror profile, expertise, contact) +│ +└── learning (Resources, guides, FAQs) +``` + +### Breadcrumb Examples + +``` +Home > Jury Dashboard + +Home > Jury 1 > Assignments + +Home > Jury 1 > Assignments > OceanClean AI > Evaluate + +Home > Live Finals > Round 7 + +Home > Winner Confirmation + +Home > Awards > Innovation Award > Vote + +Home > Onboarding > Jury 2 +``` + +### Global Navigation (Header) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ [MOPC Logo] Jury: [Jury 1 ▼] | 🔔 3 | Dr. Martin ▼ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +| Element | Description | +|---------|-------------| +| **MOPC Logo** | Click → Dashboard | +| **Jury Switcher** | Dropdown to switch jury group context | +| **Notifications** | Bell icon with count → notification center | +| **User Menu** | Profile, settings, logout | + +### Footer Navigation (Minimal) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Help Center | Contact Support | Privacy | © MOPC 2026 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 12. Responsive Design — Mobile Considerations + +### Mobile Breakpoints + +| Breakpoint | Width | Adjustments | +|------------|-------|-------------| +| Desktop | ≥1024px | Full sidebar, multi-column layouts | +| Tablet | 768-1023px | Collapsed sidebar, single-column | +| Mobile | <768px | Bottom nav, stacked cards, simplified forms | + +### Mobile Dashboard + +``` +┌─────────────────────────────────┐ +│ ☰ Jury Dashboard 🔔3 [👤] │ +├─────────────────────────────────┤ +│ │ +│ Upcoming Deadlines │ +│ ┌─────────────────────────────┐ │ +│ │ ⏱ Jury 1 — 3 days left │ │ +│ │ ⏱ Innovation — 18 days │ │ +│ └─────────────────────────────┘ │ +│ │ +│ Your Jury Groups │ +│ │ +│ ┌─────────────────────────────┐ │ +│ │ Jury 1 — Semi-finalist ⚡ │ │ +│ │ ─────────────────────────── │ │ +│ │ 12/20 complete (60%) │ │ +│ │ ████████████░░░░ │ │ +│ │ [Continue Evaluation →] │ │ +│ └─────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────┐ │ +│ │ Innovation Award Jury │ │ +│ │ ─────────────────────────── │ │ +│ │ Voting opens May 1 │ │ +│ │ [View Details] │ │ +│ └─────────────────────────────┘ │ +│ │ +├─────────────────────────────────┤ +│ [🏠] [📋] [🏆] [👤] │ +└─────────────────────────────────┘ +``` + +### Mobile Evaluation Form + +``` +┌──────────────────────────────────┐ +│ ← Evaluating: OceanClean AI │ +├──────────────────────────────────┤ +│ [📄 Docs] [📊 Score] [💬 Feed] │ +├──────────────────────────────────┤ +│ Innovation & Impact (30%) │ +│ ──────────────────────────────── │ +│ 1 2 3 4 5 │ +│ ○ ○ ○ ● ○ │ +│ │ +│ Notes: │ +│ ┌──────────────────────────────┐ │ +│ │ Strong AI approach. │ │ +│ │ Scalability concerns. │ │ +│ └──────────────────────────────┘ │ +│ │ +│ Feasibility (25%) │ +│ ──────────────────────────────── │ +│ 1 2 3 4 5 │ +│ ○ ○ ● ○ ○ │ +│ │ +│ (scroll for more criteria...) │ +│ │ +├──────────────────────────────────┤ +│ Overall: 3.6/5.0 Auto-saved 5s │ +├──────────────────────────────────┤ +│ [💾 Save] [✅ Submit] [Next →] │ +└──────────────────────────────────┘ +``` + +### Mobile Live Voting + +``` +┌────────────────────────────────┐ +│ Live Finals — Jury 3 │ +│ ● Connected ⏱ 2:15 left │ +├────────────────────────────────┤ +│ NOW PRESENTING │ +│ ────────────────────────────── │ +│ OceanClean AI (3/6) │ +│ │ +│ Rate (1-10): │ +│ [1] [2] [3] [4] [5] │ +│ [6] [7] [8] [9] [10] │ +│ ● │ +│ │ +│ Notes: │ +│ ┌────────────────────────────┐ │ +│ │ Excellent presentation. │ │ +│ └────────────────────────────┘ │ +│ │ +│ [✓ Submit Vote (8)] │ +│ [Skip This Project] │ +│ │ +│ Progress: ██████░░░ 3/6 │ +│ Up Next: TidalEnergy Pro │ +└────────────────────────────────┘ +``` + +--- + +## 13. Accessibility (WCAG AA Compliance) + +### Key Requirements + +| Criterion | Implementation | +|-----------|---------------| +| **Keyboard Navigation** | All interactive elements focusable with Tab, activate with Enter/Space | +| **Screen Reader Support** | ARIA labels on all form controls, live regions for status updates | +| **Color Contrast** | 4.5:1 for text, 3:1 for UI components | +| **Focus Indicators** | Visible focus ring on all interactive elements | +| **Error Messages** | Clear, specific, associated with form fields | +| **Headings** | Semantic hierarchy (h1 > h2 > h3) | +| **Skip Links** | "Skip to main content" link at top of page | + +### Accessible Scoring Interface + +```html +

+ Innovation & Impact (30%) +

How novel is the solution? What is the potential ocean impact?

+ +
+ + + + + +
+
+``` + +### Screen Reader Announcements + +```typescript +// Auto-save feedback +
+ Evaluation auto-saved 5 seconds ago +
+ +// Evaluation submission +
+ Evaluation submitted successfully. Navigating to next project. +
+ +// Live voting timer +
+ 2 minutes 30 seconds remaining +
+``` + +### Keyboard Shortcuts + +| Key | Action | +|-----|--------| +| `Tab` / `Shift+Tab` | Navigate between fields | +| `Enter` / `Space` | Activate button, select radio/checkbox | +| `Arrow Keys` | Navigate radio groups | +| `Esc` | Close dialogs | +| `Ctrl+S` | Save draft (evaluation form) | +| `Ctrl+Enter` | Submit evaluation (when all fields valid) | + +--- + +## 14. Component Library — Reusable shadcn/ui Components + +### Core Components + +| Component | Usage | File | +|-----------|-------|------| +| `Card` | Jury group cards, project cards | `@/components/ui/card` | +| `Button` | All CTAs, form actions | `@/components/ui/button` | +| `Badge` | Status indicators, category tags | `@/components/ui/badge` | +| `Progress` | Assignment progress bars | `@/components/ui/progress` | +| `Tabs` | Document/Scoring/Feedback tabs | `@/components/ui/tabs` | +| `RadioGroup` | Scoring criteria, COI declaration | `@/components/ui/radio-group` | +| `Textarea` | Feedback fields, notes | `@/components/ui/textarea` | +| `Select` | Filters, dropdowns | `@/components/ui/select` | +| `Dialog` | COI declaration, confirmation dialogs | `@/components/ui/dialog` | +| `Toast` | Success/error notifications | `@/components/ui/toast` | +| `Skeleton` | Loading states | `@/components/ui/skeleton` | +| `Alert` | Warnings, deadlines | `@/components/ui/alert` | + +### Custom Jury Components + +```typescript +// src/components/jury/JuryGroupSwitcher.tsx +export function JuryGroupSwitcher({ + groups: JuryGroup[], + currentGroupId: string, + onSwitch: (groupId: string) => void +}) { ... } + +// src/components/jury/DeadlineCountdown.tsx +export function DeadlineCountdown({ + deadline: Date, + showGracePeriod?: boolean +}) { ... } + +// src/components/jury/AssignmentCard.tsx +export function AssignmentCard({ + assignment: Assignment, + project: Project, + onAction: () => void +}) { ... } + +// src/components/jury/EvaluationScoringForm.tsx +export function EvaluationScoringForm({ + criteria: EvaluationCriterion[], + mode: "criteria" | "global" | "binary", + onScoreChange: (scores: CriterionScores) => void +}) { ... } + +// src/components/jury/DocumentViewer.tsx +export function DocumentViewer({ + submissionWindows: SubmissionWindow[], + projectFiles: ProjectFile[] +}) { ... } + +// src/components/jury/LiveVotingInterface.tsx +export function LiveVotingInterface({ + session: LiveVotingSession, + currentProject: Project, + onVote: (score: number, notes?: string) => void +}) { ... } + +// src/components/jury/WinnerConfirmationForm.tsx +export function WinnerConfirmationForm({ + proposal: WinnerProposal, + onConfirm: (approved: boolean, comments?: string) => void +}) { ... } + +// src/components/jury/AwardVotingForm.tsx +export function AwardVotingForm({ + award: SpecialAward, + eligibleProjects: Project[], + mode: AwardScoringMode, + onVote: (vote: AwardVote) => void +}) { ... } +``` + +--- + +## 15. State Management & Data Fetching + +### tRPC Queries (React Query) + +```typescript +// Dashboard +const { data: dashboard } = trpc.jury.getDashboard.useQuery(); + +// Assignments for a jury group +const { data: assignments } = trpc.jury.getAssignments.useQuery({ + juryGroupId +}); + +// Single assignment with project and evaluation +const { data: assignment } = trpc.jury.getAssignmentDetail.useQuery({ + assignmentId +}); + +// Project files grouped by submission window +const { data: files } = trpc.jury.getProjectDocuments.useQuery({ + projectId, + roundId +}); + +// Evaluation form criteria +const { data: form } = trpc.jury.getEvaluationForm.useQuery({ + roundId +}); + +// Live voting session +const { data: liveSession } = trpc.jury.getLiveSession.useQuery({ + roundId +}, { + refetchInterval: 5000 // Poll every 5s +}); + +// Winner proposal +const { data: proposal } = trpc.jury.getWinnerProposal.useQuery({ + proposalId +}); + +// Award details and eligible projects +const { data: award } = trpc.jury.getAwardForVoting.useQuery({ + awardId +}); +``` + +### Mutations + +```typescript +// Start evaluation (creates draft Evaluation record) +const startEvaluation = trpc.jury.startEvaluation.useMutation(); + +// Auto-save evaluation draft +const autosaveEvaluation = trpc.jury.autosaveEvaluation.useMutation(); + +// Submit evaluation +const submitEvaluation = trpc.jury.submitEvaluation.useMutation(); + +// Declare COI +const declareCOI = trpc.jury.declareCOI.useMutation(); + +// Submit live vote +const submitLiveVote = trpc.jury.submitLiveVote.useMutation(); + +// Confirm winner proposal +const confirmWinners = trpc.jury.confirmWinnerProposal.useMutation(); + +// Submit award vote +const submitAwardVote = trpc.jury.submitAwardVote.useMutation(); + +// Update juror preferences (during onboarding) +const updatePreferences = trpc.jury.updatePreferences.useMutation(); +``` + +### Local State (Zustand or React Context) + +```typescript +// Current jury group context +const useJuryStore = create((set) => ({ + currentJuryGroupId: null, + setCurrentJuryGroup: (id) => set({ currentJuryGroupId: id }), +})); + +// Evaluation form draft (before auto-save) +const useEvaluationDraft = create((set) => ({ + scores: {}, + feedback: '', + updateScore: (criterion, score) => set((state) => ({ + scores: { ...state.scores, [criterion]: score } + })), + updateFeedback: (text) => set({ feedback: text }), + clearDraft: () => set({ scores: {}, feedback: '' }), +})); +``` + +--- + +## 16. Error Handling & Edge Cases + +### Evaluation Window Closed + +``` +┌─────────────────────────────────────────┐ +│ ⚠️ Evaluation Window Closed │ +│ │ +│ The deadline for Jury 1 evaluations was │ +│ April 30, 2026. You can no longer │ +│ submit new evaluations. │ +│ │ +│ If you need an extension, contact the │ +│ admin to request a grace period. │ +│ │ +│ [ Contact Admin ] [ Back to List ] │ +└─────────────────────────────────────────┘ +``` + +### Grace Period Active + +``` +┌─────────────────────────────────────────┐ +│ 🕐 Grace Period Active │ +│ │ +│ You have been granted a 2-day extension.│ +│ Your new deadline: May 2, 2026 │ +│ │ +│ [ Continue Evaluation ] │ +└─────────────────────────────────────────┘ +``` + +### COI Prevents Evaluation + +``` +┌─────────────────────────────────────────┐ +│ 🔒 Conflict of Interest Declared │ +│ │ +│ You declared a conflict of interest for │ +│ "DeepReef Monitoring" on April 5, 2026. │ +│ │ +│ Reason: Former colleague of team lead. │ +│ │ +│ You cannot evaluate this project. This │ +│ assignment has been removed from your │ +│ list and may be reassigned. │ +│ │ +│ [ ← Back to Assignments ] │ +└─────────────────────────────────────────┘ +``` + +### All Assignments Complete + +``` +┌─────────────────────────────────────────┐ +│ ✅ All Evaluations Complete! │ +│ │ +│ You have submitted evaluations for all │ +│ 20 assigned projects. Thank you! │ +│ │ +│ Next steps: │ +│ • Results will be announced May 10 │ +│ • You may be invited to live finals │ +│ │ +│ [ View Your Evaluations ] │ +│ [ Return to Dashboard ] │ +└─────────────────────────────────────────┘ +``` + +### Live Voting Not Yet Started + +``` +┌─────────────────────────────────────────┐ +│ ⏱ Live Finals Not Yet Started │ +│ │ +│ The live finals ceremony begins on: │ +│ May 20, 2026 at 18:00 CET │ +│ │ +│ This page will activate when the │ +│ ceremony starts. │ +│ │ +│ [ Set Reminder ] [ ← Dashboard ] │ +└─────────────────────────────────────────┘ +``` + +### Juror on Multiple Juries — Context Confusion + +Prevention: +- **Jury switcher** in global header (always visible) +- **Breadcrumbs** showing current jury group +- **Color-coded badges** per jury group (e.g., Jury 1 = blue, Jury 2 = green) +- **Separate assignment lists** per jury group (no mixing) + +--- + +## 17. Performance Optimizations + +### Code Splitting + +```typescript +// Lazy-load heavy components +const LiveVotingInterface = lazy(() => import('@/components/jury/LiveVotingInterface')); +const DocumentViewer = lazy(() => import('@/components/jury/DocumentViewer')); +const WinnerConfirmationForm = lazy(() => import('@/components/jury/WinnerConfirmationForm')); + +// Use Suspense with skeleton +}> + + +``` + +### Data Prefetching + +```typescript +// On dashboard mount, prefetch next assignment +useEffect(() => { + if (nextAssignmentId) { + trpcClient.jury.getAssignmentDetail.prefetch({ assignmentId: nextAssignmentId }); + } +}, [nextAssignmentId]); + +// On assignment list, prefetch first pending project +useEffect(() => { + if (firstPendingAssignmentId) { + trpcClient.jury.getAssignmentDetail.prefetch({ + assignmentId: firstPendingAssignmentId + }); + } +}, [firstPendingAssignmentId]); +``` + +### Optimistic Updates + +```typescript +// Auto-save with optimistic update +const autosave = trpc.jury.autosaveEvaluation.useMutation({ + onMutate: async (newData) => { + // Cancel outgoing refetches + await utils.jury.getEvaluation.cancel({ evaluationId }); + + // Snapshot current value + const previous = utils.jury.getEvaluation.getData({ evaluationId }); + + // Optimistically update to new value + utils.jury.getEvaluation.setData({ evaluationId }, (old) => ({ + ...old, + ...newData, + updatedAt: new Date(), + })); + + return { previous }; + }, + onError: (err, newData, context) => { + // Rollback on error + utils.jury.getEvaluation.setData({ evaluationId }, context.previous); + }, +}); +``` + +--- + +## 18. Testing Scenarios + +### Unit Tests + +```typescript +// Test evaluation form validation +describe('EvaluationScoringForm', () => { + it('requires all criteria to be scored before submission', () => { ... }); + it('calculates weighted average correctly', () => { ... }); + it('saves draft without validation', () => { ... }); +}); + +// Test deadline countdown +describe('DeadlineCountdown', () => { + it('shows days remaining when >24h left', () => { ... }); + it('shows hours remaining when <24h left', () => { ... }); + it('shows "overdue" when past deadline', () => { ... }); + it('shows grace period indicator when active', () => { ... }); +}); +``` + +### Integration Tests + +```typescript +// Test full evaluation workflow +describe('Jury Evaluation Flow', () => { + it('juror can declare COI and skip evaluation', () => { ... }); + it('juror can save draft, navigate away, and resume', () => { ... }); + it('juror can submit evaluation and see success message', () => { ... }); + it('juror cannot submit past deadline without grace period', () => { ... }); + it('auto-save triggers every 30s', () => { ... }); +}); + +// Test multi-jury context switching +describe('Multi-Jury Navigation', () => { + it('jury switcher shows all user's jury groups', () => { ... }); + it('switching jury updates assignment list', () => { ... }); + it('breadcrumbs reflect current jury context', () => { ... }); +}); +``` + +### E2E Tests (Playwright) + +```typescript +test('juror completes full evaluation from dashboard', async ({ page }) => { + await page.goto('/jury/dashboard'); + await page.click('text=Continue Next Evaluation'); + + // COI declaration + await page.click('text=No conflict'); + await page.click('text=Submit Declaration'); + + // Score criteria + await page.click('[data-criterion="innovation"] [value="4"]'); + await page.click('[data-criterion="feasibility"] [value="3"]'); + await page.click('[data-criterion="team"] [value="4"]'); + await page.click('[data-criterion="ocean-relevance"] [value="5"]'); + + // Enter feedback + await page.fill('[name="feedback"]', 'Strong innovation, feasibility needs improvement.'); + + // Submit + await page.click('text=Submit Evaluation'); + await expect(page.locator('text=Evaluation submitted')).toBeVisible(); + + // Verify navigation to next assignment + await expect(page).toHaveURL(/\/evaluate\/.+/); +}); +``` + +--- + +## 19. Migration from Current UI + +### Page Mapping + +| Current Route | New Route | Migration Notes | +|--------------|-----------|-----------------| +| `/jury/page.tsx` | `/jury/dashboard` | Add multi-jury support, deadline widget | +| `/jury/stages/page.tsx` | (remove) | Replaced by jury group overview | +| `/jury/stages/[stageId]/assignments/page.tsx` | `/jury/groups/[juryGroupId]/assignments` | Add filters, status indicators | +| `/jury/stages/[stageId]/projects/[projectId]/evaluate/page.tsx` | `/jury/groups/[juryGroupId]/evaluate/[projectId]` | Add multi-window doc viewer, COI blocking | +| `/jury/stages/[stageId]/live/page.tsx` | `/jury/live/[roundId]` | Add real-time sync, mobile UI | +| `/jury/awards/[id]/page.tsx` | `/jury/awards/[awardId]/vote` | Add voting interface | +| (new) | `/jury/confirmation/[proposalId]` | New winner confirmation page | +| (new) | `/jury/onboarding/[juryGroupId]` | New onboarding flow | + +### Data Migration + +```typescript +// Convert old stageId references to roundId +async function migrateJuryRoutes() { + // Update assignments query to use roundId + const assignments = await prisma.assignment.findMany({ + where: { userId: currentUserId }, + include: { + round: true, // was "stage" + project: true + }, + }); + + // Group by jury group instead of stage + const byJuryGroup = groupBy(assignments, 'round.juryGroupId'); + + return byJuryGroup; +} +``` + +--- + +## 20. Future Enhancements + +### Phase 2 Features + +| Feature | Description | Priority | +|---------|-------------|----------| +| **Peer review discussions** | Anonymous commenting on peer evaluations | Medium | +| **Jury chat** | Real-time chat during deliberation periods | Low | +| **Bulk evaluation** | Compare 2-3 projects side-by-side | Medium | +| **AI evaluation assistant** | AI suggests scores based on rubric | Low | +| **Evaluation templates** | Save feedback snippets for reuse | Low | +| **Mobile app** | Native iOS/Android for live voting | Medium | +| **Offline mode** | Evaluate drafts offline, sync when online | Low | +| **Evaluation analytics** | Per-juror scoring patterns, outlier detection | Medium | + +--- + +## Summary + +This Jury UI redesign transforms the jury member experience with: + +1. **Multi-jury dashboard** — Clear overview of all jury commitments +2. **Jury group switcher** — Easy context switching for jurors on multiple juries +3. **Cross-round document visibility** — Jury 2 sees Round 1 + Round 2 docs seamlessly +4. **Onboarding flow** — Expertise selection, COI pre-declaration, preferences +5. **Enhanced evaluation interface** — Tabbed document viewer, auto-save, deadline countdown +6. **Live finals voting** — Real-time mobile-responsive voting interface +7. **Winner confirmation** — Digital signature workflow for official results +8. **Award voting** — Separate interface for special award juries +9. **Accessibility-first** — WCAG AA compliance, keyboard nav, screen reader support +10. **Mobile-optimized** — Responsive design for all devices, especially live voting + +The UI is built with shadcn/ui components, tRPC for type-safe data fetching, and follows the redesigned data model with JuryGroups, Rounds, and SubmissionWindows. + +**Total Page Count**: 20+ pages across dashboard, assignments, evaluation, live voting, confirmation, awards, onboarding + +**Total Lines**: 900+ lines of comprehensive documentation diff --git a/docs/claude-architecture-redesign/17-applicant-ui.md b/docs/claude-architecture-redesign/17-applicant-ui.md new file mode 100644 index 0000000..4007d43 --- /dev/null +++ b/docs/claude-architecture-redesign/17-applicant-ui.md @@ -0,0 +1,1787 @@ +# Applicant UI Redesign + +**Document Version:** 1.0 +**Last Updated:** 2026-02-15 +**Status:** Draft — Pending Redesign Implementation + +--- + +## Table of Contents + +1. [Overview](#1-overview) +2. [Current Applicant UI Analysis](#2-current-applicant-ui-analysis) +3. [Applicant Dashboard (Main Landing)](#3-applicant-dashboard-main-landing) +4. [Application Form (INTAKE Round)](#4-application-form-intake-round) +5. [Multi-Round Submissions](#5-multi-round-submissions) +6. [Mentoring Workspace](#6-mentoring-workspace) +7. [Team Management](#7-team-management) +8. [Results & Status Tracking](#8-results--status-tracking) +9. [Navigation & Information Architecture](#9-navigation--information-architecture) +10. [Mobile Experience](#10-mobile-experience) +11. [Accessibility](#11-accessibility) +12. [Email Notifications](#12-email-notifications) +13. [API Changes](#13-api-changes) + +--- + +## 1. Overview + +The applicant experience redesign transforms the platform from a single-submission system into a **multi-round collaboration platform** where teams progress through multiple stages of document submission, receive mentoring, and track their advancement through the competition. + +### Key Transformations + +| Current System | Redesigned System | +|----------------|-------------------| +| Single submission window | Multiple submission windows across rounds | +| Basic file upload only | Document management with versioning and locking | +| Minimal mentoring (chat only) | Full mentoring workspace with file sharing and promotion | +| Static status display | Dynamic round-by-round progress tracker | +| Generic "Documents" page | Per-window submission interfaces with requirement tracking | +| No deadline management | Countdown timers, grace periods, and late submission handling | +| Limited team management | Full team collaboration features | + +### User Personas + +**Primary Persona: Team Lead (Project Submitter)** +- Coordinates team efforts across multiple submission rounds +- Manages document uploads and team member roles +- Communicates with mentor during mentoring phase +- Tracks competition progress and deadlines +- Receives notifications for all critical events + +**Secondary Persona: Team Member** +- View-only access to project details +- Can upload documents (if permitted) +- Participates in mentor workspace +- Receives team-wide notifications + +**Tertiary Persona: Advisor (Non-voting team member)** +- Can view all project materials +- Can leave internal notes +- Cannot submit on behalf of team +- Receives status updates + +--- + +## 2. Current Applicant UI Analysis + +### What Exists Today + +**Routes:** +``` +/applicant/ +├── page.tsx — Dashboard (basic) +├── documents/page.tsx — All-in-one upload page +├── mentor/page.tsx — Chat-only interface +├── team/page.tsx — Team member list +└── pipeline/ + ├── page.tsx — Pipeline status list + └── [stageId]/ + ├── status/page.tsx — Stage-specific status + └── documents/page.tsx — Stage-specific uploads +``` + +**Current Features:** +- ✅ Basic dashboard with project details +- ✅ File upload via MinIO pre-signed URLs +- ✅ Basic mentor chat (MentorMessage model) +- ✅ Team member list with roles +- ✅ Status timeline (linear) + +**Current Limitations:** +1. **Single Submission Window** — Only one INTAKE stage supported +2. **No Multi-Round Docs** — Can't request new documents from semi-finalists/finalists +3. **No Document Locking** — Previous round files remain editable +4. **No Mentoring Workspace** — Only basic chat, no file sharing +5. **No File Promotion** — Can't convert mentor files to official submissions +6. **No Deadline Countdowns** — No visual deadline tracking +7. **Static Progress Tracking** — Timeline doesn't reflect round-by-round advancement +8. **No Grace Period UI** — Late submissions handled but not surfaced to user + +--- + +## 3. Applicant Dashboard (Main Landing) + +### 3.1 Dashboard Layout + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Monaco Ocean Protection Challenge — Applicant Portal │ +│ ──────────────────────────────────────────────────────────────────────│ +│ [Dashboard] [Application] [Submissions] [Mentoring] [Team] │ +└────────────────────────────────────────────────────────────────────────┘ + +┌────────────────────────────────────────────────────────────────────────┐ +│ OceanClean AI [FINALIST] [Category: │ +│ 2026 Edition — Monaco Ocean Protection Challenge STARTUP] │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Current Round ─────────────────────────────────────────────────────┐ +│ │ +│ 📋 Round 6: Finalist Mentoring │ +│ Status: Active │ +│ ⏱ 12 days remaining until June 30, 2026 │ +│ │ +│ Action Required: │ +│ ✓ Mentor assigned: Dr. Martin Duval │ +│ → 3 unread messages from mentor │ +│ → Review updated business plan draft │ +│ │ +│ [Open Mentoring Workspace →] │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Competition Progress ──────────────────────────────────────────────┐ +│ │ +│ Round 1: Application ✓ Complete — Feb 15, 2026 │ +│ Round 2: AI Screening ✓ Passed — Mar 1, 2026 │ +│ Round 3: Jury 1 Evaluation ✓ Semi-finalist — Mar 20, 2026 │ +│ Round 4: Semi-finalist Docs ✓ Submitted — Apr 5, 2026 │ +│ Round 5: Jury 2 Evaluation ✓ Finalist — May 1, 2026 │ +│ Round 6: Mentoring ⏳ In Progress (12 days left) │ +│ Round 7: Live Finals 🔒 Not yet started │ +│ Round 8: Results 🔒 Not yet started │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Quick Actions ──────────────┬─── Notifications ──────────────────┐ +│ │ │ +│ 📁 Documents │ 💬 3 new messages from mentor │ +│ 4 submission windows │ 📅 Mentoring ends in 12 days │ +│ [Manage Files →] │ ✅ Round 4 docs approved │ +│ │ │ +│ 👥 Team │ [View All Notifications →] │ +│ 5 members │ │ +│ [Manage Team →] │ │ +│ │ │ +│ 💬 Mentor │ │ +│ Dr. Martin Duval │ │ +│ [Open Workspace →] │ │ +│ │ │ +└────────────────────────────────┴─────────────────────────────────────┘ + +┌─── Team Overview ──────────────┬─── Upcoming Deadlines ─────────────┐ +│ │ │ +│ 👑 Sarah Chen (Lead) │ June 30, 2026 │ +│ 👤 Alex Kumar (Member) │ Mentoring period ends │ +│ 👤 Maria Santos (Member) │ (12 days, 5 hours) │ +│ 👤 James Taylor (Member) │ │ +│ 🎓 Dr. Lisa Wong (Advisor) │ July 15, 2026 │ +│ │ Live Finals │ +│ [Manage Team →] │ (27 days) │ +│ │ │ +└────────────────────────────────┴─────────────────────────────────────┘ +``` + +### 3.2 Dashboard Data Requirements + +**API Call:** +```typescript +trpc.applicant.getDashboard.useQuery() +``` + +**Response Shape:** +```typescript +{ + project: { + id: string + title: string + teamName: string + status: ProjectStatus + competitionCategory: 'STARTUP' | 'BUSINESS_CONCEPT' + currentRound: { + id: string + name: string + roundType: RoundType + status: RoundStatus + windowOpenAt: DateTime + windowCloseAt: DateTime + daysRemaining: number + hoursRemaining: number + } | null + teamMembers: Array<{ + id: string + role: 'LEAD' | 'MEMBER' | 'ADVISOR' + user: { id, name, email, avatar } + }> + mentorAssignment: { + mentor: { id, name, email, expertise } + workspaceEnabled: boolean + unreadMessageCount: number + } | null + } + + competitionProgress: Array<{ + roundNumber: number + roundName: string + roundType: RoundType + status: 'complete' | 'in_progress' | 'pending' | 'locked' + state: ProjectRoundStateValue // PASSED, REJECTED, IN_PROGRESS, etc. + enteredAt: DateTime | null + exitedAt: DateTime | null + result: string | null // "Semi-finalist", "Finalist", etc. + }> + + activeTasks: Array<{ + type: 'upload_docs' | 'respond_to_mentor' | 'review_feedback' | 'complete_profile' + priority: 'high' | 'medium' | 'low' + title: string + description: string + dueDate: DateTime | null + actionUrl: string + }> + + submissionWindows: Array<{ + id: string + name: string + roundNumber: number + status: 'open' | 'closed' | 'locked' | 'upcoming' + windowOpenAt: DateTime | null + windowCloseAt: DateTime | null + isLate: boolean + requirementsFulfilled: number + requirementsTotal: number + }> + + notifications: Array<{ + id: string + type: NotificationType + title: string + message: string + createdAt: DateTime + isRead: boolean + actionUrl: string | null + }> + + upcomingDeadlines: Array<{ + date: DateTime + title: string + description: string + type: 'submission_window' | 'mentoring_end' | 'live_event' | 'other' + }> +} +``` + +### 3.3 Component Breakdown + +**Components:** +- `` — Main container +- `` — Shows active round with countdown and actions +- `` — Visual round-by-round timeline +- `` — 3-column grid of primary actions +- `` — Recent notifications with unread count +- `` — Compact team roster +- `` — Upcoming deadlines with time remaining +- `` — Actionable to-dos with priority + +--- + +## 4. Application Form (INTAKE Round) + +### 4.1 Multi-Step Form Wizard + +The initial application form is a **guided wizard** with progress tracking, draft saving, and dynamic field rendering based on competition configuration. + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Apply to Monaco Ocean Protection Challenge 2026 │ +│ ──────────────────────────────────────────────────────────────────────│ +│ Step 1 of 5: Team Information │ +│ [●════○────○────○────○] │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Team Information ───────────────────────────────────────────────────┐ +│ │ +│ Project Name * │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ OceanClean AI │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Team/Organization Name │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ OceanClean Technologies Inc. │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Project Category * │ +│ ◉ Startup (Existing company or organization) │ +│ ○ Business Concept (Idea or early-stage project) │ +│ │ +│ Primary Ocean Issue Addressed * │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ [Select issue...] ▼ │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ • Ocean plastic pollution │ +│ • Coastal ecosystem restoration │ +│ • Sustainable fishing practices │ +│ • Marine biodiversity conservation │ +│ • Climate change adaptation │ +│ │ +│ Country/Region * │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ United States ▼ │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ [Save Draft] [Back] [Next: Project Details →]│ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 4.2 Form Steps + +**Step 1: Team Information** +- Project name (required) +- Team/organization name +- Project category (Startup / Business Concept) +- Primary ocean issue +- Country/region + +**Step 2: Project Details** +- Executive summary (500 words max) +- Detailed description (1500 words max) +- Innovation summary +- Impact metrics +- Technology/approach description + +**Step 3: Team Members** +``` +┌─── Team Members ───────────────────────────────────────────────────────┐ +│ │ +│ Team Lead * │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ Name: Sarah Chen │ │ +│ │ Email: sarah@oceanclean.ai │ │ +│ │ Phone: +1 555-0123 │ │ +│ │ Role: CEO & Co-founder │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Additional Team Members │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ 👤 Alex Kumar — CTO — alex@oceanclean.ai [Remove] │ │ +│ │ 👤 Maria Santos — COO — maria@oceanclean.ai [Remove] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ [+ Add Team Member] │ +│ │ +│ Advisors (Optional) │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ 🎓 Dr. Lisa Wong — Marine Biology Expert [Remove] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ [+ Add Advisor] │ +│ │ +│ [Save Draft] [Back] [Next: Upload Documents →]│ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +**Step 4: Upload Documents** +``` +┌─── Upload Documents ───────────────────────────────────────────────────┐ +│ │ +│ Required Documents │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 📄 Executive Summary (PDF) * │ │ +│ │ A concise 2-page PDF summary of your project │ │ +│ │ Max size: 10 MB • Accepted: PDF only │ │ +│ │ │ │ +│ │ [No file selected] │ │ +│ │ [Choose File] or drag & drop here │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 📄 Business Plan (PDF) * │ │ +│ │ Complete business plan (max 20 pages) │ │ +│ │ Max size: 25 MB • Accepted: PDF only │ │ +│ │ │ │ +│ │ ✓ business-plan-v2.pdf (2.3 MB) │ │ +│ │ Uploaded 5 minutes ago [Replace] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ Optional Documents │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 🎥 Video Pitch (MP4) │ │ +│ │ 3-minute video pitch (optional but recommended) │ │ +│ │ Max size: 100 MB • Accepted: MP4, MOV │ │ +│ │ │ │ +│ │ [No file selected] │ │ +│ │ [Choose File] or drag & drop here │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ℹ️ Documents can be uploaded or replaced at any time before the │ +│ application deadline (March 31, 2026, 11:59 PM CET). │ +│ │ +│ [Save Draft] [Back] [Next: Review & Submit →]│ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +**Step 5: Review & Submit** +``` +┌─── Review & Submit ────────────────────────────────────────────────────┐ +│ │ +│ Please review your application before submitting. │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Team Information [Edit] │ │ +│ │ ──────────────────────────────────────────────────── │ │ +│ │ Project: OceanClean AI │ │ +│ │ Organization: OceanClean Technologies Inc. │ │ +│ │ Category: Startup │ │ +│ │ Ocean Issue: Ocean plastic pollution │ │ +│ │ Location: United States │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Project Details [Edit] │ │ +│ │ ──────────────────────────────────────────────────── │ │ +│ │ Executive Summary: │ │ +│ │ OceanClean AI is an autonomous underwater... │ │ +│ │ │ │ +│ │ Detailed Description: │ │ +│ │ Our solution combines computer vision... │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Team Members [Edit] │ │ +│ │ ──────────────────────────────────────────────────── │ │ +│ │ 👑 Sarah Chen (Lead) — CEO & Co-founder │ │ +│ │ 👤 Alex Kumar — CTO │ │ +│ │ 👤 Maria Santos — COO │ │ +│ │ 🎓 Dr. Lisa Wong (Advisor) — Marine Biology Expert │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Uploaded Documents [Edit] │ │ +│ │ ──────────────────────────────────────────────────── │ │ +│ │ ✓ Executive Summary (exec-summary.pdf, 1.2 MB) │ │ +│ │ ✓ Business Plan (business-plan-v2.pdf, 2.3 MB) │ │ +│ │ ✓ Video Pitch (pitch-video.mp4, 45 MB) │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ Terms & Conditions │ +│ ☑ I confirm that all information provided is accurate │ +│ ☑ I agree to the terms and conditions │ +│ ☑ I consent to GDPR data processing │ +│ │ +│ [Save Draft] [Back] [Submit Application] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 4.3 Draft Saving Functionality + +**Auto-Save (Authenticated Users):** +- Form data auto-saves every 30 seconds +- Stored in `Project.metadataJson` with `isDraft: true` +- No expiry for authenticated drafts +- Draft indicator in dashboard + +**Manual Save (Unauthenticated Users):** +- "Save Draft" button generates draft token +- Token sent via email with resume link +- Draft expires after 30 days (configurable) +- Resume via `/apply/resume?token={draftToken}` + +**Draft Resume Flow:** +```typescript +// Client loads draft +const { data: draft } = trpc.application.resumeDraft.useQuery({ draftToken }) + +// Pre-populate form +form.reset(draft.draftDataJson) + +// On submit +await trpc.application.submitDraft.mutate({ + projectId: draft.projectId, + draftToken, + data: formData +}) +``` + +### 4.4 Submission Confirmation + +**Success Screen:** +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ │ +│ ✓ Application Submitted │ +│ │ +│ Thank you for applying to Monaco Ocean Protection Challenge 2026! │ +│ │ +│ Confirmation Number: #MOPC-2026-001234 │ +│ │ +│ What Happens Next: │ +│ 1. You'll receive a confirmation email at sarah@oceanclean.ai │ +│ 2. Our team will review your application (typically 2-3 weeks) │ +│ 3. You'll be notified of the results via email and dashboard │ +│ 4. If selected, you'll advance to Round 3: Jury 1 Evaluation │ +│ │ +│ Important Dates: │ +│ • Application deadline: March 31, 2026 │ +│ • Results announced: April 15, 2026 │ +│ │ +│ You can track your application status at any time: │ +│ [Go to Applicant Dashboard →] │ +│ │ +│ Questions? Contact us at info@monaco-opc.com │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 5. Multi-Round Submissions + +### 5.1 Submissions Dashboard + +After advancing from the initial round, teams may be required to submit additional documents. Each submission window has its own interface. + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Submissions — OceanClean AI │ +│ ──────────────────────────────────────────────────────────────────────│ +│ [Dashboard] [Application] [Submissions] [Mentoring] [Team] │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Submission Rounds ──────────────────────────────────────────────────┐ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Round 1: Application Documents │ │ +│ │ Submitted: Feb 15, 2026 • Status: ✓ Approved │ │ +│ │ ─────────────────────────────────────────────────────── │ │ +│ │ 📄 Executive Summary (exec-summary.pdf) │ │ +│ │ 📄 Business Plan (business-plan.pdf) │ │ +│ │ 🎥 Video Pitch (pitch-video.mp4) │ │ +│ │ │ │ +│ │ 🔒 This submission window is locked (view only) │ │ +│ │ [View Details] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Round 4: Semi-finalist Documents 🟢 OPEN │ │ +│ │ Deadline: April 30, 2026 (18 days remaining) │ │ +│ │ ─────────────────────────────────────────────────────── │ │ +│ │ Progress: 2 of 3 required documents uploaded │ │ +│ │ │ │ +│ │ ✓ Updated Business Plan │ │ +│ │ ✓ Financial Projections │ │ +│ │ ⚠ Video Pitch — Not uploaded │ │ +│ │ │ │ +│ │ [Upload Documents →] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Round 7: Finalist Materials 🔒 LOCKED │ │ +│ │ Opens when you advance to finalist round │ │ +│ │ ─────────────────────────────────────────────────────── │ │ +│ │ This round will unlock if you advance past │ │ +│ │ Round 5: Jury 2 Evaluation │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 5.2 Submission Window Detail View + +**Route:** `/applicant/submissions/[windowId]` + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Round 4: Semi-finalist Documents │ +│ ──────────────────────────────────────────────────────────────────────│ +│ Status: 🟢 Open • Deadline: April 30, 2026, 11:59 PM CET │ +│ ⏱ 18 days, 5 hours remaining │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Progress ───────────────────────────────────────────────────────────┐ +│ │ +│ ██████████████████████░░░░░░ 2 of 3 required documents (67%) │ +│ │ +│ ✓ Updated Business Plan — Uploaded Apr 2, 2026 │ +│ ✓ Financial Projections — Uploaded Apr 3, 2026 │ +│ ⚠ Video Pitch — Not uploaded (Required) │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Required Documents ─────────────────────────────────────────────────┐ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ ✓ Updated Business Plan (PDF) * │ │ +│ │ Revise your business plan based on Jury 1 feedback │ │ +│ │ Max size: 25 MB • Accepted: PDF only │ │ +│ │ │ │ +│ │ ✓ business-plan-updated.pdf (3.2 MB) │ │ +│ │ Uploaded Apr 2, 2026 at 3:45 PM │ │ +│ │ │ │ +│ │ [View] [Replace] [Delete] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ ✓ Financial Projections (PDF/Excel) * │ │ +│ │ 3-year financial projections with assumptions │ │ +│ │ Max size: 10 MB • Accepted: PDF, XLSX │ │ +│ │ │ │ +│ │ ✓ financials-2026-2029.xlsx (1.8 MB) │ │ +│ │ Uploaded Apr 3, 2026 at 10:20 AM │ │ +│ │ │ │ +│ │ [View] [Replace] [Delete] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ ⚠ Video Pitch (MP4) * │ │ +│ │ 5-minute team pitch video for semi-finalist round │ │ +│ │ Max size: 150 MB • Accepted: MP4, MOV │ │ +│ │ │ │ +│ │ [No file uploaded] │ │ +│ │ │ │ +│ │ [Choose File] or drag & drop here │ │ +│ │ │ │ +│ │ 📹 Recording Tips: │ │ +│ │ • Use landscape orientation (16:9) │ │ +│ │ • Ensure good lighting and audio quality │ │ +│ │ • Include all team members if possible │ │ +│ │ • Stay within 5-minute time limit │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Optional Documents ─────────────────────────────────────────────────┐ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Letters of Support (PDF) │ │ +│ │ Letters from partners, advisors, or pilot customers │ │ +│ │ Max size: 5 MB per file • Accepted: PDF only │ │ +│ │ │ │ +│ │ [No files uploaded] │ │ +│ │ [Choose File] or drag & drop here │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Submission Actions ─────────────────────────────────────────────────┐ +│ │ +│ ⚠ You must upload all required documents before the deadline. │ +│ Late submissions may not be accepted. │ +│ │ +│ [Save Progress] [Mark as Complete & Submit] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 5.3 Previous Round Read-Only View + +When a submission window closes, it becomes **locked** for applicants. They can view but not modify. + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Round 1: Application Documents │ +│ ──────────────────────────────────────────────────────────────────────│ +│ Status: 🔒 Locked • Submitted: Feb 15, 2026 │ +│ Result: ✓ Approved — Advanced to Semi-finalist Round │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Submitted Documents ────────────────────────────────────────────────┐ +│ │ +│ 📄 Executive Summary │ +│ exec-summary.pdf (1.2 MB) — Uploaded Feb 15, 2026 │ +│ [Download] │ +│ │ +│ 📄 Business Plan │ +│ business-plan.pdf (2.3 MB) — Uploaded Feb 15, 2026 │ +│ [Download] │ +│ │ +│ 🎥 Video Pitch │ +│ pitch-video.mp4 (45 MB) — Uploaded Feb 15, 2026 │ +│ [Download] │ +│ │ +│ 🔒 This submission window is locked. Documents cannot be modified. │ +│ If you need to update a document, contact the competition admin. │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 5.4 Deadline & Grace Period Handling + +**Countdown Timer:** +```typescript +// Real-time countdown component + { + toast.warning('Submission deadline has passed') + router.refresh() + }} +/> +``` + +**Grace Period UI:** +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ ⚠ DEADLINE PASSED — Grace Period Active │ +│ ──────────────────────────────────────────────────────────────────────│ +│ │ +│ The submission deadline (April 30, 2026, 11:59 PM) has passed. │ +│ You are currently in the 24-hour grace period. │ +│ │ +│ Grace period ends: May 1, 2026, 11:59 PM CET │ +│ ⏱ 23 hours, 12 minutes remaining │ +│ │ +│ Late submissions will be flagged for review. │ +│ Upload your documents now to avoid disqualification. │ +│ │ +│ [Upload Documents →] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +**Late Submission Badge:** +``` +┌──────────────────────────────────────────────────────────────┐ +│ ✓ business-plan-updated.pdf (3.2 MB) 🟡 LATE │ +│ Uploaded May 1, 2026 at 2:15 PM (14 hours after deadline) │ +│ [View] [Download] │ +└──────────────────────────────────────────────────────────────┘ +``` + +--- + +## 6. Mentoring Workspace + +### 6.1 Workspace Overview + +When a MENTORING round opens, finalist teams gain access to a **private workspace** shared with their assigned mentor. + +**Route:** `/applicant/mentoring` + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Mentoring Workspace — OceanClean AI │ +│ ──────────────────────────────────────────────────────────────────────│ +│ [💬 Chat] [📁 Files] [📋 Milestones] │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Your Mentor ────────────────────────────────────────────────────────┐ +│ │ +│ 👤 Dr. Martin Duval │ +│ Expertise: Marine Biology, Ocean Technology, Sustainability │ +│ Affiliation: Monaco Ocean Institute │ +│ │ +│ Mentoring Period: June 1 – June 30, 2026 (18 days remaining) │ +│ │ +│ "I'm excited to work with you on refining your business plan and │ +│ preparing for the live finals. Let's focus on strengthening your │ +│ impact metrics and pitch delivery." │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Activity Summary ───────────────────────────────────────────────────┐ +│ │ +│ 💬 12 messages exchanged │ +│ 📁 5 files shared │ +│ ✓ 2 of 3 milestones completed │ +│ 🔔 3 unread messages from mentor │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 6.2 Chat Interface + +**Tab: Chat** + +``` +┌─── Chat with Dr. Martin Duval ─────────────────────────────────────────┐ +│ │ +│ Apr 5, 2026 │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Dr. Martin Duval 10:30 AM │ │ +│ │ Welcome! I've reviewed your business plan. Let's work │ │ +│ │ on the financial projections section. Have you │ │ +│ │ prepared updated numbers based on Jury 1 feedback? │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────┐ │ +│ │ Sarah Chen (You) 2:15 PM │ │ +│ │ Yes, we've revised the projections. I'll upload │ │ +│ │ the new file now. We focused on making the │ │ +│ │ revenue assumptions more conservative. │ │ +│ └────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Dr. Martin Duval 3:45 PM │ │ +│ │ Great! I've left comments on the file. One more │ │ +│ │ round of revisions and it should be ready for the │ │ +│ │ finals submission. │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ Apr 8, 2026 │ +│ ┌────────────────────────────────────────────────┐ │ +│ │ Sarah Chen (You) 9:00 AM │ │ +│ │ Updated the financials based on your feedback.│ │ +│ │ See the new version in the Files tab. │ │ +│ └────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Dr. Martin Duval 10:15 AM NEW │ │ +│ │ Perfect! This version is much stronger. I recommend │ │ +│ │ promoting it to your official submission. I'll leave │ │ +│ │ a note on the file. │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Dr. Martin Duval 10:20 AM NEW │ │ +│ │ Also, let's schedule a video call next week to │ │ +│ │ practice your pitch. Available Tuesday or Thursday? │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Dr. Martin Duval 11:00 AM NEW │ │ +│ │ One more thing — have you seen the pitch deck │ │ +│ │ template I uploaded? Use that format for consistency. │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ▼▼▼ Scroll to see older messages │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ Type your message... │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ [📎] [Send] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 6.3 Files Tab + +**Tab: Files** + +``` +┌─── Workspace Files ────────────────────────────────────────────────────┐ +│ │ +│ [Upload File] [Sort: Recent ▾] │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 📄 Business Plan v3.pdf │ │ +│ │ Uploaded by Sarah Chen (You) • Apr 8, 2026, 9:00 AM │ │ +│ │ 💬 2 comments │ │ +│ │ ✅ Promoted to "Round 4: Business Plan" slot │ │ +│ │ │ │ +│ │ [Download] [View Comments] [✓ Promoted] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 📊 Financial Projections 2026-2029.xlsx │ │ +│ │ Uploaded by Dr. Martin Duval (Mentor) • Apr 6, 2026 │ │ +│ │ 💬 1 comment │ │ +│ │ │ │ +│ │ [Download] [View Comments] [Promote to Submission →] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 📊 Revenue Model Template.xlsx │ │ +│ │ Uploaded by Dr. Martin Duval (Mentor) • Apr 5, 2026 │ │ +│ │ 💬 0 comments │ │ +│ │ │ │ +│ │ [Download] [Add Comment] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 📄 Business Plan v2.pdf │ │ +│ │ Uploaded by Sarah Chen (You) • Apr 5, 2026 │ │ +│ │ 💬 3 comments │ │ +│ │ │ │ +│ │ [Download] [View Comments] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 📊 Pitch Deck Template.pptx │ │ +│ │ Uploaded by Dr. Martin Duval (Mentor) • Apr 5, 2026 │ │ +│ │ 💬 1 comment │ │ +│ │ │ │ +│ │ [Download] [View Comments] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 6.4 File Detail with Comments + +**Route:** `/applicant/mentoring/file/[fileId]` + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Business Plan v3.pdf [Download] │ +│ ──────────────────────────────────────────────────────────────────────│ +│ Uploaded by Sarah Chen (You) • Apr 8, 2026, 9:00 AM │ +│ Size: 3.2 MB • Type: application/pdf │ +│ ✅ Promoted to "Round 4: Business Plan" slot on Apr 8, 2026 │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Comments ───────────────────────────────────────────────────────────┐ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Dr. Martin Duval (Mentor) Apr 8, 10:15 AM │ +│ │ Excellent work! The revenue projections are now much │ │ +│ │ more realistic and well-justified. The competitive │ │ +│ │ analysis section is particularly strong. │ │ +│ │ │ │ +│ │ This version is ready for official submission. I │ │ +│ │ recommend promoting it. │ │ +│ │ │ │ +│ │ [Reply] │ │ +│ │ │ │ +│ │ ┌────────────────────────────────────────────────┐ │ │ +│ │ │ Sarah Chen (You) Apr 8, 10:30 AM │ │ │ +│ │ │ Thank you! I've promoted this version to the │ │ │ +│ │ │ Round 4 submission. Should we also work on the │ │ │ +│ │ │ pitch deck next? │ │ │ +│ │ │ │ │ │ +│ │ │ [Reply] │ │ │ +│ │ └────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌────────────────────────────────────────────────┐ │ │ +│ │ │ Dr. Martin Duval (Mentor) Apr 8, 11:00 AM │ │ │ +│ │ │ Yes, let's do that. Use the template I shared. │ │ │ +│ │ │ │ │ │ +│ │ │ [Reply] │ │ │ +│ │ └────────────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Sarah Chen (You) Apr 8, 9:05 AM │ +│ │ Here's the updated business plan based on your │ │ +│ │ previous feedback. I've: │ │ +│ │ - Made revenue assumptions more conservative │ │ +│ │ - Added competitor analysis section │ │ +│ │ - Updated financial projections through 2029 │ │ +│ │ │ │ +│ │ [Reply] │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ Add a comment... │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ [Post Comment] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 6.5 File Promotion Flow + +**Promotion Dialog:** +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Promote File to Official Submission [✕] │ +│ ──────────────────────────────────────────────────────────────────────│ +│ │ +│ File: Business Plan v3.pdf (3.2 MB) │ +│ │ +│ Target Submission Window * │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Round 4: Semi-finalist Documents ▼ │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ Replaces Requirement Slot * │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Updated Business Plan ▼ │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ⚠ WARNING │ +│ This will replace the current file in the "Updated Business Plan" │ +│ slot with this workspace file. │ +│ │ +│ Current file: │ +│ • business-plan-updated.pdf (2.8 MB) │ +│ • Uploaded Apr 2, 2026 │ +│ │ +│ The old file will be archived but no longer visible to jurors. │ +│ │ +│ ☑ I understand this action cannot be undone without admin help │ +│ │ +│ [Cancel] [Promote & Replace File] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +**Success Toast:** +``` +┌────────────────────────────────────────────────────────────────┐ +│ ✓ File promoted successfully │ +│ "Business Plan v3.pdf" is now your official Round 4 submission │ +│ [View in Submissions →] │ +└────────────────────────────────────────────────────────────────┘ +``` + +### 6.6 Milestones Tab + +**Tab: Milestones** + +``` +┌─── Mentoring Milestones ───────────────────────────────────────────────┐ +│ │ +│ Track your progress through the mentoring period │ +│ │ +│ ✓ Initial Review Meeting │ +│ Completed Apr 5, 2026 — Discussed project scope and goals │ +│ │ +│ ✓ Business Plan Revision │ +│ Completed Apr 8, 2026 — Updated financials and market analysis │ +│ │ +│ ⏳ Pitch Deck Preparation │ +│ In Progress — Draft pitch deck for finals presentation │ +│ Due: Apr 20, 2026 │ +│ │ +│ ○ Practice Pitch Session │ +│ Not Started — Video call to rehearse finals pitch │ +│ Due: Apr 25, 2026 │ +│ │ +│ ○ Final Review │ +│ Not Started — Review all materials before live finals │ +│ Due: May 1, 2026 │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 7. Team Management + +**Route:** `/applicant/team` + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Team — OceanClean AI │ +│ ──────────────────────────────────────────────────────────────────────│ +│ Manage your team members and roles │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Team Members ───────────────────────────────────────────────────────┐ +│ │ +│ [+ Invite Team Member] │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 👑 Sarah Chen [LEAD] │ │ +│ │ sarah@oceanclean.ai │ │ +│ │ CEO & Co-founder │ │ +│ │ │ │ +│ │ Permissions: Full access (manage team, upload, submit) │ │ +│ │ Joined: Feb 15, 2026 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 👤 Alex Kumar [MEMBER] │ │ +│ │ alex@oceanclean.ai │ │ +│ │ CTO — Technology Lead │ │ +│ │ │ │ +│ │ Permissions: Can upload documents, view all materials │ │ +│ │ Joined: Feb 16, 2026 │ │ +│ │ │ │ +│ │ [Edit Role] [Remove] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 👤 Maria Santos [MEMBER] │ │ +│ │ maria@oceanclean.ai │ │ +│ │ COO — Operations Lead │ │ +│ │ │ │ +│ │ Permissions: Can upload documents, view all materials │ │ +│ │ Joined: Feb 16, 2026 │ │ +│ │ │ │ +│ │ [Edit Role] [Remove] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 👤 James Taylor [MEMBER] │ │ +│ │ james@oceanclean.ai │ │ +│ │ Product Manager │ │ +│ │ │ │ +│ │ ⏳ Invitation pending (sent Feb 20, 2026) │ │ +│ │ │ │ +│ │ [Resend Invitation] [Cancel Invitation] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 🎓 Dr. Lisa Wong [ADVISOR] │ │ +│ │ lisa.wong@university.edu │ │ +│ │ Marine Biology Expert, Ocean University │ │ +│ │ │ │ +│ │ Permissions: View-only access, can leave notes │ │ +│ │ Joined: Feb 18, 2026 │ │ +│ │ │ │ +│ │ [Edit Role] [Remove] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 7.1 Invite Team Member Dialog + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Invite Team Member [✕] │ +│ ──────────────────────────────────────────────────────────────────────│ +│ │ +│ Email Address * │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ james@oceanclean.ai │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ Full Name * │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ James Taylor │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ Role in Team │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Product Manager │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ Team Role * │ +│ ◉ Member — Can upload documents and view all materials │ +│ ○ Advisor — View-only access, can leave internal notes │ +│ │ +│ Personal Message (Optional) │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Hi James! We'd like you to join our team for the │ │ +│ │ Monaco Ocean Protection Challenge. Click the link... │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ An invitation email will be sent to james@oceanclean.ai │ +│ │ +│ [Cancel] [Send Invitation] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 8. Results & Status Tracking + +### 8.1 Round-by-Round Status View + +**Route:** `/applicant/status` + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Competition Status — OceanClean AI │ +│ ──────────────────────────────────────────────────────────────────────│ +│ Category: STARTUP • Current Status: FINALIST │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Round Results ──────────────────────────────────────────────────────┐ +│ │ +│ ✅ Round 1: Application │ +│ Feb 15, 2026 — Submitted │ +│ Result: Approved — Advanced to screening │ +│ ───────────────────────────────────────────────────────── │ +│ Your application met all requirements and was approved │ +│ for AI screening. │ +│ │ +│ ✅ Round 2: AI Screening │ +│ Mar 1, 2026 — Completed │ +│ Result: Passed — Advanced to Jury 1 Evaluation │ +│ ───────────────────────────────────────────────────────── │ +│ Your project scored 8.2/10 on AI eligibility screening. │ +│ Strengths: Innovation, impact potential, technical feasibility │ +│ │ +│ ✅ Round 3: Jury 1 Evaluation │ +│ Mar 20, 2026 — Completed │ +│ Result: SEMI-FINALIST (Top 20 of 150 projects) │ +│ ───────────────────────────────────────────────────────── │ +│ Congratulations! You've advanced to the semi-finalist round. │ +│ Jury feedback: │ +│ • Strong technical approach and innovation │ +│ • Excellent team credentials │ +│ • Consider strengthening financial projections │ +│ • Market analysis could be more detailed │ +│ │ +│ ✅ Round 4: Semi-finalist Documents │ +│ Apr 5, 2026 — Submitted │ +│ Result: Documents approved │ +│ ───────────────────────────────────────────────────────── │ +│ All required documents uploaded and verified. │ +│ │ +│ ✅ Round 5: Jury 2 Evaluation │ +│ May 1, 2026 — Completed │ +│ Result: FINALIST (Top 6 of 20 semi-finalists) │ +│ ───────────────────────────────────────────────────────── │ +│ Outstanding! You've been selected as a finalist. │ +│ Jury feedback: │ +│ • Excellent response to previous feedback │ +│ • Strong market opportunity and competitive positioning │ +│ • Financial projections are now realistic and well-justified │ +│ • Team is well-equipped to execute the plan │ +│ │ +│ ⏳ Round 6: Mentoring │ +│ In Progress — 12 days remaining │ +│ Mentor: Dr. Martin Duval │ +│ ───────────────────────────────────────────────────────── │ +│ Work with your mentor to refine your pitch and materials. │ +│ [Open Mentoring Workspace →] │ +│ │ +│ 🔒 Round 7: Live Finals │ +│ Scheduled: July 15, 2026 │ +│ Location: Monaco, Monte-Carlo │ +│ ───────────────────────────────────────────────────────── │ +│ Present your project live to jury and audience. │ +│ More details coming soon. │ +│ │ +│ 🔒 Round 8: Results │ +│ Scheduled: July 16, 2026 │ +│ ───────────────────────────────────────────────────────── │ +│ Final results announced at award ceremony. │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +### 8.2 Final Results Page + +**Route:** `/applicant/results` (visible after Round 8 closes) + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ Final Results — Monaco Ocean Protection Challenge 2026 │ +│ ──────────────────────────────────────────────────────────────────────│ +│ │ +│ 🏆 CONGRATULATIONS! 🏆 │ +│ │ +│ OceanClean AI — 2nd Place, Startup Category │ +│ │ +│ ────────────────────────────────────────────────────────────────── │ +│ │ +│ Award: €100,000 Prize + Mentorship Package │ +│ │ +│ Jury Feedback: │ +│ "OceanClean AI demonstrated exceptional innovation in autonomous │ +│ underwater plastic collection. The team's technical expertise and │ +│ clear go-to-market strategy impressed the jury. We're excited to │ +│ see this project scale to address ocean pollution globally." │ +│ │ +│ Next Steps: │ +│ 1. You will be contacted by MOPC team within 48 hours │ +│ 2. Prize disbursement process begins July 20, 2026 │ +│ 3. Mentorship program starts August 1, 2026 │ +│ │ +│ [Download Certificate] [View Press Release] [Share on Social Media] │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Special Awards ─────────────────────────────────────────────────────┐ +│ │ +│ 🌟 Innovation Award — WINNER │ +│ Awarded for: Most innovative use of AI and robotics in ocean tech │ +│ Prize: €25,000 │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ + +┌─── Competition Ranking ────────────────────────────────────────────────┐ +│ │ +│ Startup Category Final Standings: │ +│ 1. 🥇 SeaGuard Systems │ +│ 2. 🥈 OceanClean AI (You) │ +│ 3. 🥉 Coral Restore Pro │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 9. Navigation & Information Architecture + +### 9.1 Route Structure + +``` +/applicant/ +├── dashboard (/) — Main overview, progress tracker, notifications +├── application/ — Initial application form +│ ├── edit — Multi-step wizard (Steps 1-5) +│ └── review — Pre-submit review page +├── submissions/ — Multi-round document management +│ ├── [windowId] — Specific submission window upload interface +│ │ └── history — Version history per requirement +│ └── history — All submissions across all windows +├── mentoring/ — Mentoring workspace (if active) +│ ├── chat — Messages with mentor +│ ├── files — Shared workspace files +│ └── file/[fileId] — File detail with threaded comments +├── team/ — Team member management +│ ├── invite — Invite new member dialog +│ └── member/[memberId] — Member detail/edit +├── status — Round-by-round status display +├── results — Final competition results (post-Round 8) +└── notifications — Notification center +``` + +### 9.2 Navigation Component + +**Primary Navigation (Persistent Header):** +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ 🌊 MOPC Portal Sarah Chen 🔔 (3)│ +│ ──────────────────────────────────────────────────────────────────────│ +│ [Dashboard] [Submissions] [Mentoring] [Team] [Status] │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +**Mobile Navigation (Hamburger Menu):** +``` +┌─────────────────────┐ +│ ☰ Menu │ +│ ─────────────────── │ +│ 🏠 Dashboard │ +│ 📁 Submissions (2) │ +│ 💬 Mentoring (3) │ +│ 👥 Team │ +│ 📊 Status │ +│ 🔔 Notifications │ +│ ⚙️ Settings │ +│ 🚪 Sign Out │ +└─────────────────────┘ +``` + +### 9.3 Breadcrumbs + +``` +Dashboard > Submissions > Round 4: Semi-finalist Documents > Video Pitch +``` + +### 9.4 Contextual Actions + +**Floating Action Button (Mobile):** +- On Dashboard: Quick upload to active submission window +- On Submissions: Upload new document +- On Mentoring: Send message +- On Team: Invite member + +--- + +## 10. Mobile Experience + +### 10.1 Responsive Breakpoints + +| Breakpoint | Width | Layout | +|------------|-------|--------| +| Mobile | < 640px | Single column, stacked cards, hamburger menu | +| Tablet | 640px - 1024px | Two-column grid for dashboard, single-column forms | +| Desktop | > 1024px | Three-column dashboard, side-by-side forms | + +### 10.2 Mobile Dashboard + +``` +┌────────────────────────────┐ +│ ☰ OceanClean AI 🔔3 │ +│ ──────────────────────────│ +│ │ +│ ┌────────────────────────┐ │ +│ │ 📋 Current Round │ │ +│ │ Round 6: Mentoring │ │ +│ │ ⏱ 12 days left │ │ +│ │ [Open →] │ │ +│ └────────────────────────┘ │ +│ │ +│ ┌────────────────────────┐ │ +│ │ Progress │ │ +│ │ ✓ Round 1-5 Complete │ │ +│ │ ⏳ Round 6 Active │ │ +│ │ 🔒 Round 7-8 Locked │ │ +│ │ [Details →] │ │ +│ └────────────────────────┘ │ +│ │ +│ Quick Actions │ +│ ┌─────┐ ┌─────┐ ┌─────┐ │ +│ │ 📁 │ │ 👥 │ │ 💬 │ │ +│ │ Docs│ │ Team│ │Mentor│ │ +│ └─────┘ └─────┘ └─────┘ │ +│ │ +│ Notifications │ +│ 💬 3 new mentor messages │ +│ 📅 Deadline in 12 days │ +│ ✅ Round 4 docs approved │ +│ │ +└────────────────────────────┘ +``` + +### 10.3 Mobile File Upload + +``` +┌────────────────────────────┐ +│ ← Upload Document │ +│ ──────────────────────────│ +│ │ +│ Business Plan (Required) │ +│ │ +│ Max size: 25 MB │ +│ Accepted: PDF only │ +│ │ +│ ┌────────────────────────┐ │ +│ │ │ │ +│ │ Tap to Select │ │ +│ │ File │ │ +│ │ │ │ +│ │ 📱 From Device │ │ +│ │ ☁️ From Cloud │ │ +│ │ │ │ +│ └────────────────────────┘ │ +│ │ +│ OR │ +│ │ +│ [📷 Take Photo] │ +│ │ +│ ───────────────────────── │ +│ │ +│ Current File: │ +│ business-plan.pdf │ +│ 2.3 MB • Apr 2, 2026 │ +│ │ +│ [Replace] [View] │ +│ │ +└────────────────────────────┘ +``` + +--- + +## 11. Accessibility + +### 11.1 WCAG 2.1 AA Compliance + +**Keyboard Navigation:** +- All forms accessible via Tab/Shift-Tab +- File upload triggers via Enter/Space +- Skip-to-content link at top +- Focus indicators on all interactive elements + +**Screen Reader Support:** +- ARIA labels on all form fields +- `role="status"` for deadline countdowns +- `aria-live="polite"` for notification updates +- Alt text on all icons and images +- Semantic HTML (`
`, `