202 lines
11 KiB
Markdown
202 lines
11 KiB
Markdown
|
# Executive Summary: MOPC Architecture Redesign
|
||
|
|
|
||
|
|
## Why This Redesign
|
||
|
|
|
||
|
|
The MOPC platform currently uses a **Pipeline -> Track -> Stage** model with generic JSON configs to orchestrate the competition. While technically sound, this architecture introduces unnecessary abstraction for what is fundamentally a **linear sequential competition flow**.
|
||
|
|
|
||
|
|
### Current Problems
|
||
|
|
|
||
|
|
| Problem | Impact |
|
||
|
|
|---------|--------|
|
||
|
|
| **3-level nesting** (Pipeline->Track->Stage) | Cognitive overhead for admins configuring rounds |
|
||
|
|
| **Generic `configJson` blobs** per stage type | "Vague" — hard to know what's configurable without reading code |
|
||
|
|
| **No explicit jury entities** | Juries are implicit (per-stage assignments), can't manage "Jury 1" as a thing |
|
||
|
|
| **Single submission round** | No way to open a second submission window for semi-finalists |
|
||
|
|
| **Track layer for main flow** | MAIN track adds indirection without value for a linear flow |
|
||
|
|
| **No mentoring workspace** | Mentor file exchange exists but no comments, no promotion to submission |
|
||
|
|
| **No winner confirmation** | No multi-party agreement step to cement winners |
|
||
|
|
| **Missing round types** | Can't model a "Semi-finalist Submission" or "Mentoring" or "Confirmation" step |
|
||
|
|
|
||
|
|
### Design Principles
|
||
|
|
|
||
|
|
1. **Domain over abstraction** — Models map directly to competition concepts (Jury 1, Round 2, etc.)
|
||
|
|
2. **Linear by default** — The main flow is sequential. Branching is only for special awards.
|
||
|
|
3. **Typed configs over JSON blobs** — Each round type has explicit, documented fields.
|
||
|
|
4. **Explicit entities** — Juries, submission windows, and confirmation steps are first-class models.
|
||
|
|
5. **Deep integration** — Every feature connects. Jury groups link to rounds, rounds link to submissions, submissions link to evaluations.
|
||
|
|
6. **Admin override everywhere** — Any automated decision can be manually overridden with audit trail.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Before & After: Architecture Comparison
|
||
|
|
|
||
|
|
### BEFORE (Current System)
|
||
|
|
|
||
|
|
```
|
||
|
|
Program
|
||
|
|
└── Pipeline (generic container)
|
||
|
|
├── Track: "Main Competition" (MAIN)
|
||
|
|
│ ├── Stage: "Intake" (INTAKE, configJson: {...})
|
||
|
|
│ ├── Stage: "Filtering" (FILTER, configJson: {...})
|
||
|
|
│ ├── Stage: "Evaluation" (EVALUATION, configJson: {...})
|
||
|
|
│ ├── Stage: "Selection" (SELECTION, configJson: {...})
|
||
|
|
│ ├── Stage: "Live Finals" (LIVE_FINAL, configJson: {...})
|
||
|
|
│ └── Stage: "Results" (RESULTS, configJson: {...})
|
||
|
|
├── Track: "Award 1" (AWARD)
|
||
|
|
│ ├── Stage: "Evaluation" (EVALUATION)
|
||
|
|
│ └── Stage: "Results" (RESULTS)
|
||
|
|
└── Track: "Award 2" (AWARD)
|
||
|
|
├── Stage: "Evaluation" (EVALUATION)
|
||
|
|
└── Stage: "Results" (RESULTS)
|
||
|
|
|
||
|
|
Juries: implicit (assignments per stage, no named entity)
|
||
|
|
Submissions: single round (one INTAKE stage)
|
||
|
|
Mentoring: basic (messages + notes, no workspace)
|
||
|
|
Winner confirmation: none
|
||
|
|
```
|
||
|
|
|
||
|
|
### AFTER (Redesigned System)
|
||
|
|
|
||
|
|
```
|
||
|
|
Program
|
||
|
|
└── Competition (purpose-built, replaces Pipeline)
|
||
|
|
├── Rounds (linear sequence, replaces Track+Stage):
|
||
|
|
│ ├── Round 1: "Application Window" ─────── (INTAKE)
|
||
|
|
│ ├── Round 2: "AI Screening" ──────────── (FILTERING)
|
||
|
|
│ ├── Round 3: "Jury 1 - Semi-finalist" ── (EVALUATION) ── juryGroupId: jury-1
|
||
|
|
│ ├── Round 4: "Semi-finalist Docs" ─────── (SUBMISSION) ── submissionWindowId: sw-2
|
||
|
|
│ ├── Round 5: "Jury 2 - Finalist" ──────── (EVALUATION) ── juryGroupId: jury-2
|
||
|
|
│ ├── Round 6: "Finalist Mentoring" ─────── (MENTORING)
|
||
|
|
│ ├── Round 7: "Live Finals" ────────────── (LIVE_FINAL) ── juryGroupId: jury-3
|
||
|
|
│ └── Round 8: "Confirm Winners" ─────────── (CONFIRMATION)
|
||
|
|
│
|
||
|
|
├── Jury Groups (explicit, named):
|
||
|
|
│ ├── "Jury 1" ── members: [judge-a, judge-b, ...] ── linked to Round 3
|
||
|
|
│ ├── "Jury 2" ── members: [judge-c, judge-d, ...] ── linked to Round 5
|
||
|
|
│ └── "Jury 3" ── members: [judge-e, judge-f, ...] ── linked to Round 7
|
||
|
|
│
|
||
|
|
├── Submission Windows (multi-round):
|
||
|
|
│ ├── Window 1: "Round 1 Docs" ── requirements: [Exec Summary, Business Plan]
|
||
|
|
│ └── Window 2: "Round 2 Docs" ── requirements: [Updated Plan, Video Pitch]
|
||
|
|
│
|
||
|
|
└── Special Awards (standalone):
|
||
|
|
├── "Innovation Award" ── mode: STAY_IN_MAIN, juryGroup: jury-2-award
|
||
|
|
└── "Impact Award" ── mode: SEPARATE_POOL, juryGroup: dedicated-jury
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Key Decisions
|
||
|
|
|
||
|
|
### 1. Eliminate the Track Layer
|
||
|
|
|
||
|
|
**Decision:** Remove the `Track` model entirely. The main competition is a linear sequence of Rounds. Special awards become standalone entities.
|
||
|
|
|
||
|
|
**Rationale:** The MOPC competition has one main flow (Intake -> Filtering -> Jury 1 -> Submission 2 -> Jury 2 -> Mentoring -> Finals -> Confirmation). The `Track` concept (MAIN/AWARD/SHOWCASE with RoutingMode and DecisionMode) was designed for branching flows that don't exist in this competition. Awards don't need their own track — they're parallel evaluation/voting processes that reference the same projects.
|
||
|
|
|
||
|
|
**Impact:**
|
||
|
|
- `Track` model deleted
|
||
|
|
- `TrackKind`, `RoutingMode` enums deleted
|
||
|
|
- `ProjectStageState.trackId` removed (becomes `ProjectRoundState` with just `projectId` + `roundId`)
|
||
|
|
- Award tracks replaced with enhanced `SpecialAward` model
|
||
|
|
- ~200 lines of Track CRUD code eliminated
|
||
|
|
|
||
|
|
### 2. Rename Pipeline -> Competition, Stage -> Round
|
||
|
|
|
||
|
|
**Decision:** Use domain-specific names that map to the competition vocabulary.
|
||
|
|
|
||
|
|
**Rationale:** Admins think in terms of "Competition 2026" and "Round 3: Jury 1 Evaluation", not "Pipeline" and "Stage". The rename costs nothing but improves comprehension.
|
||
|
|
|
||
|
|
### 3. Expand RoundType Enum
|
||
|
|
|
||
|
|
**Decision:** Add SUBMISSION, MENTORING, and CONFIRMATION to the existing types.
|
||
|
|
|
||
|
|
**Current:** `INTAKE | FILTER | EVALUATION | SELECTION | LIVE_FINAL | RESULTS`
|
||
|
|
|
||
|
|
**New:** `INTAKE | FILTERING | EVALUATION | SUBMISSION | MENTORING | LIVE_FINAL | CONFIRMATION`
|
||
|
|
|
||
|
|
**Changes:**
|
||
|
|
- `FILTER` -> `FILTERING` (clearer naming)
|
||
|
|
- `SELECTION` removed (merged into EVALUATION's advancement config)
|
||
|
|
- `RESULTS` removed (results are a view, not a round — handled by the CONFIRMATION round output)
|
||
|
|
- `SUBMISSION` added (new doc requirements for advancing teams)
|
||
|
|
- `MENTORING` added (mentor-team workspace activation)
|
||
|
|
- `CONFIRMATION` added (multi-party winner agreement)
|
||
|
|
|
||
|
|
### 4. Explicit JuryGroup Model
|
||
|
|
|
||
|
|
**Decision:** Juries are first-class entities with names, members, and per-juror configuration.
|
||
|
|
|
||
|
|
**Before:** Assignments were per-stage with no grouping concept. "Jury 1" only existed in the admin's head.
|
||
|
|
|
||
|
|
**After:** `JuryGroup` model with members, linked to specific evaluation/live-final rounds. A juror can belong to multiple groups.
|
||
|
|
|
||
|
|
### 5. Multi-Round Submissions via SubmissionWindow
|
||
|
|
|
||
|
|
**Decision:** A new `SubmissionWindow` model handles document requirements per round, with automatic locking of previous windows.
|
||
|
|
|
||
|
|
**Before:** One INTAKE stage with one set of `FileRequirement` records.
|
||
|
|
|
||
|
|
**After:** Each submission window has its own requirements. When a new window opens, previous ones lock for applicants. Jury rounds can see docs from specific windows.
|
||
|
|
|
||
|
|
### 6. Typed Configs Replace JSON Blobs
|
||
|
|
|
||
|
|
**Decision:** Replace generic `configJson: Json?` with round-type-specific config models or strongly-typed JSON with Zod validation.
|
||
|
|
|
||
|
|
**Before:** `Stage.configJson` could be anything — you'd have to read the code to know what fields exist for each StageType.
|
||
|
|
|
||
|
|
**After:** Each round type has a documented, validated config shape. The wizard presents only the fields relevant to each type.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Scope Summary
|
||
|
|
|
||
|
|
| Area | Action | Complexity |
|
||
|
|
|------|--------|------------|
|
||
|
|
| **Schema** | Major changes (new models, renamed models, deleted Track) | High |
|
||
|
|
| **Stage engine** | Rename to round engine, simplify (no Track references) | Medium |
|
||
|
|
| **Assignment service** | Enhance with jury groups, hard/soft caps, category ratios | Medium |
|
||
|
|
| **Filtering service** | Minimal changes (rename stageId -> roundId) | Low |
|
||
|
|
| **Live control** | Enhanced stage manager UI, same core logic | Medium |
|
||
|
|
| **Mentor system** | Major enhancement (workspace, files, comments, promotion) | High |
|
||
|
|
| **Winner confirmation** | New system (proposal, approvals, freezing) | High |
|
||
|
|
| **Special awards** | Enhanced (standalone, two modes, own jury groups) | Medium |
|
||
|
|
| **Notification system** | Enhanced (deadline countdowns, reminder triggers) | Medium |
|
||
|
|
| **Admin UI** | Full redesign (competition wizard, round management) | High |
|
||
|
|
| **Jury UI** | Enhanced (multi-jury dashboard, cross-round docs) | Medium |
|
||
|
|
| **Applicant UI** | Enhanced (multi-round submissions, mentoring workspace) | Medium |
|
||
|
|
| **Mentor UI** | New (dedicated mentor dashboard and workspace) | High |
|
||
|
|
| **API routers** | Major refactor (rename, new endpoints, removed endpoints) | High |
|
||
|
|
| **Migration** | Data migration from old schema to new | Medium |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Document Index
|
||
|
|
|
||
|
|
| # | Document | Purpose |
|
||
|
|
|---|----------|---------|
|
||
|
|
| 00 | This document | Executive summary and key decisions |
|
||
|
|
| 01 | Current System Audit | What exists today — models, services, routers, UI |
|
||
|
|
| 02 | Gap Analysis | Current vs required, feature-by-feature comparison |
|
||
|
|
| 03 | Data Model | Complete Prisma schema redesign with migration SQL |
|
||
|
|
| 04 | Round: Intake | Application window, forms, deadlines, drafts |
|
||
|
|
| 05 | Round: Filtering | AI screening, eligibility, admin overrides |
|
||
|
|
| 06 | Round: Evaluation | Multi-jury, caps, ratios, scoring, advancement |
|
||
|
|
| 07 | Round: Submission | Multi-round docs, locking, jury visibility |
|
||
|
|
| 08 | Round: Mentoring | Private workspace, file comments, promotion |
|
||
|
|
| 09 | Round: Live Finals | Stage manager, live voting, deliberation |
|
||
|
|
| 10 | Round: Confirmation | Jury signatures, admin override, result freezing |
|
||
|
|
| 11 | Special Awards | Two modes, award juries, integration |
|
||
|
|
| 12 | Jury Groups | Multi-jury architecture, members, overrides |
|
||
|
|
| 13 | Notifications & Deadlines | Countdowns, reminders, window management |
|
||
|
|
| 14 | AI Services | Filtering, assignment, summaries, eligibility |
|
||
|
|
| 15 | Admin UI Redesign | Dashboard, wizard, round management |
|
||
|
|
| 16 | Jury UI Redesign | Dashboard, evaluation, live voting |
|
||
|
|
| 17 | Applicant UI Redesign | Dashboard, multi-round uploads, mentoring |
|
||
|
|
| 18 | Mentor UI Redesign | Dashboard, workspace, file review |
|
||
|
|
| 19 | API Router Reference | tRPC changes — new, modified, removed |
|
||
|
|
| 20 | Service Layer Changes | Engine, assignment, new services |
|
||
|
|
| 21 | Migration Strategy | Schema migration, data migration, rollback |
|
||
|
|
| 22 | Integration Map | Cross-reference of all feature connections |
|
||
|
|
| 23 | Implementation Sequence | Phased order with dependencies |
|