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.