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.