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:
201
docs/claude-architecture-redesign/00-executive-summary.md
Normal file
201
docs/claude-architecture-redesign/00-executive-summary.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user