MOPC/MOPC-Portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Competition/Round architecture: full platform rewrite (Phases 1-9)
All checks were successful
Build and Push Docker Image / build (push) Successful in 7m45s
Details

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Matt
2026-02-15 23:04:15 +01:00
parent 9ab4717f96
commit 6ca39c976b
349 changed files with 69938 additions and 28767 deletions
Download Patch File Download Diff File Expand all files Collapse all files

360
docs/unified-architecture-redesign/13-open-questions-and-governance.md Normal file
View File

@@ -0,0 +1,360 @@
# Open Questions & Governance
## Overview
This document tracks all design decisions — resolved and remaining — and defines the governance process for the redesign. Resolved decisions are numbered for reference. Remaining questions are prioritized (P1 = must resolve before implementation, P2 = can resolve during implementation).
---
## Resolved Decisions
| # | Decision | Resolution | Resolved By |
|---|----------|------------|-------------|
| 1 | **Winner count per category** | Top N (configurable, default 3). All projects ranked within category. Podium UI for top 3. Cross-category comparison view. | User Q&A |
| 2 | **Score model for final winners** | Jury 3 live scores only for final winner determination. All-jury composite rankings available in reports/analytics. Configurable between "Jury 3 only" and "Jury 3 + audience blend" per competition. | User Q&A |
| 3 | **Cross-jury visibility** | Fully independent during active evaluation — no cross-jury score visibility. During Live Finals (R7) and Deliberation (R8), prior jury scores/feedback/notes visible to Jury 3 **if admin enables** (`showPriorJuryData` toggle). All cross-jury data available in reports section for internal analytics. | User Q&A |
| 4 | **Confirmation model** | Deliberation IS the confirmation — no separate WinnerProposal → jury sign-off → admin approval. Deliberation voting serves as jury agreement. Replaces "all jury agree + admin approval" from original flow spec. | User Q&A |
| 5 | **Deliberation modes** | Two admin-configurable modes: SINGLE_WINNER_VOTE (each juror picks one winner) and FULL_RANKING (ordinal 1st, 2nd, 3rd... aggregated via Borda count). | User Q&A |
| 6 | **Deliberation scope** | Separate per category (Startup and Concept deliberations are independent sessions). No deliberation for special awards — awards decided by their own jury/judge mechanism. | User Q&A |
| 7 | **Tie-breaking** | Multiple methods supported: runoff vote (new vote with tied projects only), admin tie-break (admin decides between tied), admin override (override entire result). All configurable per deliberation session. | User Q&A |
| 8 | **Post-deliberation flow** | Admin reviews final deliberation result → locks → ResultLock snapshot created. Unlock requires super-admin with mandatory reason. | User Q&A |
| 9 | **Soft-cap buffer** | Default +10 over the soft cap. Configurable per JuryGroup via `softCapBuffer` field. | User Q&A |
| 10 | **Startup/concept ratio** | Suggestive bias only (not deterministic). Disclosed to judges. Judges see a note like "You have been assigned primarily Startup projects based on your preference." | User Q&A |
| 11 | **Mode A pull-out** | Admin-confirmed (`routingConfirmationMode: ADMIN_CONFIRMED`). Admin must review and approve which projects are pulled from the main pool into the award pool. | User Q&A |
| 12 | **File promotion authority** | Team lead and admin can promote mentor workspace files to official submissions. Mentor can promote IF admin enables it per competition. | User Q&A |
| 13 | **Invite pre-assignment** | Both modes supported: AssignmentIntent (intent at invite time, honored by algorithm) and direct admin assignment. | User Q&A |
| 14 | **Jury absence handling** | Quorum fallback with participant status types: REQUIRED, ABSENT_EXCUSED, REPLACED, REPLACEMENT_ACTIVE. Absent-excused don't count toward quorum. Admin can replace juror or mark as excused. | User Q&A |
| 15 | **Result unlock** | Super-admin only, mandatory reason. Creates ResultUnlockEvent with audit trail. | User Q&A |
| 16 | **Jury naming** | Custom labels per program. JuryGroup has a `label` field (e.g., "Jury 1", "Selection Panel", "Live Finals Jury"). | User Q&A |
| 17 | **Judge onboarding self-service** | Judges CAN adjust their cap and category ratio preference during onboarding. Admin-configurable toggle (`allowOnboardingSelfService`) to enable/disable per JuryGroup. | Flow spec + Q&A |
| 18 | **AI ranked shortlist** | AI generates recommended ranked shortlist per category at the end of EVERY evaluation round (Jury 1, Jury 2, and any award evaluation). Admin can always override. | Flow spec + Q&A |
| 19 | **Audience vote totals** | Shown to Jury 3 during deliberation phase. Configurable reveal timing (real-time, after jury vote, at deliberation). | Flow spec + Q&A |
| 20 | **Assignment intent lifecycle** | Full lifecycle tracking: PENDING → HONORED (algorithm matched) / OVERRIDDEN (admin changed) / EXPIRED (round closed) / CANCELLED (removed). All terminal states immutable. See [04-jury-groups-and-assignment-policy.md](./04-jury-groups-and-assignment-policy.md). | Gap analysis |
| 21 | **Submission bundle state** | **REJECTED** — Per-file tracking with SubmissionWindow enforcement is simpler than a formal SubmissionBundle entity. Completeness is derived from slot requirements vs. uploaded files. See Rejected Alternatives below. | Gap analysis |
| 22 | **Purpose keys for analytics** | Optional `Round.purposeKey: String?` for analytics grouping (e.g., "jury1_selection", "semifinal_docs"). NOT a new enum — purely semantic. RoundType + label is sufficient for routing; purposeKey is for cross-competition reporting only. | Gap analysis |
| 23 | **Enhanced audit with before/after state** | `DecisionAuditLog.details` JSON field already supports before/after state. Convention: include `{ before: {...}, after: {...} }` structure for all override actions. No new DB fields needed — documented as convention. | Gap analysis |
---
## Rejected Alternatives
Design concepts from the Codex architecture plan that were evaluated and rejected in favor of simpler approaches:
| # | Concept | Source | Rejection Rationale |
|---|---------|--------|-------------------|
| R1 | **SubmissionBundle entity** | Codex docs | Added complexity without benefit. Per-file tracking with `SubmissionWindow` + slot requirements achieves the same completeness tracking. Deriving bundle state from `required slots - uploaded files` is simpler than maintaining a separate state machine. |
| R2 | **FinalConfirmation as separate step** | Codex docs | Merged into Deliberation per Decision #4. Deliberation voting IS the confirmation — a separate WinnerProposal → jury sign-off → admin approval flow added unnecessary ceremony. Admin reviews and locks the deliberation result directly. |
| R3 | **Purpose Keys as enum** | Codex docs | Made optional `String?` instead of enum (Decision #22). A fixed enum would require schema migration for each new analytics category. Free-text purposeKey with conventional values is more flexible. |
| R4 | **Jury-Stage binding** | Codex docs | JuryGroups are independent entities linked to rounds via `roundId`, not bound to stages. This allows a jury to be reused across competitions and rounds without schema changes. |
---
## Ambiguity Log
Design decisions where both approaches were viable. Documenting the trade-off for future reference:
| # | Ambiguity | Decision | Trade-Off |
|---|-----------|----------|-----------|
| A1 | **Cap enforcement: strict vs. flexible** | 3-mode system (HARD/SOFT/NONE) | More complex than binary on/off, but covers all real-world scenarios. SOFT mode with buffer is the common case. |
| A2 | **Cross-jury data visibility: always vs. configurable** | Configurable per round via `showPriorJuryData` | Default OFF prevents bias, but some programs want continuity. Toggle gives admin control. |
| A3 | **Deliberation mode: single vs. dual** | Both modes supported (SINGLE_WINNER_VOTE / FULL_RANKING) | Two code paths to maintain, but programs have genuinely different needs. Borda count for detailed ranking, simple vote for quick decisions. |
| A4 | **Document mutability: immutable vs. admin-replaceable** | Admin can replace with full provenance tracking | Trades simplicity for flexibility. Provenance chain (`replacedById`, audit log) ensures accountability. |
---
## Remaining P1 Questions (Before UI/Router Refactor)
These must be resolved before starting Phase 5 (Admin Control Plane + Participant UX):
### P1-1: Mentoring Scope
**Question**: Is mentoring available only to finalists, or configurable to include semi-finalists?
**Options**:
- A) Finalists only (simplest, matches current flow)
- B) Configurable via `MentoringConfig.eligibility` enum: FINALISTS_ONLY | SEMIFINALISTS_AND_ABOVE | CONFIGURABLE
**Impact**: Affects who sees the "Request Mentor" toggle and when mentor assignment runs.
**Current leaning**: The `MentoringConfig` already has an `eligibility` field with options. Implement B for flexibility.
---
### P1-2: Document Mutability After Lock
**Question**: Can admins replace locked (read-only) submissions from prior rounds?
**Options**:
- A) No — once a round's docs are locked, they're immutable for everyone
- B) Yes — admin can replace with full provenance (`sourceType: ADMIN_REPLACEMENT`)
**Impact**: Affects document lifecycle rules and audit requirements.
**Current leaning**: B — admin override everywhere is a guiding principle. Provenance tracking ensures accountability.
---
### P1-3: Audience Reveal Timing
**Question**: Are audience vote totals visible to Jury 3 in real time during the live event, or only when deliberation begins?
**Options**:
- A) Real-time (jury sees audience votes as they come in)
- B) After jury vote (jury submits their scores first, then audience results revealed)
- C) At deliberation start (audience results shown when deliberation session opens)
- D) Configurable via `LiveFinalConfig.audienceRevealTiming`
**Impact**: Affects whether audience votes can bias Jury 3 scoring.
**Current leaning**: D — make it configurable. Default to C (at deliberation start) to prevent audience bias on jury scores.
---
## Remaining P2 Questions (Can Resolve During Implementation)
### P2-1: Reporting Visibility
**Question**: Are per-jury compliance reports (assignment coverage, evaluation completion, etc.) visible to all program admins or super-admin only?
**Impact**: Affects report page access control.
---
### P2-2: Override Transparency
**Question**: Which override details are visible to jury users? For example, if admin overrides a judge's assignment, does the judge see "Admin assigned this project to you" or just the project appearing?
**Impact**: Affects jury dashboard messaging.
---
### P2-3: Notification Triggers
**Question**: What exact round transitions trigger applicant email notifications? (e.g., "You've advanced to the semi-finals", "Your submission window is open", "You've been selected as a finalist")
**Impact**: Affects notification service configuration.
---
### P2-4: CSV Bulk Invite
**Question**: What columns should the CSV bulk invite format include? Current thinking: name, email, role, juryGroupLabel, roundLabel, preAssignmentMode (INTENT | DIRECT), maxProjects, categoryBias.
**Impact**: Affects invite import service.
---
## Delivery Governance
### Weekly Architecture Sync
- **Who**: Backend lead, frontend lead, product owner, ops
- **When**: Weekly, 30 minutes
- **Agenda**: Phase progress, blockers, upcoming decisions, contract drift review
### Phase Gate Reviews
Each phase completion triggers a review:
1. Deliverables checklist reviewed
2. Release gate criteria verified (see [12-observability-and-release-gates.md](./12-observability-and-release-gates.md))
3. Test results reviewed
4. Any outstanding P1 questions flagged
5. Sign-off from architecture owner and product owner
### No Silent Contract Drift
After Phase 0 (Contract Freeze), any change to the following requires explicit review:
| Change Type | Approval Required |
|-------------|-------------------|
| Prisma model addition or field change | Architecture owner |
| Zod config schema modification | Architecture owner |
| RoundType enum change | Architecture owner + product owner |
| tRPC procedure signature change | Architecture owner |
| Assignment policy behavior change | Architecture owner + product owner |
| New feature flag addition | Architecture owner |
Changes are NOT blocked — they require documentation (what changed, why, impact) and sign-off.
### Evidence Package Template
Each phase gate review includes:
```
Phase [X] Evidence Package
- Date: YYYY-MM-DD
- Phase: [name]
- Status: PASS / CONDITIONAL PASS / FAIL
Deliverables:
- [ ] [deliverable 1] — status, link to PR/commit
- [ ] [deliverable 2] — status
Test Results:
- Unit: X/X passing
- Integration: X/X passing
- E2E: X/X passing
Release Gate: [A/B/C/D/E/F]
- [ ] Criterion 1 — status
- [ ] Criterion 2 — status
Open Items:
- [any blockers or deferred items]
Sign-off:
- Architecture: [name] [date]
- Product: [name] [date]
```
---
## Reference Monaco 2026 Configuration
A concrete example showing how the Monaco 2026 competition would be configured in the redesigned system:
```yaml
competition:
name: "Monaco Ocean Protection Challenge 2026"
programId: "monaco-opc-2026"
status: DRAFT
rounds:
- order: 1
label: "Application Window"
type: INTAKE
config:
deadlinePolicy: FLAG # accept late with flag
requiredDocSlots: ["executive_summary", "business_plan", "team_profile"]
- order: 2
label: "AI Eligibility Screening"
type: FILTERING
config:
aiEnabled: true
autoAdvanceEligible: false # admin reviews before advancing
- order: 3
label: "Jury 1 — Semi-Finalist Selection"
type: EVALUATION
juryGroupId: jury-1
config:
scoringRubric: { criteria: [...], maxScore: 100 }
requireFeedback: true
generateAiShortlist: true
- order: 4
label: "Semi-Finalist Documents"
type: SUBMISSION
config:
requiredDocSlots: ["updated_business_plan", "financial_projections", "impact_report"]
lockPriorRoundDocs: true
deadlinePolicy: HARD
- order: 5
label: "Jury 2 — Finalist Selection"
type: EVALUATION
juryGroupId: jury-2
config:
scoringRubric: { criteria: [...], maxScore: 100 }
requireFeedback: true
generateAiShortlist: true
showPriorJuryData: false # independent evaluation
- order: 6
label: "Finalist Mentoring"
type: MENTORING
config:
eligibility: FINALISTS_ONLY
requireMentorRequest: true
assignmentMethod: MANUAL
allowMentorPromotion: false
- order: 7
label: "Live Finals — Jury 3"
type: LIVE_FINAL
juryGroupId: jury-3
config:
audienceVotingEnabled: true
audienceRevealTiming: AT_DELIBERATION
audienceBlendWeight: 0 # jury only for scoring
showPriorJuryData: true # Jury 3 sees prior jury history
scoringMode: CRITERIA_BASED
presentationOrder: MANUAL
- order: 8
label: "Final Deliberation"
type: DELIBERATION
juryGroupId: jury-3
config:
mode: FULL_RANKING
showCollectiveRankings: true
tieBreakMethod: ADMIN_DECIDES
topN: 3
allowAdminOverride: true
juryGroups:
- label: "Jury 1"
defaultCapMode: SOFT
defaultMaxProjects: 15
softCapBuffer: 10
allowOnboardingSelfService: true
defaultCategoryBias: { STARTUP: 0.5, BUSINESS_CONCEPT: 0.5 }
- label: "Jury 2"
defaultCapMode: SOFT
defaultMaxProjects: 10
softCapBuffer: 10
allowOnboardingSelfService: true
- label: "Jury 3 — Live Finals"
defaultCapMode: NONE # all finalists reviewed
allowOnboardingSelfService: false
specialAwards:
- name: "Innovation Award"
routingMode: STAY_IN_MAIN
eligibilityMode: AI_SUGGESTED
winnerDecisionMode: JURY_VOTE
juryGroupLabel: "Innovation Award Panel"
- name: "Ocean Impact Award"
routingMode: SEPARATE_POOL
pullOutBehavior: KEEP_IN_BOTH
routingConfirmationMode: ADMIN_CONFIRMED
eligibilityMode: AI_SUGGESTED
winnerDecisionMode: SINGLE_JUDGE
singleJudgeLabel: "Impact Award Chair"
submissionWindows:
- label: "Round 1 Application Documents"
roundOrder: 1
requirements:
- slotKey: "executive_summary"
label: "Executive Summary"
required: true
acceptedTypes: ["application/pdf"]
- slotKey: "business_plan"
label: "Business Plan"
required: true
acceptedTypes: ["application/pdf"]
- slotKey: "team_profile"
label: "Team Profile"
required: true
acceptedTypes: ["application/pdf"]
- label: "Round 2 Semi-Finalist Documents"
roundOrder: 4
requirements:
- slotKey: "updated_business_plan"
label: "Updated Business Plan"
required: true
- slotKey: "financial_projections"
label: "Financial Projections"
required: true
- slotKey: "impact_report"
label: "Environmental Impact Report"
required: true
```
This configuration, when loaded into the system, would create the full Monaco 2026 competition with all 8 rounds, 3 main juries, 2 special awards, and 2 submission windows — ready for admin to set dates and invite jury members.