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,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.
|
||||
Reference in New Issue
Block a user