MOPC-App/docs/codex-architecture-redesign-docs/03-gap-analysis-and-simplification-decisions.md

03. Gap Analysis And Simplification Decisions

1) Summary

The platform already supports most building blocks of your competition, but key Monaco requirements are either implicit, partially modeled, or dispersed across modules. This document converts those gaps into explicit redesign decisions.

2) Gap Matrix (Current vs Required vs Redesign)

Area	Current State	Monaco Requirement	Redesign Decision
Stage semantics	Generic StageType, behavior split between configJson and UI assumptions	Explicit flow steps (R1 intake, eligibility, Jury1, R2, Jury2, mentoring layer, Jury3 live, final confirmation)	Add stagePurposeKey (typed enum) and purpose-specific policy validation
Jury modeling	Jury mostly inferred from role + assignments	Explicit Jury 1/2/3 and award juries with overlap	Add first-class Jury and JuryMembership models; bind to stages
Assignment policy	Max/min load + overflow policy + some category quota support	Per-judge hard/soft cap + soft buffer + startup/concept ratio + manual fallback queue	Create typed AssignmentPolicy + JudgePolicyOverride; formal unassigned queue
Filtering outcomes	Deterministic + AI + manual queue present	Eligibility pass with admin override and reason trace	Keep existing model, add stricter outcome taxonomy and promotion gates
Submission rounds	Stage requirements exist; file logic partly stage-bound	Round bundles with lock/read-only and provenance	Introduce explicit SubmissionRound/DocumentBundle abstraction on top of stage
Mentoring workspace	Mentor assignment/messages/notes/milestones exist	Private files + threaded comments + promotion to official submission	Add mentor workspace files/comments and PromotionEvent typed audit
Special awards	Strong award model, routing present but mixed semantics	Mode A/B behavior per award with pull-out/dual participation	Add explicit awardParticipationMode + routing policy constraints
Live finals	Live cursor + voting session + audience support exists	Stage manager controls + Jury 3 notes + deliberation windows	Keep live primitives; add deliberation policy and jury3 context contracts
Final confirmation	Audit + decision logs exist	All jury agree + one admin approval + result lock	Add dedicated FinalConfirmation workflow and result freeze state
Invite/member flows	Admin/member/team invites implemented; pre-assignment exists	Must deeply reflect updated architecture and juries	Make invites jury-aware and stage-purpose aware; unify assignment intents

3) High-Impact Ambiguity Sources To Eliminate

3.1 configJson As Primary Runtime Logic

Current problem:

• Critical behavior lives in open-ended JSON keys with inconsistent naming and weak compile-time guarantees.

Decision:

• Keep configJson for non-critical UI metadata.
• Move flow-critical behavior into typed policy tables and strict schemas.

3.2 Generic Stage Types Without Purpose Contract

Current problem:

• Two stages can both be EVALUATION, but system behavior may need to differ radically (Jury1 vs Jury2 vs award).

Decision:

• Add immutable stagePurposeKey and purpose-aware policy validator.

3.3 Dispersed Assignment Constraints

Current problem:

• Multiple assignment pathways (stageAssignment router/service, assignment router, AI suggestions) can diverge in rules.

Decision:

• Centralize assignment rule evaluation into one policy engine used by all assignment entry points.

3.4 Invite And Onboarding Disconnected From Jury Context

Current problem:

• /admin/members/invite pre-assigns projects directly, but not explicitly tied to jury entities and policy contracts.

Decision:

• Introduce AssignmentIntent attached to JuryMembership/stage context during invite flow; materialize assignments when stage/policy permits.

4) Simplification Decisions (Non-Negotiable)

1. One source of truth for stage behavior: stagePurposeKey + policy models
2. One source of truth for assignment constraints: centralized assignment policy engine
3. One source of truth for winner lock: explicit final confirmation workflow
4. One source of truth for document status: round bundle + requirement slot state
5. One source of truth for role access: policy-based access resolver by context

5) Compatibility Strategy

5.1 Keep Existing Backbone

No full rewrite:

• Preserve Pipeline, Track, Stage, ProjectStageState, Assignment, Evaluation, SpecialAward, LiveVotingSession

5.2 Additive Evolution

Add new typed entities and read/write adapters:

• old endpoints keep working in compatibility mode during migration
• new flows use purpose/policy-aware endpoints

5.3 Controlled De-ambiguation

• Introduce strict validation for future pipeline configs
• Provide migration scripts for legacy configJson keys
• fail-fast for unsupported combinations

6) Design Tradeoffs

6.1 Why Not Fully Dynamic “No Skeleton” Flow?

• You requested clarity and reduced vagueness.
• Purely dynamic flow increases flexibility but harms predictability, QA surface, and operator confidence.

Chosen approach:

• fixed Monaco skeleton + configurable policies and optional modules.

6.2 Why Typed Tables Instead Of More JSON?

• Critical competition logic requires integrity constraints, easier querying, and deterministic behavior.
• Typed models improve auditability and testability.

6.3 Why Add Jury As Explicit Entity?

• Your flow explicitly names Jury 1/2/3 and overlapping award juries.
• This cannot remain a UI convention without creating operational drift.

7) Required Outcome Of Simplification

By end of redesign:

• Admins can configure Monaco flow without hidden dependencies.
• Assignment limits are deterministic, while startup/concept ratio remains a transparent soft-bias recommendation.
• Invite/member pages support policy-compliant jury memberships plus both pre-assignment modes (intent-first and direct assignment where explicitly enabled).
• Documents, mentoring, awards, finals, and confirmation all speak the same domain language.