62 lines
4.0 KiB
Markdown
62 lines
4.0 KiB
Markdown
|
# 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](./01-architecture-and-decisions.md) | Core decisions, ADRs, guiding principles, before/after architecture |
|
|||
|
|
| 02 | [Data Model](./02-data-model.md) | Complete Prisma schema, typed config Zod schemas, enum definitions |
|
|||
|
|
| 03 | [Competition Flow](./03-competition-flow.md) | Round-by-round specification (R1–R8) with cross-cutting behaviors |
|
|||
|
|
| 04 | [Jury Groups & Assignment Policy](./04-jury-groups-and-assignment-policy.md) | JuryGroup model, cap modes, assignment algorithm, policy precedence |
|
|||
|
|
| 05 | [Special Awards](./05-special-awards.md) | Award modes (stay-in-main vs separate pool), per-award pipelines |
|
|||
|
|
| 06 | [Mentoring & Document Lifecycle](./06-mentoring-and-document-lifecycle.md) | Multi-round submissions, mentor workspace, file promotion |
|
|||
|
|
| 07 | [Live Finals & Deliberation](./07-live-finals-and-deliberation.md) | Stage manager, Jury 3 live experience, deliberation voting, ResultLock |
|
|||
|
|
| 08 | [Platform Integration Matrix](./08-platform-integration-matrix.md) | Page-by-page impact map for admin, jury, applicant, mentor UIs |
|
|||
|
|
| 09 | [Implementation Roadmap](./09-implementation-roadmap.md) | 9-phase plan with dependencies, durations, rollback points |
|
|||
|
|
| 10 | [Migration Strategy](./10-migration-strategy.md) | 4-phase schema migration, feature flags, data mapping, rollback |
|
|||
|
|
| 11 | [Testing & QA](./11-testing-and-qa.md) | Test pyramid, Monaco flow test matrix, deliberation test matrix |
|
|||
|
|
| 12 | [Observability & Release Gates](./12-observability-and-release-gates.md) | Metrics, structured logging, alerts, release gates A–F |
|
|||
|
|
| 13 | [Open Questions & Governance](./13-open-questions-and-governance.md) | Resolved decisions, remaining P1/P2 questions, delivery governance |
|
|||
|
|
|
|||
|
|
## Recommended Reading Order
|
|||
|
|
|
|||
|
|
1. **01 Architecture & Decisions** — understand the "why" and core decisions
|
|||
|
|
2. **02 Data Model** — the schema that everything builds on
|
|||
|
|
3. **03 Competition Flow** — how the 8 rounds work end-to-end
|
|||
|
|
4. **04–07** — deep dives into specific subsystems (read as needed)
|
|||
|
|
5. **08 Integration Matrix** — understand the blast radius across the platform
|
|||
|
|
6. **09–10** — implementation and migration planning
|
|||
|
|
7. **11–12** — quality and operational readiness
|
|||
|
|
8. **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](./02-data-model.md)"). Model names, config types, and enum values are consistent across all documents.
|