Competition/Round architecture: full platform rewrite (Phases 1-9)
All checks were successful
Build and Push Docker Image / build (push) Successful in 7m45s
All checks were successful
Build and Push Docker Image / build (push) Successful in 7m45s
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:
@@ -0,0 +1,146 @@
|
||||
# 01. Current Platform Architecture Audit
|
||||
|
||||
## 1) Technology Baseline
|
||||
- Frontend: Next.js App Router, role-based route groups
|
||||
- API: tRPC router composition (`src/server/routers/_app.ts`)
|
||||
- ORM/DB: Prisma + PostgreSQL (`prisma/schema.prisma`)
|
||||
- Auth: NextAuth + invitation token + onboarding + password setup flows
|
||||
- Storage: MinIO/S3-like presigned URLs for project files
|
||||
- Notifications: email + in-app notifications + reminder logs
|
||||
- AI: OpenAI-backed assignment/filtering/award eligibility/summary/mentor matching with fallback logic
|
||||
|
||||
## 2) Core Current Domain Model (As Implemented)
|
||||
|
||||
### 2.1 Stage Engine Backbone
|
||||
Current schema already includes the core stage engine building blocks:
|
||||
- `Pipeline` (program-level orchestration container)
|
||||
- `Track` (main/award/showcase branches)
|
||||
- `Stage` (typed lifecycle node)
|
||||
- `StageTransition` (graph edges with optional guards)
|
||||
- `ProjectStageState` (project position/state inside stage)
|
||||
- `Cohort` + `CohortProject` (grouping for live/selection windows)
|
||||
- `LiveProgressCursor` (live presentation pointer)
|
||||
- `OverrideAction` + `DecisionAuditLog` (decision/override evidence)
|
||||
|
||||
### 2.2 Evaluation / Assignment / Filtering / Awards / Mentorship
|
||||
The platform also has substantial supporting models:
|
||||
- Assignment & judging: `Assignment`, `Evaluation`, `EvaluationForm`, `ConflictOfInterest`, `GracePeriod`
|
||||
- Filtering: `FilteringRule`, `FilteringResult`, `FilteringJob`
|
||||
- Awards: `SpecialAward`, `AwardEligibility`, `AwardJuror`, `AwardVote`
|
||||
- Mentorship: `MentorAssignment`, `MentorMessage`, `MentorNote`, `MentorMilestone`, `MentorMilestoneCompletion`
|
||||
- Documents: `FileRequirement`, `ProjectFile`
|
||||
- Live voting: `LiveVotingSession`, `LiveVote`, `AudienceVoter`
|
||||
|
||||
### 2.3 User/Invite/Team Model
|
||||
- Users: `User` with roles, invite token, onboarding state, workload fields
|
||||
- Team: `TeamMember` links project/user and role (`LEAD`, `MEMBER`, `ADVISOR`)
|
||||
- Invitation tokens are user-level (`inviteToken`, `inviteTokenExpiresAt`), reused across admin and team invite flows
|
||||
|
||||
## 3) Current Services (Behavior Layer)
|
||||
|
||||
### 3.1 Stage Lifecycle Services
|
||||
- `stage-engine.ts`: transition validation + execution + guard evaluation
|
||||
- `stage-filtering.ts`: stage-scoped deterministic + AI banding filtering with manual queue concept
|
||||
- `stage-assignment.ts`: stage-scoped assignment preview/rebalance/coverage, workload/tag balancing
|
||||
- `live-control.ts`: live session control (cursor, queue reorder, pause/resume, cohort windows)
|
||||
- `stage-notifications.ts`: event emission + notification policy checks
|
||||
|
||||
### 3.2 AI and Automation Services
|
||||
- `ai-assignment.ts`, `smart-assignment.ts`
|
||||
- `ai-filtering.ts`
|
||||
- `award-eligibility-job.ts`, `ai-award-eligibility.ts`
|
||||
- `mentor-matching.ts`
|
||||
- `ai-evaluation-summary.ts`
|
||||
|
||||
### 3.3 Deadline/Reminder Services
|
||||
- `evaluation-reminders.ts` for stage deadline reminder windows and deduplicated reminder logs
|
||||
|
||||
## 4) Current API Surface (tRPC Router Map)
|
||||
Major routers currently include:
|
||||
|
||||
- Competition architecture: `pipeline`, `stage`, `stageFiltering`, `stageAssignment`, `cohort`, `live`, `decision`, `award`, `specialAward`
|
||||
- Judging ops: `assignment`, `evaluation`, `gracePeriod`, `filtering`
|
||||
- Project/applicant/docs: `project`, `application`, `applicant`, `file`, `project-pool`
|
||||
- Mentorship: `mentor`
|
||||
- Identity/admin ops: `user`, `program`, `settings`, `notification`, `audit`, `dashboard`
|
||||
- Platform modules: `message`, `webhook`, `learningResource`, `partner`, `tag`, imports, analytics, export
|
||||
|
||||
## 5) Current UI Surface (By Role)
|
||||
|
||||
### 5.1 Admin Surface
|
||||
- Program settings, apply settings, pipeline wizard/advanced editors
|
||||
- Project pool and project management
|
||||
- Members + invitation workflow (`/admin/members/invite`)
|
||||
- Mentors and mentorship settings
|
||||
- Awards and live/reporting pages
|
||||
|
||||
### 5.2 Applicant Surface
|
||||
- Applicant dashboard, pipeline status, stage documents, team management, mentoring page
|
||||
- Team invite/remove functionality in applicant team pages
|
||||
|
||||
### 5.3 Jury Surface
|
||||
- Stage lists, assignment lists, project review/evaluation pages, comparison, live stage pages, awards
|
||||
|
||||
### 5.4 Mentor Surface
|
||||
- Mentor dashboard, project workspaces, notes, milestones, messaging
|
||||
|
||||
### 5.5 Public/Auth Surface
|
||||
- Public application pages
|
||||
- Accept invite page, onboarding page, set password flow
|
||||
- Public live score and audience vote pages
|
||||
|
||||
## 6) Current Strengths
|
||||
1. Strong foundational stage/pipeline schema already exists.
|
||||
2. Manual override and audit models already present.
|
||||
3. AI-assisted modules are implemented with fallback paths.
|
||||
4. Live voting/session primitives already exist.
|
||||
5. File requirements + per-stage file visibility logic already exist.
|
||||
6. Team invitation and onboarding flows are functioning and integrated with email + status.
|
||||
|
||||
## 7) Current Mismatch Areas Against Monaco Flow
|
||||
|
||||
### 7.1 Stage Purpose Ambiguity
|
||||
- `StageType` is generic (`INTAKE/FILTER/EVALUATION/...`) but does not encode explicit Monaco semantics (Jury 1 vs Jury 2 vs Jury 3, Submission Round 1 vs Round 2, Final Confirmation).
|
||||
- Behavior depends heavily on `configJson` conventions and page-level interpretation.
|
||||
|
||||
### 7.2 Jury Entity Is Implicit, Not First-Class
|
||||
- Jury membership is mostly inferred from `User.role` + stage assignments.
|
||||
- The Monaco requirement for explicit overlapping juries (`Jury 1/2/3`, award juries) is not modeled as first-class reusable entities.
|
||||
|
||||
### 7.3 Assignment Policy Is Incomplete For Required Cap Semantics
|
||||
- Current assignment supports limits and balancing, but lacks formal per-judge hard/soft cap contracts with explicit buffer and exhaustion handling.
|
||||
- Category mix logic exists but not in the exact required startup/concept ratio semantics per judge + override flow.
|
||||
|
||||
### 7.4 Document Lifecycle Is Partially Structured
|
||||
- Stage-level requirements are present; previous-stage visibility exists.
|
||||
- But “submission bundles per round” and official round-level locking semantics are not consistently first-class.
|
||||
|
||||
### 7.5 Mentoring Collaboration Layer Is Not Complete
|
||||
- Messaging/notes/milestones exist.
|
||||
- Missing required private mentor-team file workspace with threaded comments + official submission promotion provenance.
|
||||
|
||||
### 7.6 Finals Confirmation Workflow Not Fully Typed
|
||||
- Live voting and cursor controls exist.
|
||||
- No dedicated final confirmation entity enforcing “all jury agree + one admin approval + result freeze lock”.
|
||||
|
||||
### 7.7 Award Mode Semantics Need Hardening
|
||||
- Awards are powerful but routing mode behavior (`pull-out` vs `dual participation`) is not represented as explicit governance policy with strict validation.
|
||||
|
||||
### 7.8 Cross-Platform Consistency Gaps
|
||||
- Critical workflows (member invite, team invite, onboarding, pre-assignment, stage visibility) are implemented across multiple modules with some duplicated logic and role assumptions.
|
||||
- This increases drift risk when competition architecture changes.
|
||||
|
||||
## 8) Complexity/Vagueness Sources
|
||||
1. Over-reliance on freeform `configJson` for core behavior.
|
||||
2. Multiple overlapping assignment/filtering router/service pathways.
|
||||
3. Legacy “round” nomenclature still appears in fields and comments while pipeline model is active.
|
||||
4. Invite/onboarding/team and assignment logic are integrated but not governed by a single “competition operating model” contract.
|
||||
5. Some stage-specific behavior depends on UI assumptions rather than centralized policy evaluation.
|
||||
|
||||
## 9) Conclusion (Current-State Summary)
|
||||
The platform is not a blank slate. It is a capable stage-engine system with substantial functionality already built. The redesign should be an **evolutionary hardening and simplification** effort:
|
||||
|
||||
- Keep what is structurally strong (pipeline/stage backbone, audit, live primitives)
|
||||
- Introduce explicit entities/policies where Monaco flow requires precision
|
||||
- Reduce ambiguity by making flow-critical contracts typed and validated
|
||||
- Unify all user-facing functions under the same stage/jury/document/decision model
|
||||
@@ -0,0 +1,285 @@
|
||||
# 02. Monaco Flow Target Architecture
|
||||
|
||||
## 1) Target Architecture Intent
|
||||
Design the competition as a **typed, policy-driven stage machine** where each step in your Monaco flow maps to an explicit stage purpose and policy contract.
|
||||
|
||||
Core idea:
|
||||
- Keep existing `Pipeline/Track/Stage` spine
|
||||
- Add explicit purpose codes and policy entities
|
||||
- Drive every major feature (invite, docs, assignment, review, mentoring, finals, confirmation) from the same stage context
|
||||
|
||||
## 2) Canonical Stage Purpose Map
|
||||
|
||||
For the main track, define explicit purpose keys (not just generic stage type):
|
||||
|
||||
1. `submission_r1_intake`
|
||||
2. `eligibility_filter`
|
||||
3. `jury1_evaluation`
|
||||
4. `submission_r2_intake`
|
||||
5. `jury2_evaluation`
|
||||
6. `finals_prep_collaboration` (mentoring layer; may be non-blocking stage or overlay policy)
|
||||
7. `jury3_live_finals`
|
||||
8. `final_confirmation`
|
||||
9. `results_publication`
|
||||
|
||||
`StageType` remains useful (`INTAKE`, `FILTER`, `EVALUATION`, `LIVE_FINAL`, `RESULTS`) but **stage purpose key is authoritative** for business behavior.
|
||||
|
||||
## 3) Actor Spaces (Target)
|
||||
|
||||
### 3.1 Applicants / Teams
|
||||
- Apply during open submission windows
|
||||
- Upload required documents for active submission stage
|
||||
- Access prior round docs read-only
|
||||
- Request mentoring (if enabled)
|
||||
- Collaborate with mentor in private file/chat workspace
|
||||
- Mark eligible mentoring file as official submission (when allowed)
|
||||
|
||||
### 3.2 Admins
|
||||
- Configure stages, deadlines, rubrics, file requirements, assignment policies
|
||||
- Trigger/monitor AI filtering and assignment
|
||||
- Override eligibility, assignments, advancement, finalist/winner outcomes
|
||||
- Run live finals controls (stage manager)
|
||||
- Perform final confirmation and official result lock
|
||||
|
||||
### 3.3 Judges
|
||||
- Belong to explicit juries (`Jury 1`, `Jury 2`, `Jury 3`, award juries)
|
||||
- Review assigned projects in active windows
|
||||
- Access prior + current docs as policy allows
|
||||
- Submit scores, feedback, notes
|
||||
- Participate in deliberation/final confirmation where required
|
||||
|
||||
### 3.4 Mentors
|
||||
- Assigned to eligible finalist teams that requested mentoring
|
||||
- Use mentor-team private workspace (chat, files, threaded comments)
|
||||
- Help refine docs; optionally approve/promote files if policy permits
|
||||
|
||||
### 3.5 Audience (Optional)
|
||||
- Votes during configured live finals windows
|
||||
- Only when enabled for stage/category/session
|
||||
|
||||
## 4) End-To-End Flow Blueprint (Mapped To Monaco)
|
||||
|
||||
## 4.1 Stage A: Submission Round 1 (`submission_r1_intake`)
|
||||
|
||||
### Inputs
|
||||
- Program application settings
|
||||
- Stage deadline and late policy
|
||||
- Required document set for round 1
|
||||
|
||||
### Runtime Rules
|
||||
- Applicant can edit/upload only while submission window policy allows
|
||||
- Late behavior from policy:
|
||||
- strict cutoff
|
||||
- accepted as late with flag
|
||||
- accepted in grace window only
|
||||
- Admin can always inspect and intervene
|
||||
|
||||
### Outputs
|
||||
- Project classified as `STARTUP` or `BUSINESS_CONCEPT`
|
||||
- Round 1 submission bundle + metadata + late flag
|
||||
|
||||
## 4.2 Stage B: AI Eligibility Filter (`eligibility_filter`)
|
||||
|
||||
### Inputs
|
||||
- Eligible candidate pool from Stage A
|
||||
- Deterministic rules + AI criteria text + confidence thresholds
|
||||
|
||||
### Runtime Rules
|
||||
- Deterministic checks first, then AI evaluation (if enabled)
|
||||
- Outcome buckets:
|
||||
- `eligible`
|
||||
- `ineligible`
|
||||
- `manual_review`
|
||||
- Admin override always allowed with reason code + audit
|
||||
|
||||
### Outputs
|
||||
- Eligible pool for Jury 1
|
||||
- Ineligible pool retained and visible to admins with evidence
|
||||
|
||||
## 4.3 Stage C: Jury 1 Evaluation (`jury1_evaluation`)
|
||||
|
||||
### Inputs
|
||||
- Jury 1 membership
|
||||
- Assignment policy per juror (cap mode, cap value, soft buffer, category-bias preference)
|
||||
- Rubric/version and deadline window
|
||||
|
||||
### Runtime Rules
|
||||
- Assignment engine obeys per-judge policies:
|
||||
- hard cap: never exceed cap
|
||||
- soft cap: target cap, may go to cap+buffer
|
||||
- Startup/concept ratio is treated as a **soft bias** for fair distribution, not a deterministic constraint
|
||||
- Jury onboarding must clearly state that ratio preference is a suggestion, not a hard rule
|
||||
- After all soft-cap judges reach cap+buffer:
|
||||
- unassigned projects move to manual assignment queue
|
||||
- Judges see countdown, project list, round 1 documents
|
||||
- Submit score, feedback, notes
|
||||
|
||||
### Outputs
|
||||
- Ranking and distribution views per category
|
||||
- AI recommended shortlist per category
|
||||
- Admin final advancement decision -> Semi-finalists
|
||||
|
||||
## 4.4 Stage D: Submission Round 2 (`submission_r2_intake`)
|
||||
|
||||
### Inputs
|
||||
- Semi-finalists selected from Stage C
|
||||
- New round 2 document requirements
|
||||
|
||||
### Runtime Rules
|
||||
- Applicant edits only round 2 requirements
|
||||
- Round 1 docs are read-only for applicants
|
||||
- Judges/admin can see both bundles (with clear labeling)
|
||||
- Admin retains full document management authority across rounds
|
||||
|
||||
### Outputs
|
||||
- Round 1 locked bundle + Round 2 final bundle per semi-finalist
|
||||
|
||||
## 4.5 Stage E: Jury 2 Evaluation (`jury2_evaluation`)
|
||||
|
||||
### Inputs
|
||||
- Jury 2 membership + assignment policies
|
||||
- Access to round 1 + round 2 docs
|
||||
- Special award governance configuration
|
||||
|
||||
### Runtime Rules
|
||||
- Same assignment controls as Jury 1
|
||||
- Judges score and annotate
|
||||
- Special awards run in configured mode:
|
||||
- mode A: separate pool (optional pull-out, admin-confirmed)
|
||||
- mode B: dual eligibility while staying in main pool
|
||||
- Award juries can overlap with main juries
|
||||
- Some awards can run in single-judge decision mode (award master / designated judge)
|
||||
- Admin can override finalist recommendations
|
||||
|
||||
### Outputs
|
||||
- Finalists per category
|
||||
- Award shortlist/winners progression state per award policy
|
||||
|
||||
## 4.6 Stage F: Mentoring Collaboration Layer (`finals_prep_collaboration` overlay)
|
||||
|
||||
This is a collaboration layer, not a judging gate.
|
||||
|
||||
### Inputs
|
||||
- Finalists requesting mentoring
|
||||
- Mentor assignments
|
||||
|
||||
### Runtime Rules
|
||||
- Private mentor-team workspace:
|
||||
- messaging/chat
|
||||
- file upload by mentor/team
|
||||
- threaded file comments
|
||||
- Promotion to official submission supported where policy allows:
|
||||
- promotion authority: team lead and admin
|
||||
- create provenance record (who, when, source file, target requirement)
|
||||
- keep immutable audit trail
|
||||
|
||||
### Outputs
|
||||
- Improved finalist submissions
|
||||
- Complete mentoring collaboration + promotion history
|
||||
|
||||
## 4.7 Stage G: Live Finals Jury 3 (`jury3_live_finals`)
|
||||
|
||||
### Inputs
|
||||
- Finalist list/order
|
||||
- Jury 3 members
|
||||
- Live voting settings and optional audience voting config
|
||||
|
||||
### Runtime Rules
|
||||
- Admin stage manager can set active presenter, open/close vote windows
|
||||
- Jury 3 sees:
|
||||
- all finalist info and historical context allowed by policy
|
||||
- prior jury summaries (if permitted)
|
||||
- real-time note-taking and live voting controls
|
||||
- Audience vote optional; if enabled, shown during deliberation as configured
|
||||
|
||||
### Outputs
|
||||
- Live vote records + deliberation notes + optional audience totals
|
||||
|
||||
## 4.8 Stage H: Final Confirmation (`final_confirmation`)
|
||||
|
||||
### Inputs
|
||||
- Jury 3 voting outcomes
|
||||
- Deliberation notes
|
||||
- Award outcomes
|
||||
|
||||
### Runtime Rules
|
||||
- Explicit confirmation workflow:
|
||||
- all required jury confirmations captured (default unanimous for both category winners and award winners, based on active quorum)
|
||||
- if a required juror is absent, admin can either replace the juror or mark absence so they do not count toward required confirmations (fully audited)
|
||||
- exception: awards configured for single-judge mode follow single-judge confirmation flow
|
||||
- one admin approval required to finalize
|
||||
- Admin override path is supported for both category and award outcomes with mandatory reason/audit evidence
|
||||
- On finalize:
|
||||
- winner rankings locked
|
||||
- result set immutable (unlock allowed only through super-admin workflow with explicit audit reason)
|
||||
|
||||
### Outputs
|
||||
- Official winners per category
|
||||
- Official award winners
|
||||
- Immutable final decision audit package
|
||||
|
||||
## 4.9 Stage I: Results Publication (`results_publication`)
|
||||
- Controlled publication policy (manual or policy-based)
|
||||
- Public/private output controls
|
||||
- Report export snapshot references final lock version
|
||||
|
||||
## 5) Cross-Cutting Target Behaviors
|
||||
|
||||
### 5.1 Deadlines And Reminder Contracts
|
||||
Every stage with time windows must have:
|
||||
- user-visible countdown in role dashboards
|
||||
- reminder policy (3-day, 24h, 1h defaults; configurable)
|
||||
- reliable dedupe via reminder logs
|
||||
|
||||
### 5.2 Manual Override Everywhere (With Structured Reasoning)
|
||||
Admins can override:
|
||||
- filtering outcomes
|
||||
- assignment decisions
|
||||
- advancement and finalist picks
|
||||
- award eligibility and winner selection
|
||||
- final winner confirmation
|
||||
|
||||
Each override requires:
|
||||
- reason code
|
||||
- optional reason text
|
||||
- before/after snapshot
|
||||
- actor and timestamp
|
||||
|
||||
### 5.3 Multi-Jury Explicitness
|
||||
Juries become explicit objects with memberships and stage bindings:
|
||||
- main juries and award juries use purpose bindings with custom labels per program
|
||||
- overlap allowed
|
||||
- assignments and dashboards are jury-context-aware
|
||||
|
||||
### 5.4 Multi-Round Document Visibility
|
||||
- Applicants edit current stage only
|
||||
- Applicants read-only previous stage docs
|
||||
- Judges view current + previous by policy
|
||||
- Admin full control
|
||||
|
||||
### 5.5 Platform-Wide Integration Rule
|
||||
No function may bypass stage context:
|
||||
- invite + onboarding
|
||||
- assignment generation
|
||||
- document submission/locking
|
||||
- live voting
|
||||
- status timeline
|
||||
- notifications
|
||||
|
||||
All are resolved through a central `competition context resolver` (program + pipeline + stage purpose + jury context + user role).
|
||||
|
||||
## 6) Simplicity + Customizability Strategy
|
||||
|
||||
### 6.1 Simplicity
|
||||
- Fixed Monaco-compatible stage purpose skeleton (minimal mandatory stages)
|
||||
- Strong defaults and pre-built templates for most competitions
|
||||
- Role-specific UX views that only expose relevant controls
|
||||
|
||||
### 6.2 Customizability
|
||||
- Policy overrides per stage, jury, award, and user
|
||||
- Configurable late policies, cap buffers, top-N finalists, audience voting behavior
|
||||
- Award mode per award (`separate_pool` vs `dual_track`)
|
||||
- Final confirmation rules configurable (unanimous, supermajority, quorum fallback handling, etc.)
|
||||
|
||||
## 7) Target Outcome
|
||||
The redesigned architecture should let admins run Monaco OPC end-to-end **without ad hoc interpretation** and with full traceability, while still allowing controlled per-program policy customization.
|
||||
@@ -0,0 +1,98 @@
|
||||
# 03. Gap Analysis And Simplification Decisions
|
||||
|
||||
## 1) Summary
|
||||
The platform already supports most building blocks of your competition, but key Monaco requirements are either implicit, partially modeled, or dispersed across modules. This document converts those gaps into explicit redesign decisions.
|
||||
|
||||
## 2) Gap Matrix (Current vs Required vs Redesign)
|
||||
|
||||
| Area | Current State | Monaco Requirement | Redesign Decision |
|
||||
|---|---|---|---|
|
||||
| Stage semantics | Generic `StageType`, behavior split between `configJson` and UI assumptions | Explicit flow steps (R1 intake, eligibility, Jury1, R2, Jury2, mentoring layer, Jury3 live, final confirmation) | Add `stagePurposeKey` (typed enum) and purpose-specific policy validation |
|
||||
| Jury modeling | Jury mostly inferred from role + assignments | Explicit `Jury 1/2/3` and award juries with overlap | Add first-class `Jury` and `JuryMembership` models; bind to stages |
|
||||
| Assignment policy | Max/min load + overflow policy + some category quota support | Per-judge hard/soft cap + soft buffer + startup/concept ratio + manual fallback queue | Create typed `AssignmentPolicy` + `JudgePolicyOverride`; formal unassigned queue |
|
||||
| Filtering outcomes | Deterministic + AI + manual queue present | Eligibility pass with admin override and reason trace | Keep existing model, add stricter outcome taxonomy and promotion gates |
|
||||
| Submission rounds | Stage requirements exist; file logic partly stage-bound | Round bundles with lock/read-only and provenance | Introduce explicit `SubmissionRound`/`DocumentBundle` abstraction on top of stage |
|
||||
| Mentoring workspace | Mentor assignment/messages/notes/milestones exist | Private files + threaded comments + promotion to official submission | Add mentor workspace files/comments and `PromotionEvent` typed audit |
|
||||
| Special awards | Strong award model, routing present but mixed semantics | Mode A/B behavior per award with pull-out/dual participation | Add explicit `awardParticipationMode` + routing policy constraints |
|
||||
| Live finals | Live cursor + voting session + audience support exists | Stage manager controls + Jury 3 notes + deliberation windows | Keep live primitives; add deliberation policy and jury3 context contracts |
|
||||
| Final confirmation | Audit + decision logs exist | All jury agree + one admin approval + result lock | Add dedicated `FinalConfirmation` workflow and result freeze state |
|
||||
| Invite/member flows | Admin/member/team invites implemented; pre-assignment exists | Must deeply reflect updated architecture and juries | Make invites jury-aware and stage-purpose aware; unify assignment intents |
|
||||
|
||||
## 3) High-Impact Ambiguity Sources To Eliminate
|
||||
|
||||
### 3.1 `configJson` As Primary Runtime Logic
|
||||
Current problem:
|
||||
- Critical behavior lives in open-ended JSON keys with inconsistent naming and weak compile-time guarantees.
|
||||
|
||||
Decision:
|
||||
- Keep `configJson` for non-critical UI metadata.
|
||||
- Move flow-critical behavior into typed policy tables and strict schemas.
|
||||
|
||||
### 3.2 Generic Stage Types Without Purpose Contract
|
||||
Current problem:
|
||||
- Two stages can both be `EVALUATION`, but system behavior may need to differ radically (Jury1 vs Jury2 vs award).
|
||||
|
||||
Decision:
|
||||
- Add immutable `stagePurposeKey` and purpose-aware policy validator.
|
||||
|
||||
### 3.3 Dispersed Assignment Constraints
|
||||
Current problem:
|
||||
- Multiple assignment pathways (stageAssignment router/service, assignment router, AI suggestions) can diverge in rules.
|
||||
|
||||
Decision:
|
||||
- Centralize assignment rule evaluation into one policy engine used by all assignment entry points.
|
||||
|
||||
### 3.4 Invite And Onboarding Disconnected From Jury Context
|
||||
Current problem:
|
||||
- `/admin/members/invite` pre-assigns projects directly, but not explicitly tied to jury entities and policy contracts.
|
||||
|
||||
Decision:
|
||||
- Introduce `AssignmentIntent` attached to `JuryMembership`/stage context during invite flow; materialize assignments when stage/policy permits.
|
||||
|
||||
## 4) Simplification Decisions (Non-Negotiable)
|
||||
|
||||
1. **One source of truth for stage behavior:** `stagePurposeKey + policy models`
|
||||
2. **One source of truth for assignment constraints:** centralized assignment policy engine
|
||||
3. **One source of truth for winner lock:** explicit final confirmation workflow
|
||||
4. **One source of truth for document status:** round bundle + requirement slot state
|
||||
5. **One source of truth for role access:** policy-based access resolver by context
|
||||
|
||||
## 5) Compatibility Strategy
|
||||
|
||||
### 5.1 Keep Existing Backbone
|
||||
No full rewrite:
|
||||
- Preserve `Pipeline`, `Track`, `Stage`, `ProjectStageState`, `Assignment`, `Evaluation`, `SpecialAward`, `LiveVotingSession`
|
||||
|
||||
### 5.2 Additive Evolution
|
||||
Add new typed entities and read/write adapters:
|
||||
- old endpoints keep working in compatibility mode during migration
|
||||
- new flows use purpose/policy-aware endpoints
|
||||
|
||||
### 5.3 Controlled De-ambiguation
|
||||
- Introduce strict validation for future pipeline configs
|
||||
- Provide migration scripts for legacy `configJson` keys
|
||||
- fail-fast for unsupported combinations
|
||||
|
||||
## 6) Design Tradeoffs
|
||||
|
||||
### 6.1 Why Not Fully Dynamic “No Skeleton” Flow?
|
||||
- You requested clarity and reduced vagueness.
|
||||
- Purely dynamic flow increases flexibility but harms predictability, QA surface, and operator confidence.
|
||||
|
||||
Chosen approach:
|
||||
- fixed Monaco skeleton + configurable policies and optional modules.
|
||||
|
||||
### 6.2 Why Typed Tables Instead Of More JSON?
|
||||
- Critical competition logic requires integrity constraints, easier querying, and deterministic behavior.
|
||||
- Typed models improve auditability and testability.
|
||||
|
||||
### 6.3 Why Add Jury As Explicit Entity?
|
||||
- Your flow explicitly names Jury 1/2/3 and overlapping award juries.
|
||||
- This cannot remain a UI convention without creating operational drift.
|
||||
|
||||
## 7) Required Outcome Of Simplification
|
||||
By end of redesign:
|
||||
- Admins can configure Monaco flow without hidden dependencies.
|
||||
- Assignment limits are deterministic, while startup/concept ratio remains a transparent soft-bias recommendation.
|
||||
- Invite/member pages support policy-compliant jury memberships plus both pre-assignment modes (intent-first and direct assignment where explicitly enabled).
|
||||
- Documents, mentoring, awards, finals, and confirmation all speak the same domain language.
|
||||
@@ -0,0 +1,317 @@
|
||||
# 04. Unified Domain Model And Config Contracts
|
||||
|
||||
## 1) Objectives
|
||||
This target model turns the Monaco flow into strict, reusable contracts while preserving the current pipeline infrastructure.
|
||||
|
||||
Goals:
|
||||
1. Minimize schema churn where current models are already correct.
|
||||
2. Remove ambiguity for jury identity, assignment policy, round bundles, mentoring promotion, and final lock.
|
||||
3. Keep customization through explicit policy layers, not ad hoc conditionals.
|
||||
|
||||
## 2) Proposed Domain Additions
|
||||
|
||||
## 2.1 Stage Purpose Contract
|
||||
|
||||
### Add To `Stage`
|
||||
- `purposeKey` (enum/string, required after migration)
|
||||
|
||||
Proposed purpose enum values:
|
||||
- `submission_r1_intake`
|
||||
- `eligibility_filter`
|
||||
- `jury1_evaluation`
|
||||
- `submission_r2_intake`
|
||||
- `jury2_evaluation`
|
||||
- `jury3_live_finals`
|
||||
- `final_confirmation`
|
||||
- `results_publication`
|
||||
- `award_evaluation`
|
||||
- `award_results`
|
||||
|
||||
Rule:
|
||||
- `StageType` remains coarse technical type.
|
||||
- `purposeKey` controls business behavior and policy validation.
|
||||
|
||||
## 2.2 Jury As First-Class Entity
|
||||
|
||||
### New `Jury`
|
||||
Fields:
|
||||
- `id`, `programId`, `purposeKey`, `code`, `displayLabel`, `kind` (`MAIN`, `AWARD`), `isActive`
|
||||
|
||||
Examples:
|
||||
- `code=main-semifinal`, `displayLabel=Technical Semi-Final Jury`
|
||||
- `code=main-finalist`, `displayLabel=Grand Jury`
|
||||
- `code=award-blue-innovation`, `displayLabel=Blue Innovation Prize Jury`
|
||||
|
||||
### New `JuryMembership`
|
||||
Fields:
|
||||
- `juryId`, `userId`, `roleInJury` (`CHAIR`, `MEMBER`), `activeFrom`, `activeTo`, `status`
|
||||
|
||||
### New `JuryStageBinding`
|
||||
Fields:
|
||||
- `juryId`, `stageId`, `isPrimary`, `permissionsJson`
|
||||
|
||||
Use:
|
||||
- controls which juries are allowed to evaluate/vote in each stage
|
||||
- allows overlap across juries and awards
|
||||
|
||||
## 2.3 Assignment Policy Contract
|
||||
|
||||
### New `AssignmentPolicy` (stage + jury scoped)
|
||||
Fields:
|
||||
- `stageId`
|
||||
- `juryId`
|
||||
- `requiredReviews`
|
||||
- `defaultCap`
|
||||
- `defaultCapMode` (`HARD`, `SOFT`)
|
||||
- `softBuffer` (default 10, configurable)
|
||||
- `categoryBiasPolicyJson` (startup/concept mix preference weights; non-deterministic)
|
||||
- `overflowPolicy` (`manual_queue`, `expand_pool`, `reduce_reviews`)
|
||||
- `isActive`
|
||||
|
||||
### New `JudgePolicyOverride`
|
||||
Fields:
|
||||
- `assignmentPolicyId`
|
||||
- `userId`
|
||||
- `cap`, `capMode`, `softBuffer`
|
||||
- `startupBiasWeight`, `conceptBiasWeight`
|
||||
- `biasDisclosureAcceptedAt` (onboarding acknowledgement that bias is suggestive only)
|
||||
- `source` (`ADMIN_SET`, `JUDGE_ONBOARDING`)
|
||||
|
||||
### New `AssignmentIntent`
|
||||
Purpose:
|
||||
- records desired assignments created before assignment materialization (e.g., from member invite page)
|
||||
|
||||
Fields:
|
||||
- `stageId`, `juryId`, `userId`, `projectId`, `intentSource`, `status`
|
||||
|
||||
### New `AssignmentException`
|
||||
Purpose:
|
||||
- explicit record for manual over-cap assignments
|
||||
|
||||
Fields:
|
||||
- `assignmentId`, `policyId`, `exceptionType`, `reasonCode`, `reasonText`, `approvedBy`
|
||||
|
||||
## 2.4 Submission Round Bundle Contract
|
||||
|
||||
### New `SubmissionRound`
|
||||
Fields:
|
||||
- `id`, `stageId`, `roundKey`, `name`, `openAt`, `closeAt`, `latePolicy`, `lateGraceHours`, `editabilityPolicy`
|
||||
|
||||
### Evolve `FileRequirement`
|
||||
Add:
|
||||
- `submissionRoundId` (nullable transitional, required after migration)
|
||||
- `slotKey` (stable requirement slot identifier)
|
||||
|
||||
### Evolve `ProjectFile`
|
||||
Add:
|
||||
- `submissionRoundId`
|
||||
- `submissionSlotKey`
|
||||
- `sourceType` (`DIRECT_UPLOAD`, `MENTOR_PROMOTION`, `ADMIN_REPLACEMENT`)
|
||||
- `sourceReferenceId` (e.g., mentor file id)
|
||||
- `isOfficial`
|
||||
|
||||
### New `SubmissionBundleState`
|
||||
Fields:
|
||||
- `projectId`, `submissionRoundId`, `status` (`DRAFT`, `SUBMITTED`, `LOCKED`), `lockedAt`, `lockedBy`
|
||||
|
||||
## 2.5 Mentoring Collaboration + Promotion
|
||||
|
||||
### New `MentorWorkspaceFile`
|
||||
Fields:
|
||||
- `projectId`, `mentorId` (nullable for team upload), file storage metadata, visibility, status
|
||||
|
||||
### New `MentorWorkspaceComment`
|
||||
Fields:
|
||||
- `workspaceFileId`, `authorId`, `threadKey`, `content`, timestamps
|
||||
|
||||
### New `SubmissionPromotionEvent`
|
||||
Fields:
|
||||
- `projectId`, `workspaceFileId`, `targetSubmissionRoundId`, `targetSlotKey`
|
||||
- `promotedById`, `promotedAt`
|
||||
- `resultProjectFileId`
|
||||
- `approvalState` (if mentor/admin approvals required)
|
||||
|
||||
Invariant:
|
||||
- promotion always creates immutable provenance link from mentoring artifact to official submission slot.
|
||||
- promotion authority is limited to team lead and admin.
|
||||
|
||||
## 2.6 Special Award Governance Contract
|
||||
|
||||
### Extend `SpecialAward`
|
||||
Add:
|
||||
- `participationMode` (`SEPARATE_POOL`, `DUAL_TRACK`)
|
||||
- `routingBehavior` (`PULL_FROM_MAIN`, `KEEP_IN_MAIN`)
|
||||
- `routingConfirmationMode` (`AUTO`, `ADMIN_CONFIRMED`) // Monaco default: `ADMIN_CONFIRMED` for pull-out
|
||||
- `requiresDedicatedJury` (bool)
|
||||
- `winnerDecisionMode` (`JURY_CONFIRMATION`, `SINGLE_JUDGE_DECIDES`)
|
||||
- `singleJudgeUserId` (nullable, required when `winnerDecisionMode=SINGLE_JUDGE_DECIDES`)
|
||||
- `winnerCandidateSource` (`ELIGIBILITY_REMAINING_POOL`, `CUSTOM_SHORTLIST`) // Monaco single-judge awards use eligibility remaining pool
|
||||
- `submissionRequirementMode` (`REUSE_MAIN`, `CUSTOM`)
|
||||
|
||||
### New `AwardStageBinding`
|
||||
Fields:
|
||||
- `awardId`, `filterStageId`, `evaluationStageId`, `resultStageId`
|
||||
|
||||
## 2.7 Final Confirmation Contract
|
||||
|
||||
### New `FinalConfirmationSession`
|
||||
Fields:
|
||||
- `stageId` (final confirmation stage)
|
||||
- `status` (`OPEN`, `PENDING_ADMIN_APPROVAL`, `FINALIZED`, `CANCELLED`)
|
||||
- `decisionRule` (`UNANIMOUS`, `SUPERMAJORITY`, `SIMPLE_MAJORITY`, `SINGLE_JUDGE_DECIDES`)
|
||||
- `quorumPolicy` (`ACTIVE_MEMBERS_ONLY`, `ALLOW_REPLACEMENT`)
|
||||
- `requiredApprovalsCount` (resolved from active quorum after absence/replacement decisions)
|
||||
- `scope` (`CATEGORY`, `AWARD`)
|
||||
- `isAdminOverridden` (bool)
|
||||
- `overrideReasonCode`, `overrideReasonText`, `overriddenByAdminId`, `overriddenAt`
|
||||
- `finalizedByAdminId`, `finalizedAt`
|
||||
|
||||
### New `FinalConfirmationParticipant`
|
||||
Fields:
|
||||
- `sessionId`, `juryMemberId`
|
||||
- `status` (`REQUIRED`, `ABSENT_EXCUSED`, `REPLACED`, `REPLACEMENT_ACTIVE`)
|
||||
- `replacedByJuryMemberId` (nullable)
|
||||
- `absenceReasonCode`, `absenceReasonText`
|
||||
- `updatedByAdminId`, `updatedAt`
|
||||
|
||||
### New `FinalConfirmationVote`
|
||||
Fields:
|
||||
- `sessionId`, `juryMemberId`, `projectId/category/awardScope`, `decision`, `comment`
|
||||
|
||||
### New `ResultLock`
|
||||
Fields:
|
||||
- `sessionId`, `programId`, `lockVersion`, `lockedAt`, `lockedBy`, `snapshotJson`
|
||||
|
||||
### New `ResultUnlockEvent`
|
||||
Fields:
|
||||
- `resultLockId`, `programId`
|
||||
- `unlockedBySuperAdminId`, `unlockedAt`
|
||||
- `reasonCode`, `reasonText`
|
||||
- `relockVersion` (nullable until relock)
|
||||
|
||||
Invariant:
|
||||
- once `ResultLock` is created, winner outputs are immutable except via explicit super-admin unlock workflow with mandatory audit reason.
|
||||
|
||||
## 3) Policy Precedence Model
|
||||
|
||||
Order of precedence (highest to lowest):
|
||||
1. Explicit admin override action (with reason)
|
||||
2. Per-user override policy (e.g., judge cap override)
|
||||
3. Stage+jury policy
|
||||
4. Program-level default policy
|
||||
5. System default
|
||||
|
||||
All runtime evaluators must return:
|
||||
- resolved value
|
||||
- source layer
|
||||
- explanation payload for audit/debug UI
|
||||
|
||||
## 4) Access Contract (Role + Context)
|
||||
|
||||
Replace scattered checks with `resolveAccess(user, context)` where context includes:
|
||||
- `programId`
|
||||
- `trackId`
|
||||
- `stageId`
|
||||
- `stagePurposeKey`
|
||||
- `juryId` (if applicable)
|
||||
- `projectId` (if applicable)
|
||||
- `submissionRoundId` (if applicable)
|
||||
|
||||
Returns typed permissions:
|
||||
- `canViewProject`
|
||||
- `canUploadSubmissionSlot`
|
||||
- `canViewPreviousRoundDocs`
|
||||
- `canAssignProjects`
|
||||
- `canVoteLive`
|
||||
- `canConfirmFinalWinners`
|
||||
- etc.
|
||||
|
||||
## 5) Assignment Engine Contract
|
||||
|
||||
Input:
|
||||
- projects eligible in stage
|
||||
- jury members bound to stage
|
||||
- resolved per-judge policy (cap mode, cap, buffer, category-bias preference)
|
||||
- required reviews
|
||||
- COI and availability constraints
|
||||
|
||||
Required behavior:
|
||||
1. satisfy hard-cap constraints strictly
|
||||
2. satisfy soft-cap targets before using buffer
|
||||
3. apply startup/concept distribution as a soft scoring bias (never a strict blocker)
|
||||
4. when all soft-cap members hit cap+buffer, place remainder in manual queue
|
||||
5. never silently drop unassigned projects
|
||||
|
||||
Output:
|
||||
- assignment set
|
||||
- unassigned queue with explicit reasons
|
||||
- policy-compliance summary
|
||||
|
||||
## 6) Document Contract
|
||||
|
||||
For every stage with submission behavior:
|
||||
- active `SubmissionRound` must exist
|
||||
- all required slots represented by `FileRequirement.slotKey`
|
||||
- applicant write rights only for active round if open
|
||||
- previous round slots read-only in applicant scope
|
||||
- judges see current + previous according to stage policy
|
||||
- admins full mutate rights with replacement provenance
|
||||
|
||||
## 7) Invite + Onboarding Contract
|
||||
|
||||
## 7.1 Admin Member Invite
|
||||
- Invitations create `User` + optional `JuryMembership`.
|
||||
- Jury selection uses program-defined custom jury labels, while binding to explicit stage-purpose contracts.
|
||||
- Pre-assignment supports both modes:
|
||||
- intent-first mode via `AssignmentIntent` (default recommended)
|
||||
- direct assignment mode via `Assignment` (explicitly enabled and policy-validated)
|
||||
|
||||
## 7.2 Team Invite
|
||||
- Team lead invites create/attach `TeamMember`
|
||||
- invite token acceptance path remains, but post-accept routing resolves to proper applicant/team context
|
||||
|
||||
## 7.3 Accept Invite Routing
|
||||
After acceptance:
|
||||
- if user has jury memberships pending onboarding -> jury onboarding journey
|
||||
- if mentor -> mentor onboarding
|
||||
- if applicant team member only -> applicant team dashboard
|
||||
|
||||
## 8) Event/Audit Contract
|
||||
|
||||
Every significant workflow event emits:
|
||||
- business event type (`assignment.generated`, `final_confirmation.finalized`, etc.)
|
||||
- actor
|
||||
- entity scope
|
||||
- policy snapshot
|
||||
- before/after state where relevant
|
||||
|
||||
Override events must include:
|
||||
- reason code
|
||||
- reason text
|
||||
- impacted policy key
|
||||
- reviewer chain (if applicable)
|
||||
|
||||
## 9) API Contract Evolution (Router-Level)
|
||||
|
||||
## 9.1 Keep and Evolve
|
||||
- Keep existing routers (`pipeline`, `stage`, `assignment`, `evaluation`, `file`, `mentor`, `live-voting`, `decision`, `user`, etc.)
|
||||
- Add new endpoints for purpose/policy/jury/final confirmation and deprecate ambiguous patterns progressively
|
||||
|
||||
## 9.2 New Endpoint Families
|
||||
- `jury.*`: CRUD memberships/bindings
|
||||
- `assignmentPolicy.*`: configure and inspect effective policy
|
||||
- `submissionRound.*`: lifecycle and bundle state
|
||||
- `mentorWorkspace.*`: files/comments/promotion
|
||||
- `finalConfirmation.*`: create/collect/finalize lock, handle quorum fallback, and manage juror replacement/absence
|
||||
- `resultUnlock.*`: super-admin unlock/relock workflow with audit capture
|
||||
- `access.*`: debug effective permissions (admin-only)
|
||||
|
||||
## 10) Migration Safety Rules
|
||||
1. Additive migrations first.
|
||||
2. Backfill `purposeKey` and policy references from existing configs.
|
||||
3. Dual-read / single-write transition windows where needed.
|
||||
4. Feature flags for critical runtime path switches.
|
||||
5. No silent behavior changes in production without compatibility mode.
|
||||
|
||||
## 11) End State
|
||||
A coherent operating model where all functions, pages, and APIs are consistent with Monaco flow and each key behavior is explainable, testable, and auditable.
|
||||
@@ -0,0 +1,174 @@
|
||||
# 05. Platform-Wide Integration Matrix
|
||||
|
||||
## 1) Integration Rule
|
||||
Every function must consume the same competition context contract:
|
||||
- program
|
||||
- pipeline/track
|
||||
- stage + `purposeKey`
|
||||
- jury context (when relevant)
|
||||
- submission round context (when relevant)
|
||||
- resolved policy set
|
||||
|
||||
No page/router may hardcode Monaco behavior without passing through this context resolver.
|
||||
|
||||
## 2) Critical Integration Domains
|
||||
|
||||
1. Identity and invitation/onboarding
|
||||
2. Pipeline/stage orchestration
|
||||
3. Assignment/evaluation
|
||||
4. Documents/submission bundles
|
||||
5. Awards and routing
|
||||
6. Mentoring collaboration
|
||||
7. Live finals and final confirmation
|
||||
8. Notifications, timeline, reporting, exports
|
||||
|
||||
## 3) Admin UX Integration Matrix
|
||||
|
||||
| Surface | Current Behavior | Required Integration To Redesigned Architecture |
|
||||
|---|---|---|
|
||||
| `src/app/(admin)/admin/rounds/pipeline/[id]/wizard/page.tsx` | Generic stage setup | Must require `purposeKey` assignment and validate Monaco skeleton completeness |
|
||||
| `src/app/(admin)/admin/rounds/pipeline/[id]/advanced/page.tsx` | Advanced free-form editing | Add policy editors for jury binding, assignment policies, submission rounds, final confirmation |
|
||||
| `src/app/(admin)/admin/rounds/pipeline/[id]/edit/page.tsx` | Pipeline editing | Prevent invalid stage-purpose combinations; show dependency impacts |
|
||||
| `src/components/admin/pipeline/sections/assignment-section.tsx` | min/max load + overflow | Replace with explicit hard/soft cap + buffer + startup/concept bias controls (clearly labeled suggestive, not deterministic) |
|
||||
| `src/components/admin/pipeline/sections/filtering-section.tsx` | rules + AI criteria | Bind to `eligibility_filter` purpose and standardized outcomes |
|
||||
| `src/components/admin/pipeline/sections/awards-section.tsx` | award routing/scoring basic | Add participation mode (`separate_pool`/`dual_track`) and pull-out behavior |
|
||||
| `src/components/admin/pipeline/sections/live-finals-section.tsx` | live/audience settings | Add Jury 3 deliberation window and final confirmation linkage |
|
||||
| `src/components/admin/pipeline/stage-config-editor.tsx` | generic config rendering | render purpose-aware controls only; remove ambiguous keys |
|
||||
| `src/app/(admin)/admin/projects/page.tsx` | project list by filters | Add stage-purpose-aware views and round bundle health columns |
|
||||
| `src/app/(admin)/admin/projects/pool/page.tsx` | project pool ops | Use assignment intent/manual queue with reason tracking |
|
||||
| `src/app/(admin)/admin/reports/stages/page.tsx` | stage reporting | Include compliance metrics (cap violations, override counts, unassigned backlog) |
|
||||
|
||||
## 4) Invite / Member / Onboarding Integration Matrix (High Priority)
|
||||
|
||||
### 4.1 Admin Member Invite (Explicit Requirement)
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(admin)/admin/members/invite/page.tsx` | invites users; optional pre-assign project-to-user by stage | Must bind invite flow to explicit `JuryMembership`. UI must support both pre-assignment modes: `AssignmentIntent` mode and policy-validated direct assignment mode. Admin chooses custom-labeled jury (main or award), stage scope, and mode. |
|
||||
| `src/server/routers/user.ts` `bulkCreate` | creates users and may directly create assignments | Support dual behavior: create `AssignmentIntent` and/or direct policy-validated assignments based on request mode. Track chosen mode, source, and policy decision in audit details. |
|
||||
| `src/server/routers/user.ts` `sendInvitation`/`bulkSendInvitations` | token invitation | Include context metadata (jury memberships, pending assignment intents, onboarding path) in invitation payload/logs. |
|
||||
|
||||
### 4.2 Team Invite / Project Team Management
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(applicant)/applicant/team/page.tsx` | team lead invites/removes members | Keep flow, but gate permissions via context resolver and ensure invite acceptance routes into project-team scope correctly. |
|
||||
| `src/app/(public)/my-submission/[id]/team/page.tsx` | mirrored team flow | Must consume same backend contract as applicant team page; no divergent logic. |
|
||||
| `src/server/routers/applicant.ts` `inviteTeamMember` | creates/updates user + team member + email | Add membership lifecycle states and provenance events; ensure no conflict with jury/mentor invitation states. |
|
||||
|
||||
### 4.3 Invite Acceptance + Onboarding
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(auth)/accept-invite/page.tsx` | validates token and signs in | After acceptance, route based on membership context (jury, mentor, team, admin) and pending obligations (onboarding, password, jury onboarding choices). |
|
||||
| `src/app/(auth)/onboarding/page.tsx` | role-aware onboarding | Must collect jury cap/bias preferences (if enabled) for judges, clearly disclose that startup/concept bias is suggestive (not a rule), and tie to `JudgePolicyOverride` records. |
|
||||
| `src/server/routers/user.ts` `validateInviteToken` | token validation only | include contextual invitation metadata for accurate UX preview. |
|
||||
| `src/server/routers/user.ts` `needsOnboarding` | role-based onboarding check | extend to membership-aware onboarding requirements per jury/stage. |
|
||||
|
||||
## 5) Applicant + Submission Integration Matrix
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(public)/apply/[slug]/page.tsx` | stage/public form | enforce submission round contract (`SubmissionRound`, slots, late policy) |
|
||||
| `src/app/(public)/apply/edition/[programSlug]/page.tsx` | edition mode intake | must map to `submission_r1_intake` purpose policies if Monaco profile active |
|
||||
| `src/app/(applicant)/applicant/pipeline/page.tsx` | pipeline visibility | show purpose-based journey (R1, eligibility, Jury1 result, R2, etc.) |
|
||||
| `src/app/(applicant)/applicant/pipeline/[stageId]/documents/page.tsx` | stage docs | enforce round-bundle write/read states by stage purpose |
|
||||
| `src/app/(applicant)/applicant/documents/page.tsx` | docs view | show bundle timeline and official slot status per round |
|
||||
| `src/server/routers/application.ts` | public submission & draft | create `SubmissionBundleState` and normalize category key mapping |
|
||||
| `src/server/routers/applicant.ts` `getUploadUrl/saveFileMetadata/deleteFile` | upload + save + delete | enforce slot state, round lock, promotion provenance, late behavior policy |
|
||||
| `src/server/routers/file.ts` | file access and grouped views | use submission round + stage purpose aware visibility consistently across roles |
|
||||
|
||||
## 6) Jury Integration Matrix
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(jury)/jury/stages/page.tsx` | shows active stages | show only stages bound to juries user belongs to |
|
||||
| `src/app/(jury)/jury/stages/[stageId]/assignments/page.tsx` | assignment list | render cap status, ratio status, deadline countdown, completion obligations |
|
||||
| `src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/page.tsx` | project details | purpose-aware document separation (Round 1 vs Round 2) |
|
||||
| `src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/evaluate/page.tsx` | evaluation form | enforce stage/jury policy and graceful lock behavior |
|
||||
| `src/app/(jury)/jury/stages/[stageId]/live/page.tsx` | live finals interaction | require Jury 3 membership and live session permissions |
|
||||
| `src/server/routers/assignment.ts` | assignment CRUD/suggestions/jobs | centralize policy engine usage for all assignment paths |
|
||||
| `src/server/routers/evaluation.ts` | evaluation lifecycle | incorporate jury binding checks and final confirmation contribution rights |
|
||||
| `src/server/services/stage-assignment.ts` | stage assignment preview/run | implement hard/soft cap+buffer with category bias as weighted guidance (not deterministic rule) |
|
||||
| `src/server/services/smart-assignment.ts` | scoring logic | treat startup/concept preference as transparent scoring bias, not strict quota blocking |
|
||||
|
||||
## 7) Awards Integration Matrix
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(admin)/admin/awards/*` | award management | expose mode A/B semantics, admin-confirmed pull-out flow, and single-judge decision mode where configured |
|
||||
| `src/app/(jury)/jury/awards/*` | jury award voting | bind to award jury memberships/stage windows and suppress jury voting for single-judge awards |
|
||||
| `src/server/routers/award.ts` | award track governance | add strict validation for participation mode, stage bindings, admin-confirmed pull-out, and single-judge configuration |
|
||||
| `src/server/routers/specialAward.ts` | eligibility + jurors + votes | include standardized filter->review->selection pipeline and override chain |
|
||||
| `src/server/services/award-eligibility-job.ts` | background eligibility | persist decision reasoning under unified audit event taxonomy |
|
||||
|
||||
## 8) Mentor Integration Matrix
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(mentor)/mentor/projects/[id]/page.tsx` | mentor project detail | include private workspace files + threaded comments; promotion actions only where allowed by team-lead/admin authority |
|
||||
| `src/app/(applicant)/applicant/mentor/page.tsx` | applicant mentor interaction | show promotion candidate files and official slot mapping |
|
||||
| `src/server/routers/mentor.ts` | assignment/message/notes/milestones | add workspace file/comment/promotion endpoints and enforce team-lead/admin-only promotion permissions |
|
||||
| `src/server/services/mentor-matching.ts` | AI matching | gate matching by finalist + mentorship request + stage policy |
|
||||
|
||||
## 9) Live Finals + Confirmation Integration Matrix
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/app/(admin)/admin/reports/stages/page.tsx` + live admin pages | live status/reporting | show stage manager controls + deliberation timer + confirmation readiness |
|
||||
| `src/app/(public)/vote/*` | audience voting pages | enforce category/session mode and anti-duplicate policy |
|
||||
| `src/server/routers/live.ts` | live cursor controls | require `jury3_live_finals` purpose and stage manager authority |
|
||||
| `src/server/routers/live-voting.ts` | voting session mgmt | tie session lifecycle to stage purpose + deliberation/final confirmation handoff |
|
||||
| `src/server/routers/cohort.ts` | cohort windows | align with live/selection policies and category boundaries |
|
||||
| `src/server/routers/decision.ts` | overrides/audit | extend to final confirmation decisions and result lock events |
|
||||
| **new router family** `finalConfirmation.*` | none | create and govern unanimous-with-quorum-fallback confirmation for category+award scopes, single-judge award exceptions, juror replacement/absence controls, admin override paths, and final lock snapshot |
|
||||
| **new router family** `resultUnlock.*` | none | super-admin-only unlock/relock workflow with mandatory reason/audit trail |
|
||||
|
||||
## 10) Notifications / Messaging / Reporting / Export Integration Matrix
|
||||
|
||||
| Surface | Current Behavior | Required Integration |
|
||||
|---|---|---|
|
||||
| `src/server/services/stage-notifications.ts` | event-based notifications | expand event taxonomy for jury membership, promotion, confirmation lock |
|
||||
| `src/server/services/evaluation-reminders.ts` | stage deadline reminders | include jury-specific obligations and final confirmation reminders |
|
||||
| `src/server/routers/message.ts` | messaging | ensure context tags reference stage/jury/project where applicable |
|
||||
| `src/server/routers/export.ts` | report generation | include final lock version and policy-compliance evidence |
|
||||
| `src/server/routers/audit.ts` | audit search | add filter facets for stage purpose, jury id, confirmation session |
|
||||
| `src/server/routers/analytics.ts` | platform analytics | add Monaco flow KPIs (assignment saturation, override rate, policy compliance) |
|
||||
|
||||
## 11) Router Integration Checklist (All tRPC Domains)
|
||||
|
||||
Each router in `src/server/routers/_app.ts` must be classified into one of three buckets:
|
||||
|
||||
1. **Directly governed by competition context**
|
||||
- `pipeline`, `stage`, `stageFiltering`, `stageAssignment`, `assignment`, `evaluation`, `decision`, `live`, `liveVoting`, `cohort`, `award`, `specialAward`, `mentor`, `applicant`, `application`, `file`, `project`, `project-pool`
|
||||
|
||||
2. **Indirectly context-dependent (must carry context metadata)**
|
||||
- `user`, `notification`, `message`, `dashboard`, `analytics`, `export`, `audit`
|
||||
|
||||
3. **Context-independent utilities**
|
||||
- `avatar`, `logo`, `tag`, imports, generic settings/webhooks
|
||||
|
||||
Requirement:
|
||||
- Bucket 1 and 2 routers must accept/derive stage/jury context when touching competition entities.
|
||||
|
||||
## 12) Services Refactor Boundaries
|
||||
|
||||
| Service | Keep | Refactor Requirement |
|
||||
|---|---|---|
|
||||
| `stage-engine.ts` | yes | purpose-aware transition guards |
|
||||
| `stage-filtering.ts` | yes | standardized eligibility outcomes + reason schema |
|
||||
| `stage-assignment.ts` | yes | full hard/soft cap policy engine |
|
||||
| `smart-assignment.ts` | partial | convert soft heuristics into policy-compliant scoring only |
|
||||
| `live-control.ts` | yes | bind to Jury3 and confirmation handoff |
|
||||
| `mentor-matching.ts` | yes | finalist-stage gating and workspace policy awareness |
|
||||
| `evaluation-reminders.ts` | yes | purpose-aware reminder templates |
|
||||
|
||||
## 13) Integration Acceptance Criteria
|
||||
A module is considered integrated only if:
|
||||
1. It resolves effective competition context before executing business logic.
|
||||
2. It uses typed policy resolution (not ad hoc JSON key checks).
|
||||
3. It emits standardized audit/decision events.
|
||||
4. It fails safely when required context/policy is missing.
|
||||
|
||||
## 14) Special Note: “All Functions Deeply Integrated”
|
||||
Your requirement is satisfied only when invite/member/team/onboarding pages are not treated as peripheral admin UX, but as first-class entry points into the jury/stage/assignment model. This is explicitly mandatory in Phases 2 and 3 of the roadmap.
|
||||
@@ -0,0 +1,193 @@
|
||||
# 06. Implementation Roadmap And Migration Plan
|
||||
|
||||
## 1) Delivery Strategy
|
||||
Use an incremental, low-risk migration with compatibility layers.
|
||||
|
||||
Execution mode:
|
||||
- Additive schema first
|
||||
- Dual-read where required
|
||||
- Single-write to new contracts once validated
|
||||
- Feature flags for runtime switches
|
||||
- Rollback-safe at every phase gate
|
||||
|
||||
## 2) Phase Plan
|
||||
|
||||
## Phase 0: Contract Freeze And Blueprint Sign-Off
|
||||
|
||||
### Deliverables
|
||||
- Approved Monaco flow contract (stage purpose keys, jury model, assignment semantics)
|
||||
- Locked ADRs for major design choices
|
||||
- Finalized open question decisions from `08-open-questions-for-flow-owners.md`
|
||||
|
||||
### Exit Criteria
|
||||
- No unresolved P0 architecture questions
|
||||
- Product + operations + engineering agreement on control-plane UX behavior
|
||||
|
||||
## Phase 1: Schema Foundation (Additive)
|
||||
|
||||
### Scope
|
||||
- Add `stagePurposeKey`
|
||||
- Add jury models (`Jury`, `JuryMembership`, `JuryStageBinding`)
|
||||
- Add assignment policy models (`AssignmentPolicy`, `JudgePolicyOverride`, `AssignmentIntent`, `AssignmentException`)
|
||||
- Add submission round models (`SubmissionRound`, bundle state fields)
|
||||
- Add mentoring workspace + promotion models
|
||||
- Add final confirmation models
|
||||
|
||||
### Data Migration Tasks
|
||||
1. Backfill stage purpose keys from known stage names/slugs/types.
|
||||
2. Create purpose-bound main juries for active Monaco programs with editable custom labels.
|
||||
3. Create baseline assignment policies from existing stage config values.
|
||||
4. Materialize current intake requirements into typed submission round artifacts.
|
||||
|
||||
### Exit Criteria
|
||||
- All migrations run cleanly in staging
|
||||
- Backfill report has zero unknown stage purpose for Monaco pipelines
|
||||
- Referential integrity validated
|
||||
|
||||
## Phase 2: Policy Engine And Context Resolver
|
||||
|
||||
### Scope
|
||||
- Build centralized `competitionContextResolver`
|
||||
- Build centralized `policyResolver`
|
||||
- Refactor assignment/filtering/live access paths to consume resolver
|
||||
|
||||
### Key Deliverables
|
||||
- `resolveContext(program/stage/project/user)` service
|
||||
- `resolveAssignmentPolicy(stageId, juryId, userId)`
|
||||
- policy-aware access checks for docs/evaluations/live controls
|
||||
|
||||
### Exit Criteria
|
||||
- No core router uses legacy ad hoc logic for stage/jury policy checks
|
||||
- Policy resolution explainability endpoint available (admin debug)
|
||||
|
||||
## Phase 3: Invite/Member/Onboarding Integration (Critical)
|
||||
|
||||
### Scope
|
||||
- Refactor admin member invite flow to create jury memberships plus dual pre-assignment modes (intent mode and direct policy-validated assignment mode)
|
||||
- Align team invite flow with unified invitation context metadata
|
||||
- Update accept-invite routing to membership-aware onboarding
|
||||
|
||||
### Key Deliverables
|
||||
- `/admin/members/invite` UX and backend contract update
|
||||
- `user.bulkCreate` migration to support both assignment intent creation and direct policy-validated assignments
|
||||
- onboarding path resolver by role + memberships, including clear bias-disclosure text for jury onboarding
|
||||
|
||||
### Exit Criteria
|
||||
- Invite-created users can be traced from invite -> membership -> assignment materialization
|
||||
- No orphan invitation states
|
||||
- Regression tests pass for admin invite + team invite + accept invite
|
||||
|
||||
## Phase 4: Submission Bundle Lifecycle + Document Locking
|
||||
|
||||
### Scope
|
||||
- Introduce submission rounds and bundle states in runtime
|
||||
- Enforce edit/read-only behavior by round and stage purpose
|
||||
- Support provenance-aware promotion from mentor workspace
|
||||
|
||||
### Exit Criteria
|
||||
- Applicants can only edit current round slots
|
||||
- Judges can see current + prior bundles by policy
|
||||
- Promotion events produce immutable trace
|
||||
|
||||
## Phase 5: Assignment Engine Hardening For Monaco Semantics
|
||||
|
||||
### Scope
|
||||
- Implement strict hard/soft cap behavior with buffer
|
||||
- Implement startup/concept weighting as soft-bias preference per judge (non-deterministic)
|
||||
- Implement deterministic unassigned queue and manual fallback
|
||||
|
||||
### Exit Criteria
|
||||
- Policy compliance report proves no hard-cap violations
|
||||
- Soft-cap overflow behavior matches configured buffer rules
|
||||
- Ratio/bias behavior is explainable and visibly disclosed as suggestive in onboarding and admin UI
|
||||
- Manual queue receives all residual items with reasons
|
||||
|
||||
## Phase 6: Awards + Mentoring + Finals + Confirmation
|
||||
|
||||
### Scope
|
||||
- Add award participation mode semantics, admin-confirmed pull-out flow, and single-judge award decision mode
|
||||
- Complete mentor workspace file/comment/promotion behavior
|
||||
- Link live finals to final confirmation workflow and result lock/unlock governance
|
||||
|
||||
### Exit Criteria
|
||||
- Mode A/B award behavior validated in staging scenarios, including admin-confirmed pull-out
|
||||
- Final confirmation requires configured jury agreement with quorum fallback + admin approval (or configured single-judge award path), with admin override support and audit trail
|
||||
- Result lock snapshot generated and immutable until explicit super-admin unlock workflow is used
|
||||
|
||||
## Phase 7: UX Consolidation And Operator Experience
|
||||
|
||||
### Scope
|
||||
- Simplify admin pipeline editors with purpose-aware controls
|
||||
- Remove/disable ambiguous config controls
|
||||
- Add context-rich dashboards and compliance panels
|
||||
|
||||
### Exit Criteria
|
||||
- Operators can configure full Monaco flow without advanced/manual JSON edits
|
||||
- Support docs and admin runbooks updated
|
||||
|
||||
## Phase 8: Cutover And Decommission Legacy Paths
|
||||
|
||||
### Scope
|
||||
- Enable new contracts by default
|
||||
- Deprecate legacy code paths and config fallback branches
|
||||
- cleanup migration of deprecated fields where safe
|
||||
|
||||
### Exit Criteria
|
||||
- Production traffic fully on new architecture
|
||||
- Legacy path usage dashboards show zero critical usage
|
||||
- post-cutover audit and incident-free burn-in period complete
|
||||
|
||||
## 3) Workstream Breakdown
|
||||
|
||||
## 3.1 Backend Workstream
|
||||
- Schema/migrations
|
||||
- Policy resolver
|
||||
- Router refactors
|
||||
- Event/audit normalization
|
||||
|
||||
## 3.2 Frontend Workstream
|
||||
- Admin pipeline UX
|
||||
- Member invite and onboarding flows
|
||||
- Applicant/jury/mentor stage-aware views
|
||||
- finals control + confirmation UI
|
||||
|
||||
## 3.3 Data/Operations Workstream
|
||||
- Backfills and integrity checks
|
||||
- Job monitoring and reconciliation scripts
|
||||
- release runbooks and rollback procedures
|
||||
|
||||
## 3.4 QA Workstream
|
||||
- End-to-end test scenarios for full Monaco flow
|
||||
- policy compliance assertions
|
||||
- performance and reliability testing
|
||||
|
||||
## 4) Migration Sequencing Rules
|
||||
1. No destructive migration before dual-read period completes.
|
||||
2. Every new write path must emit old + new audit evidence during transition.
|
||||
3. Use idempotent backfills with resumable checkpoints.
|
||||
4. Keep feature toggles per major subsystem (invite policy, assignment policy, docs, confirmation).
|
||||
|
||||
## 5) Rollback Strategy
|
||||
|
||||
### 5.1 Technical Rollback
|
||||
- Feature flag rollback first
|
||||
- Keep old write handlers until two stable releases after cutover
|
||||
- Avoid schema drops until rollback window closes
|
||||
|
||||
### 5.2 Operational Rollback
|
||||
- Predefined rollback runbook for each phase
|
||||
- operator checklist for reverting admin workflows
|
||||
- communication templates for judges/admins if rollback impacts active stages
|
||||
|
||||
## 6) Delivery Governance
|
||||
- Weekly architecture sync (backend/frontend/product/ops)
|
||||
- Phase gate reviews with evidence packages
|
||||
- Strict “no silent contract drift” policy for late-stage changes
|
||||
|
||||
## 7) Suggested Initial Milestones (Order)
|
||||
1. Approve purpose keys + jury model + assignment semantics.
|
||||
2. Implement schema foundation and context resolver.
|
||||
3. Integrate invite/onboarding/team flows.
|
||||
4. Enforce round bundle lifecycle.
|
||||
5. Harden assignment policy behavior.
|
||||
6. Complete awards/mentoring/finals/confirmation chain.
|
||||
@@ -0,0 +1,157 @@
|
||||
# 07. Testing, Observability, And Release Gates
|
||||
|
||||
## 1) QA Strategy
|
||||
The redesign is policy-heavy. Testing must validate:
|
||||
1. Functional correctness
|
||||
2. Policy compliance
|
||||
3. Audit completeness
|
||||
4. Role-based access integrity
|
||||
5. Operational resilience under load and deadline pressure
|
||||
|
||||
## 2) Test Pyramid
|
||||
|
||||
### 2.1 Unit Tests
|
||||
Target modules:
|
||||
- context resolver
|
||||
- policy resolver
|
||||
- assignment policy evaluator (hard/soft/buffer/category-bias weighting)
|
||||
- round bundle lock evaluator
|
||||
- final confirmation rule evaluator
|
||||
|
||||
### 2.2 Integration Tests
|
||||
Target flows:
|
||||
- stage transitions with purpose validation
|
||||
- filtering outcomes + override
|
||||
- assignment run + unassigned queue + manual assignment
|
||||
- document upload/edit lock transitions
|
||||
- mentor promotion pipeline
|
||||
- live voting -> confirmation -> result lock
|
||||
|
||||
### 2.3 End-to-End Tests
|
||||
Target user journeys:
|
||||
- applicant R1 -> eligibility -> Jury1 -> R2 -> Jury2 -> finals prep -> finals -> result
|
||||
- admin stage manager live finals operations
|
||||
- award mode A and mode B paths
|
||||
- admin invite -> onboarding -> jury assignment materialization
|
||||
- team invite -> accept invite -> team collaboration
|
||||
|
||||
## 3) Monaco Flow Test Matrix
|
||||
|
||||
| Flow Step | Required Test Cases |
|
||||
|---|---|
|
||||
| Submission R1 | open/close behavior, late policy modes, required docs enforcement |
|
||||
| Eligibility filter | deterministic pass/fail, AI banding, manual queue, admin override trail |
|
||||
| Jury1 | cap modes, category-bias preference behavior (suggestive only), deadline reminder triggers, score submission |
|
||||
| Submission R2 | R1 read-only for applicants, R2 editable, admin full override |
|
||||
| Jury2 | visibility of R1+R2 docs, finalist recommendation and override |
|
||||
| Awards | separate pool, dual track, admin-confirmed pull-out behavior, jury overlap, single-judge decision mode |
|
||||
| Mentoring | private file sharing, comments, promotion to official slot with provenance |
|
||||
| Jury3 live | stage manager controls, voting windows, notes, audience vote mode |
|
||||
| Final confirmation | unanimous jury agreement on active quorum (or configured rule), juror replacement/absence handling, single-judge award exception flow, admin finalize, admin override path, result lock |
|
||||
|
||||
## 4) Invite/Member/Onboarding Test Matrix (Critical)
|
||||
|
||||
| Workflow | Must Validate |
|
||||
|---|---|
|
||||
| Admin member invite (`/admin/members/invite`) | creates user + jury membership + selected pre-assignment mode (intent and/or direct policy-validated assignment); respects role authorization |
|
||||
| Bulk invite CSV | invalid rows, duplicate handling, unauthorized role attempts, staged pre-assignment mode selection and materialization |
|
||||
| Invite acceptance (`/accept-invite`) | token validity, role-context preview, routing to correct onboarding path |
|
||||
| Jury onboarding | cap/bias override onboarding when enabled, including explicit disclosure that category bias is a suggestion not a rule |
|
||||
| Team invite (`/applicant/team`) | lead-only invite/remove, account setup vs existing account behavior |
|
||||
| Cross-context conflict | same user invited as jury and team member still resolves correct permissions by context |
|
||||
|
||||
## 5) Regression Coverage Extension Against Existing Test Suite
|
||||
Current suite already has useful coverage (`tests/unit/*`, `tests/integration/*`). Extend with:
|
||||
|
||||
1. `tests/unit/assignment-policy-hard-soft.test.ts`
|
||||
2. `tests/unit/final-confirmation-rules.test.ts`
|
||||
3. `tests/integration/invite-jury-membership-intent.test.ts`
|
||||
4. `tests/integration/submission-bundle-locking.test.ts`
|
||||
5. `tests/integration/mentor-promotion-provenance.test.ts`
|
||||
6. `tests/integration/award-mode-routing.test.ts`
|
||||
7. `tests/integration/live-to-final-lock.test.ts`
|
||||
|
||||
## 6) Audit Completeness Checks
|
||||
Add automated assertions that every critical operation emits both domain event and audit record:
|
||||
- eligibility override
|
||||
- assignment exception
|
||||
- stage advancement override
|
||||
- award winner override
|
||||
- promotion event
|
||||
- final confirmation finalize/lock
|
||||
|
||||
Failure to emit required audit evidence should fail tests.
|
||||
|
||||
## 7) Observability Blueprint
|
||||
|
||||
## 7.1 Metrics
|
||||
|
||||
### Competition Lifecycle Metrics
|
||||
- `projects_submitted_total` by category and stage
|
||||
- `eligibility_pass_rate`
|
||||
- `manual_review_rate`
|
||||
- `assignment_coverage_percent`
|
||||
- `unassigned_projects_count`
|
||||
- `over_cap_exception_count`
|
||||
- `submission_late_rate`
|
||||
- `mentor_promotion_count`
|
||||
- `live_vote_completion_rate`
|
||||
- `final_confirmation_duration_seconds`
|
||||
|
||||
### Reliability Metrics
|
||||
- API latency by router
|
||||
- background job success/failure rates (filtering/assignment/award jobs)
|
||||
- reminder send success/failure
|
||||
- invitation send success/failure
|
||||
|
||||
## 7.2 Logs And Tracing
|
||||
- Correlation id per operation across router -> service -> DB writes
|
||||
- Structured logs include `programId`, `stageId`, `stagePurposeKey`, `juryId`, `projectId`, `userId`
|
||||
|
||||
## 7.3 Alerts
|
||||
- assignment run leaves residual without queue record
|
||||
- final confirmation attempted without satisfied quorum requirement
|
||||
- result lock write failure
|
||||
- result unlock attempted by non-super-admin
|
||||
- invite acceptance failures spike
|
||||
- live voting session state mismatch (open with no active project)
|
||||
|
||||
## 8) Release Gates (Must Pass)
|
||||
|
||||
## Gate A: Schema + Backfill Readiness
|
||||
- all migrations idempotent in staging
|
||||
- no unresolved backfill anomalies
|
||||
|
||||
## Gate B: Policy Engine Correctness
|
||||
- hard/soft cap test pass
|
||||
- ratio policy test pass
|
||||
- access resolver test pass
|
||||
|
||||
## Gate C: End-To-End Flow Simulation
|
||||
- full Monaco dry run with seeded data and mixed categories
|
||||
- award mode A/B dry runs
|
||||
|
||||
## Gate D: Invite/Onboarding Stability
|
||||
- admin invite + team invite + acceptance flows pass under load
|
||||
|
||||
## Gate E: Finals And Confirmation Integrity
|
||||
- live voting and final confirmation produce correct lock artifacts
|
||||
- super-admin unlock/relock path preserves complete audit integrity
|
||||
|
||||
## Gate F: Operational Readiness
|
||||
- runbooks approved
|
||||
- dashboards and alerts active
|
||||
- support playbooks distributed
|
||||
|
||||
## 9) Performance And Capacity Scenarios
|
||||
- Large intake window close with bulk late submissions
|
||||
- Filtering and assignment jobs across high project volume
|
||||
- Live finals peak voting concurrency (jury + audience)
|
||||
- Bulk invitation campaigns with email retries
|
||||
|
||||
## 10) Sign-Off Criteria
|
||||
Release is approved only when:
|
||||
1. All phase gates pass.
|
||||
2. No Sev-1/Sev-2 defects remain open in critical competition flows.
|
||||
3. Audit completeness checks pass for all critical operations.
|
||||
4. Operators can execute runbook drills successfully.
|
||||
@@ -0,0 +1,88 @@
|
||||
# 08. Open Questions For Flow Owners
|
||||
|
||||
## 1) Resolved Decisions (Captured)
|
||||
As of Sunday, February 15, 2026, the following decisions are confirmed:
|
||||
|
||||
1. Final confirmation scope:
|
||||
- Unanimity applies by default to category winners and jury-based award winners.
|
||||
- Admin override must be possible in both cases with full audit reasoning.
|
||||
- Some special awards can use a single-judge decision mode after eligibility filtering.
|
||||
|
||||
2. Soft-cap buffer:
|
||||
- Default soft-cap buffer is `+10`.
|
||||
|
||||
3. Startup/concept ratio behavior:
|
||||
- Ratio is a slight bias/suggestion only.
|
||||
- It must not be fully deterministic.
|
||||
- Onboarding must explicitly disclose this to judges.
|
||||
|
||||
4. Mode A pull-out behavior:
|
||||
- Pull-out from main pool is admin-confirmed (not automatic).
|
||||
|
||||
5. Mentoring promotion authority:
|
||||
- Promotion to official submission is allowed for team lead + admin.
|
||||
|
||||
6. Admin member invite pre-assignment:
|
||||
- Both modes should be supported when possible:
|
||||
- assignment intent mode
|
||||
- direct policy-validated assignment mode
|
||||
|
||||
7. Jury absence during final confirmation:
|
||||
- Quorum fallback is allowed.
|
||||
- If a judge is absent, admins can either:
|
||||
- replace the judge, or
|
||||
- mark the judge as absent so they do not count toward required confirmation votes.
|
||||
|
||||
8. Result unlock policy:
|
||||
- Unlock after finalization is allowed only for super admins.
|
||||
- Unlock must require explicit reason/audit metadata.
|
||||
|
||||
9. Jury identity naming:
|
||||
- Main and award juries are custom-labeled.
|
||||
- Runtime behavior binds to jury purpose/stage contracts, not fixed `Jury1/Jury2/Jury3` labels.
|
||||
|
||||
## 2) Remaining P0 Questions (Need Before Schema Freeze)
|
||||
None as of Sunday, February 15, 2026.
|
||||
|
||||
## 3) Remaining P1 Questions (Needed Before UI/Router Refactor)
|
||||
|
||||
1. Judge self-service onboarding controls:
|
||||
- Are judges allowed to edit their own cap/bias preferences during onboarding for both main semi-final and finalist juries, or admin-only?
|
||||
|
||||
2. Mentoring stage applicability:
|
||||
- Is mentoring strictly finalists-only by default, or configurable to include semi-finalists?
|
||||
|
||||
3. Document mutability after lock:
|
||||
- Can admins replace locked submissions post-deadline, and should applicants see replacement history?
|
||||
|
||||
4. Audience reveal timing:
|
||||
- Should audience totals be visible to Jury 3 in real time or only at deliberation start?
|
||||
|
||||
## 4) Remaining P2 Questions
|
||||
|
||||
1. Reporting visibility:
|
||||
- Should per-jury cap/bias compliance be visible to all admins or only super admins?
|
||||
|
||||
2. Override transparency:
|
||||
- Which override details are visible to jury users versus admin-only?
|
||||
|
||||
3. Applicant communication policy:
|
||||
- Which exact transitions trigger applicant notifications?
|
||||
|
||||
4. Tie-break policy ordering:
|
||||
- Confirm strict precedence when ties remain after configured scoring.
|
||||
|
||||
## 5) Invite/Onboarding Follow-Up Questions
|
||||
|
||||
1. Invitation expiry policy:
|
||||
- Keep role-specific invite expiry differences (7-day admin invite vs 30-day team invite) or unify?
|
||||
|
||||
2. Multi-role default landing:
|
||||
- If a user is both jury and applicant team member, what is default post-login landing and should role-switch be mandatory?
|
||||
|
||||
3. CSV template scope:
|
||||
- Should CSV bulk invite support explicit jury binding + stage + pre-assignment mode columns?
|
||||
|
||||
## 6) Suggested Defaults For Remaining Items
|
||||
1. Judges can edit cap/bias in onboarding only when admin enables this per jury.
|
||||
2. Mentoring defaults to finalists-only, with optional semi-finalist extension.
|
||||
@@ -0,0 +1,153 @@
|
||||
# 09. Appendix: System Inventory (As Reviewed)
|
||||
|
||||
## 1) Data Model Inventory (Selected Competition-Critical Models)
|
||||
|
||||
### Pipeline/Stage Engine
|
||||
- `Pipeline`
|
||||
- `Track`
|
||||
- `Stage`
|
||||
- `StageTransition`
|
||||
- `ProjectStageState`
|
||||
- `Cohort`
|
||||
- `CohortProject`
|
||||
- `LiveProgressCursor`
|
||||
- `OverrideAction`
|
||||
- `DecisionAuditLog`
|
||||
|
||||
### Assignment/Evaluation
|
||||
- `Assignment`
|
||||
- `AssignmentJob`
|
||||
- `Evaluation`
|
||||
- `EvaluationForm`
|
||||
- `EvaluationSummary`
|
||||
- `EvaluationDiscussion`
|
||||
- `DiscussionComment`
|
||||
- `ConflictOfInterest`
|
||||
- `GracePeriod`
|
||||
- `ReminderLog`
|
||||
|
||||
### Filtering
|
||||
- `FilteringRule`
|
||||
- `FilteringResult`
|
||||
- `FilteringJob`
|
||||
|
||||
### Awards
|
||||
- `SpecialAward`
|
||||
- `AwardEligibility`
|
||||
- `AwardJuror`
|
||||
- `AwardVote`
|
||||
|
||||
### Mentorship
|
||||
- `MentorAssignment`
|
||||
- `MentorMessage`
|
||||
- `MentorNote`
|
||||
- `MentorMilestone`
|
||||
- `MentorMilestoneCompletion`
|
||||
|
||||
### Documents/Submission
|
||||
- `FileRequirement`
|
||||
- `ProjectFile`
|
||||
|
||||
### Live Voting
|
||||
- `LiveVotingSession`
|
||||
- `LiveVote`
|
||||
- `AudienceVoter`
|
||||
|
||||
### Identity/Team
|
||||
- `User`
|
||||
- `TeamMember`
|
||||
|
||||
## 2) Service Inventory (Competition-Critical)
|
||||
- `src/server/services/stage-engine.ts`
|
||||
- `src/server/services/stage-filtering.ts`
|
||||
- `src/server/services/stage-assignment.ts`
|
||||
- `src/server/services/live-control.ts`
|
||||
- `src/server/services/stage-notifications.ts`
|
||||
- `src/server/services/evaluation-reminders.ts`
|
||||
- `src/server/services/smart-assignment.ts`
|
||||
- `src/server/services/ai-assignment.ts`
|
||||
- `src/server/services/ai-filtering.ts`
|
||||
- `src/server/services/award-eligibility-job.ts`
|
||||
- `src/server/services/mentor-matching.ts`
|
||||
|
||||
## 3) tRPC Router Inventory
|
||||
- `program`
|
||||
- `project`
|
||||
- `user`
|
||||
- `assignment`
|
||||
- `evaluation`
|
||||
- `file`
|
||||
- `export`
|
||||
- `audit`
|
||||
- `settings`
|
||||
- `gracePeriod`
|
||||
- `learningResource`
|
||||
- `partner`
|
||||
- `notionImport`
|
||||
- `typeformImport`
|
||||
- `tag`
|
||||
- `applicant`
|
||||
- `liveVoting`
|
||||
- `analytics`
|
||||
- `avatar`
|
||||
- `logo`
|
||||
- `application`
|
||||
- `mentor`
|
||||
- `filtering`
|
||||
- `specialAward`
|
||||
- `notification`
|
||||
- `message`
|
||||
- `webhook`
|
||||
- `projectPool`
|
||||
- `wizardTemplate`
|
||||
- `dashboard`
|
||||
- `pipeline`
|
||||
- `stage`
|
||||
- `stageFiltering`
|
||||
- `stageAssignment`
|
||||
- `cohort`
|
||||
- `live`
|
||||
- `decision`
|
||||
- `award`
|
||||
|
||||
## 4) Page Inventory (High-Level by Role Group)
|
||||
|
||||
### Admin
|
||||
- members, invite members, programs, apply settings, pipeline wizard/advanced/editor, projects, mentors, awards, reports, settings, audit, messaging, partner, learning
|
||||
|
||||
### Applicant
|
||||
- dashboard, team, pipeline views, stage docs/status views, mentoring, document center
|
||||
|
||||
### Jury
|
||||
- stage list, assignment list, project evaluate pages, compare page, live page, awards, learning
|
||||
|
||||
### Mentor
|
||||
- dashboard, projects, project detail, resources
|
||||
|
||||
### Auth/Public
|
||||
- apply, edition apply, accept invite, login, onboarding, set password, public vote/live score, submission pages
|
||||
|
||||
## 5) Existing Test Inventory
|
||||
|
||||
### Unit
|
||||
- `tests/unit/stage-engine.test.ts`
|
||||
- `tests/unit/stage-assignment.test.ts`
|
||||
- `tests/unit/stage-filtering.test.ts`
|
||||
- `tests/unit/live-control.test.ts`
|
||||
- `tests/unit/override-validation.test.ts`
|
||||
- `tests/unit/award-governance.test.ts`
|
||||
|
||||
### Integration
|
||||
- `tests/integration/pipeline-crud.test.ts`
|
||||
- `tests/integration/stage-config.test.ts`
|
||||
- `tests/integration/assignment-preview.test.ts`
|
||||
- `tests/integration/cohort-voting.test.ts`
|
||||
- `tests/integration/live-runtime.test.ts`
|
||||
- `tests/integration/decision-audit.test.ts`
|
||||
|
||||
## 6) Legacy/Transition Observations
|
||||
1. `roundId` fields still exist as legacy optional references in multiple models.
|
||||
2. Stage/pipeline is active architecture but legacy wording remains in some routers/comments/UI labels.
|
||||
3. Some critical business rules still rely on JSON keys and implicit route behavior.
|
||||
|
||||
This inventory is the baseline used for the redesign and migration plans in this folder.
|
||||
@@ -0,0 +1,162 @@
|
||||
# 10. Monaco Reference Configuration (Example)
|
||||
|
||||
This is an example of how a Monaco 2026 competition would be configured in the redesigned system.
|
||||
|
||||
## 1) Program Profile
|
||||
- Program: Monaco Ocean Protection Challenge 2026
|
||||
- Categories: `STARTUP`, `BUSINESS_CONCEPT`
|
||||
- Main pipeline: `mopc-2026-main`
|
||||
- Award tracks: configurable per award
|
||||
|
||||
## 2) Stage Purpose Layout (Main Track)
|
||||
|
||||
1. `submission_r1_intake`
|
||||
- type: `INTAKE`
|
||||
- open: 2026-02-01
|
||||
- close: 2026-05-31
|
||||
- late policy: `flag`
|
||||
|
||||
2. `eligibility_filter`
|
||||
- type: `FILTER`
|
||||
- trigger: admin or auto-on-close
|
||||
|
||||
3. `jury1_evaluation`
|
||||
- type: `EVALUATION`
|
||||
- open: 2026-06-05
|
||||
- close: 2026-06-25
|
||||
- jury binding: `MAIN_SEMIFINAL`
|
||||
|
||||
4. `submission_r2_intake`
|
||||
- type: `INTAKE`
|
||||
- open: 2026-06-28
|
||||
- close: 2026-07-20
|
||||
|
||||
5. `jury2_evaluation`
|
||||
- type: `EVALUATION`
|
||||
- open: 2026-07-24
|
||||
- close: 2026-08-10
|
||||
- jury binding: `MAIN_FINALIST`
|
||||
|
||||
6. `jury3_live_finals`
|
||||
- type: `LIVE_FINAL`
|
||||
- event date window: 2026-09-01
|
||||
- jury binding: `MAIN_LIVE_FINALS`
|
||||
|
||||
7. `final_confirmation`
|
||||
- type: `SELECTION`
|
||||
- rule: unanimous active quorum + one admin approval
|
||||
- absent juror handling: replace juror or mark as excused (admin-audited)
|
||||
- admin override: enabled for both category and award scopes (mandatory reason/audit)
|
||||
- unlock policy: super-admin only
|
||||
|
||||
8. `results_publication`
|
||||
- type: `RESULTS`
|
||||
- publication mode: manual
|
||||
|
||||
## 3) Jury Definitions
|
||||
|
||||
- `MAIN_SEMIFINAL` (display label example: `Jury 1 - Technical Panel`)
|
||||
- Purpose: semi-final selection
|
||||
- members: list of judges
|
||||
- `MAIN_FINALIST` (display label example: `Jury 2 - Selection Panel`)
|
||||
- Purpose: finalist selection
|
||||
- members: list of judges (overlap allowed)
|
||||
- `MAIN_LIVE_FINALS` (display label example: `Jury 3 - Live Finals Panel`)
|
||||
- Purpose: live final voting + deliberation
|
||||
- members: list of judges (overlap allowed)
|
||||
|
||||
## 4) Assignment Policy Example
|
||||
|
||||
### Jury1 policy
|
||||
- required reviews: 3
|
||||
- default cap mode: `SOFT`
|
||||
- default cap: 25
|
||||
- buffer: 10
|
||||
- startup/concept bias target per judge: 50/50 (suggestive, not deterministic)
|
||||
|
||||
### Per-judge override example
|
||||
- judge A: hard cap 18
|
||||
- judge B: soft cap 22 buffer 8
|
||||
- judge C: startup-biased preference (100/0 suggestion, not hard rule)
|
||||
|
||||
## 5) Submission Round Requirements
|
||||
|
||||
### Round 1 (`submission_r1_intake`)
|
||||
Slots:
|
||||
- `r1_exec_summary` (required)
|
||||
- `r1_pitch_deck` (required)
|
||||
- `r1_video_pitch` (optional)
|
||||
|
||||
### Round 2 (`submission_r2_intake`)
|
||||
Slots:
|
||||
- `r2_business_plan` (required)
|
||||
- `r2_financials` (required)
|
||||
- `r2_impact_metrics` (optional)
|
||||
|
||||
Behavior:
|
||||
- applicants edit current round only
|
||||
- previous round read-only
|
||||
- admin can replace with provenance
|
||||
|
||||
## 6) Award Mode Examples
|
||||
|
||||
### Example A: Separate Pool, Pull-Out
|
||||
- award: “Blue Innovation Prize”
|
||||
- participationMode: `SEPARATE_POOL`
|
||||
- routingBehavior: `PULL_FROM_MAIN`
|
||||
- pull-out confirmation: admin-confirmed before removal from main pool
|
||||
|
||||
### Example B: Dual Track
|
||||
- award: “Community Impact Award”
|
||||
- participationMode: `DUAL_TRACK`
|
||||
- routingBehavior: `KEEP_IN_MAIN`
|
||||
|
||||
### Example C: Single-Judge Award
|
||||
- award: “Chair’s Special Recognition”
|
||||
- winnerDecisionMode: `SINGLE_JUDGE_DECIDES`
|
||||
- singleJudgeUserId: configured award judge
|
||||
- candidate set: only projects remaining eligible after award filtering
|
||||
|
||||
## 7) Mentoring Layer Example
|
||||
|
||||
Eligibility:
|
||||
- finalist projects with `wantsMentorship=true`
|
||||
|
||||
Permissions:
|
||||
- mentor and team can upload/comment private files
|
||||
- team lead + admin can promote file to official submission
|
||||
|
||||
Promotion artifact:
|
||||
- records source file, target slot, actor, timestamp, resulting official file id
|
||||
|
||||
## 8) Live Finals Example
|
||||
|
||||
- voting mode: criteria
|
||||
- audience voting: enabled for end-of-category only
|
||||
- audience totals visible to Jury3 during deliberation: true
|
||||
- tie-break order:
|
||||
1. highest Jury3 weighted score
|
||||
2. admin-declared tie-break (if still tied)
|
||||
|
||||
## 9) Final Confirmation Example
|
||||
|
||||
- decision rule: unanimous (categories + jury-based awards)
|
||||
- active quorum must submit confirmation vote (absent juror can be replaced or marked excused)
|
||||
- admin approval required after quorum unanimity
|
||||
- admin override allowed for category or award outcomes with mandatory reason code and audit snapshot
|
||||
- result lock snapshot generated immediately on finalize
|
||||
- unlock available only to super admins with mandatory reason + unlock event audit
|
||||
|
||||
## 10) Invite Flow Example
|
||||
|
||||
### Admin invite (jury)
|
||||
- create user with role `JURY_MEMBER`
|
||||
- attach `JuryMembership: MAIN_FINALIST` (custom display label in UI)
|
||||
- create optional `AssignmentIntent` for stage `jury2_evaluation` and/or direct policy-validated assignments
|
||||
- send invitation
|
||||
- on accept: jury onboarding -> cap/bias preference override if allowed (disclosure shown that bias is suggestive only)
|
||||
|
||||
### Team invite
|
||||
- create/attach `TeamMember`
|
||||
- send invitation
|
||||
- on accept: applicant context landing
|
||||
65
docs/codex-architecture-redesign-docs/README.md
Normal file
65
docs/codex-architecture-redesign-docs/README.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Monaco OPC Architecture Redesign (Codex Plan)
|
||||
|
||||
## Purpose
|
||||
This documentation set is a comprehensive redesign plan to align the current MOPC platform with the exact Monaco Ocean Protection Challenge flow you defined:
|
||||
|
||||
- Startups + Concepts in one competition lifecycle
|
||||
- AI eligibility filtering
|
||||
- Purpose-bound main juries as explicit entities (custom-labeled per program; often Jury 1 / Jury 2 / Jury 3)
|
||||
- Round-specific submission bundles
|
||||
- Special award routing modes
|
||||
- Mentoring collaboration layer with promotion to official submissions
|
||||
- Live finals control + final confirmation/lock workflow
|
||||
- Full admin override and auditability
|
||||
- End-to-end integration across all platform functions (including member invitation/onboarding/team flows)
|
||||
|
||||
The plan is intentionally designed to reduce current ambiguity and complexity while maximizing customizability through typed policies and explicit workflow entities.
|
||||
|
||||
## Scope Of This Plan
|
||||
This plan covers:
|
||||
|
||||
1. Current-state architecture audit (schema, services, routers, UI surfaces)
|
||||
2. Target-state architecture mapped 1:1 to Monaco flow
|
||||
3. Gap analysis and simplification decisions
|
||||
4. Typed domain model and policy contracts
|
||||
5. Platform-wide integration matrix (all major functions/pages)
|
||||
6. Implementation roadmap and migration/cutover strategy
|
||||
7. QA, observability, release gates
|
||||
8. Open decisions/questions for flow owners
|
||||
|
||||
This plan does **not** implement code changes. It is an implementation-ready architecture and delivery blueprint.
|
||||
|
||||
## Guiding Principles
|
||||
1. Keep the stage engine; remove ambiguity around stage purpose.
|
||||
2. Move critical competition behavior from loosely-typed `configJson` into typed models/policies.
|
||||
3. Preserve admin override authority everywhere, but formalize override intent and audit structure.
|
||||
4. Make jury/award/mentoring/finals flows first-class entities instead of inferred behavior.
|
||||
5. Keep UX simple by exposing only context-relevant controls at each stage.
|
||||
6. Ensure every user-facing workflow is backed by the redesigned architecture contract.
|
||||
|
||||
## Document Index
|
||||
- `01-current-platform-architecture-audit.md`
|
||||
- `02-monaco-flow-target-architecture.md`
|
||||
- `03-gap-analysis-and-simplification-decisions.md`
|
||||
- `04-unified-domain-model-and-config-contracts.md`
|
||||
- `05-platform-wide-integration-matrix.md`
|
||||
- `06-implementation-roadmap-and-migration-plan.md`
|
||||
- `07-testing-observability-and-release-gates.md`
|
||||
- `08-open-questions-for-flow-owners.md`
|
||||
|
||||
## Recommended Reading Order
|
||||
1. Read `02-monaco-flow-target-architecture.md` for the desired end state.
|
||||
2. Read `03-gap-analysis-and-simplification-decisions.md` to understand what must change and why.
|
||||
3. Read `04-unified-domain-model-and-config-contracts.md` for schema/API/behavior contracts.
|
||||
4. Read `05-platform-wide-integration-matrix.md` to see exact surface-level impact.
|
||||
5. Read `06-implementation-roadmap-and-migration-plan.md` + `07-testing-observability-and-release-gates.md` for execution.
|
||||
6. Resolve items in `08-open-questions-for-flow-owners.md` before Phase 1 starts.
|
||||
|
||||
## Success Criteria
|
||||
The redesign is successful when:
|
||||
|
||||
- The platform can run your full Monaco flow without workarounds.
|
||||
- Admins can configure and override all required decisions transparently.
|
||||
- Judges, mentors, applicants, and audience each see role-appropriate, stage-aware UX.
|
||||
- Invite/onboarding/team management, assignment, judging, mentoring, and finals workflows all reference the same underlying competition model.
|
||||
- Audit evidence can reconstruct every advance/reject/override/winner decision.
|
||||
Reference in New Issue
Block a user