MOPC-App/docs/codex-architecture-redesign-docs/02-monaco-flow-target-architecture.md

# 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.