4.0 KiB
Unified Architecture Redesign — Monaco Ocean Protection Challenge
Status: Design specification (pre-implementation) Date: 2026-02-15 Scope: Complete redesign of the round/pipeline system for multi-round competition management
Overview
This document set specifies the architecture redesign for the MOPC platform's competition system. The core change eliminates the Track abstraction layer and renames Pipeline → Competition, Stage → Round, producing a flat, linear round sequence with typed configurations per round type.
The design supports the full Monaco 2026 competition flow: Intake → AI Filtering → Jury 1 Evaluation → Semifinal Submission → Jury 2 Evaluation + Special Awards → Mentoring → Live Finals (Jury 3) → Deliberation → Result Lock.
Document Index
| # | Document | Description |
|---|---|---|
| 01 | Architecture & Decisions | Core decisions, ADRs, guiding principles, before/after architecture |
| 02 | Data Model | Complete Prisma schema, typed config Zod schemas, enum definitions |
| 03 | Competition Flow | Round-by-round specification (R1–R8) with cross-cutting behaviors |
| 04 | Jury Groups & Assignment Policy | JuryGroup model, cap modes, assignment algorithm, policy precedence |
| 05 | Special Awards | Award modes (stay-in-main vs separate pool), per-award pipelines |
| 06 | Mentoring & Document Lifecycle | Multi-round submissions, mentor workspace, file promotion |
| 07 | Live Finals & Deliberation | Stage manager, Jury 3 live experience, deliberation voting, ResultLock |
| 08 | Platform Integration Matrix | Page-by-page impact map for admin, jury, applicant, mentor UIs |
| 09 | Implementation Roadmap | 9-phase plan with dependencies, durations, rollback points |
| 10 | Migration Strategy | 4-phase schema migration, feature flags, data mapping, rollback |
| 11 | Testing & QA | Test pyramid, Monaco flow test matrix, deliberation test matrix |
| 12 | Observability & Release Gates | Metrics, structured logging, alerts, release gates A–F |
| 13 | Open Questions & Governance | Resolved decisions, remaining P1/P2 questions, delivery governance |
Recommended Reading Order
- 01 Architecture & Decisions — understand the "why" and core decisions
- 02 Data Model — the schema that everything builds on
- 03 Competition Flow — how the 8 rounds work end-to-end
- 04–07 — deep dives into specific subsystems (read as needed)
- 08 Integration Matrix — understand the blast radius across the platform
- 09–10 — implementation and migration planning
- 11–12 — quality and operational readiness
- 13 Open Questions — remaining decisions and governance
Key Terminology
| Old Term | New Term | Notes |
|---|---|---|
| Pipeline | Competition | Top-level competition round container |
| Stage | Round | Individual phase within a competition |
| Track | (eliminated) | Replaced by SpecialAward with routing modes |
| StageType | RoundType | INTAKE, FILTERING, EVALUATION, SUBMISSION, MENTORING, LIVE_FINAL, DELIBERATION |
| configJson | Typed Config | Per-round-type Zod-validated configuration |
| WinnerProposal | DeliberationSession | New deliberation voting model |
| WinnerApproval | DeliberationVote | Per-juror vote in deliberation |
| Confirmation | Deliberation | Deliberation IS the confirmation step |
Cross-References
All documents cross-reference each other by filename (e.g., "see 02-data-model.md"). Model names, config types, and enum values are consistent across all documents.