MOPC-App/docs/codex-architecture-redesign-docs/04-unified-domain-model-and-config-contracts.md

04. Unified Domain Model And Config Contracts

1) Objectives

This target model turns the Monaco flow into strict, reusable contracts while preserving the current pipeline infrastructure.

Goals:

1. Minimize schema churn where current models are already correct.
2. Remove ambiguity for jury identity, assignment policy, round bundles, mentoring promotion, and final lock.
3. Keep customization through explicit policy layers, not ad hoc conditionals.

2) Proposed Domain Additions

2.1 Stage Purpose Contract

Add To Stage

• purposeKey (enum/string, required after migration)

Proposed purpose enum values:

• submission_r1_intake
• eligibility_filter
• jury1_evaluation
• submission_r2_intake
• jury2_evaluation
• jury3_live_finals
• final_confirmation
• results_publication
• award_evaluation
• award_results

Rule:

• StageType remains coarse technical type.
• purposeKey controls business behavior and policy validation.

2.2 Jury As First-Class Entity

New Jury

Fields:

• id, programId, purposeKey, code, displayLabel, kind (MAIN, AWARD), isActive

Examples:

• code=main-semifinal, displayLabel=Technical Semi-Final Jury
• code=main-finalist, displayLabel=Grand Jury
• code=award-blue-innovation, displayLabel=Blue Innovation Prize Jury

New JuryMembership

Fields:

• juryId, userId, roleInJury (CHAIR, MEMBER), activeFrom, activeTo, status

New JuryStageBinding

Fields:

• juryId, stageId, isPrimary, permissionsJson

Use:

• controls which juries are allowed to evaluate/vote in each stage
• allows overlap across juries and awards

2.3 Assignment Policy Contract

New AssignmentPolicy (stage + jury scoped)

Fields:

• stageId
• juryId
• requiredReviews
• defaultCap
• defaultCapMode (HARD, SOFT)
• softBuffer (default 10, configurable)
• categoryBiasPolicyJson (startup/concept mix preference weights; non-deterministic)
• overflowPolicy (manual_queue, expand_pool, reduce_reviews)
• isActive

New JudgePolicyOverride

Fields:

• assignmentPolicyId
• userId
• cap, capMode, softBuffer
• startupBiasWeight, conceptBiasWeight
• biasDisclosureAcceptedAt (onboarding acknowledgement that bias is suggestive only)
• source (ADMIN_SET, JUDGE_ONBOARDING)

New AssignmentIntent

Purpose:

• records desired assignments created before assignment materialization (e.g., from member invite page)

Fields:

• stageId, juryId, userId, projectId, intentSource, status

New AssignmentException

Purpose:

• explicit record for manual over-cap assignments

Fields:

• assignmentId, policyId, exceptionType, reasonCode, reasonText, approvedBy

2.4 Submission Round Bundle Contract

New SubmissionRound

Fields:

• id, stageId, roundKey, name, openAt, closeAt, latePolicy, lateGraceHours, editabilityPolicy

Evolve FileRequirement

Add:

• submissionRoundId (nullable transitional, required after migration)
• slotKey (stable requirement slot identifier)

Evolve ProjectFile

Add:

• submissionRoundId
• submissionSlotKey
• sourceType (DIRECT_UPLOAD, MENTOR_PROMOTION, ADMIN_REPLACEMENT)
• sourceReferenceId (e.g., mentor file id)
• isOfficial

New SubmissionBundleState

Fields:

• projectId, submissionRoundId, status (DRAFT, SUBMITTED, LOCKED), lockedAt, lockedBy

2.5 Mentoring Collaboration + Promotion

New MentorWorkspaceFile

Fields:

• projectId, mentorId (nullable for team upload), file storage metadata, visibility, status

New MentorWorkspaceComment

Fields:

• workspaceFileId, authorId, threadKey, content, timestamps

New SubmissionPromotionEvent

Fields:

• projectId, workspaceFileId, targetSubmissionRoundId, targetSlotKey
• promotedById, promotedAt
• resultProjectFileId
• approvalState (if mentor/admin approvals required)

Invariant:

• promotion always creates immutable provenance link from mentoring artifact to official submission slot.
• promotion authority is limited to team lead and admin.

2.6 Special Award Governance Contract

Extend SpecialAward

Add:

• participationMode (SEPARATE_POOL, DUAL_TRACK)
• routingBehavior (PULL_FROM_MAIN, KEEP_IN_MAIN)
• routingConfirmationMode (AUTO, ADMIN_CONFIRMED) // Monaco default: ADMIN_CONFIRMED for pull-out
• requiresDedicatedJury (bool)
• winnerDecisionMode (JURY_CONFIRMATION, SINGLE_JUDGE_DECIDES)
• singleJudgeUserId (nullable, required when winnerDecisionMode=SINGLE_JUDGE_DECIDES)
• winnerCandidateSource (ELIGIBILITY_REMAINING_POOL, CUSTOM_SHORTLIST) // Monaco single-judge awards use eligibility remaining pool
• submissionRequirementMode (REUSE_MAIN, CUSTOM)

New AwardStageBinding

Fields:

• awardId, filterStageId, evaluationStageId, resultStageId

2.7 Final Confirmation Contract

New FinalConfirmationSession

Fields:

• stageId (final confirmation stage)
• status (OPEN, PENDING_ADMIN_APPROVAL, FINALIZED, CANCELLED)
• decisionRule (UNANIMOUS, SUPERMAJORITY, SIMPLE_MAJORITY, SINGLE_JUDGE_DECIDES)
• quorumPolicy (ACTIVE_MEMBERS_ONLY, ALLOW_REPLACEMENT)
• requiredApprovalsCount (resolved from active quorum after absence/replacement decisions)
• scope (CATEGORY, AWARD)
• isAdminOverridden (bool)
• overrideReasonCode, overrideReasonText, overriddenByAdminId, overriddenAt
• finalizedByAdminId, finalizedAt

New FinalConfirmationParticipant

Fields:

• sessionId, juryMemberId
• status (REQUIRED, ABSENT_EXCUSED, REPLACED, REPLACEMENT_ACTIVE)
• replacedByJuryMemberId (nullable)
• absenceReasonCode, absenceReasonText
• updatedByAdminId, updatedAt

New FinalConfirmationVote

Fields:

• sessionId, juryMemberId, projectId/category/awardScope, decision, comment

New ResultLock

Fields:

• sessionId, programId, lockVersion, lockedAt, lockedBy, snapshotJson

New ResultUnlockEvent

Fields:

• resultLockId, programId
• unlockedBySuperAdminId, unlockedAt
• reasonCode, reasonText
• relockVersion (nullable until relock)

Invariant:

• once ResultLock is created, winner outputs are immutable except via explicit super-admin unlock workflow with mandatory audit reason.

3) Policy Precedence Model

Order of precedence (highest to lowest):

1. Explicit admin override action (with reason)
2. Per-user override policy (e.g., judge cap override)
3. Stage+jury policy
4. Program-level default policy
5. System default

All runtime evaluators must return:

• resolved value
• source layer
• explanation payload for audit/debug UI

4) Access Contract (Role + Context)

Replace scattered checks with resolveAccess(user, context) where context includes:

• programId
• trackId
• stageId
• stagePurposeKey
• juryId (if applicable)
• projectId (if applicable)
• submissionRoundId (if applicable)

Returns typed permissions:

• canViewProject
• canUploadSubmissionSlot
• canViewPreviousRoundDocs
• canAssignProjects
• canVoteLive
• canConfirmFinalWinners
• etc.

5) Assignment Engine Contract

Input:

• projects eligible in stage
• jury members bound to stage
• resolved per-judge policy (cap mode, cap, buffer, category-bias preference)
• required reviews
• COI and availability constraints

Required behavior:

1. satisfy hard-cap constraints strictly
2. satisfy soft-cap targets before using buffer
3. apply startup/concept distribution as a soft scoring bias (never a strict blocker)
4. when all soft-cap members hit cap+buffer, place remainder in manual queue
5. never silently drop unassigned projects

Output:

• assignment set
• unassigned queue with explicit reasons
• policy-compliance summary

6) Document Contract

For every stage with submission behavior:

• active SubmissionRound must exist
• all required slots represented by FileRequirement.slotKey
• applicant write rights only for active round if open
• previous round slots read-only in applicant scope
• judges see current + previous according to stage policy
• admins full mutate rights with replacement provenance

7) Invite + Onboarding Contract

7.1 Admin Member Invite

• Invitations create User + optional JuryMembership.
• Jury selection uses program-defined custom jury labels, while binding to explicit stage-purpose contracts.
• Pre-assignment supports both modes:
  • intent-first mode via AssignmentIntent (default recommended)
  • direct assignment mode via Assignment (explicitly enabled and policy-validated)

7.2 Team Invite

• Team lead invites create/attach TeamMember
• invite token acceptance path remains, but post-accept routing resolves to proper applicant/team context

7.3 Accept Invite Routing

After acceptance:

• if user has jury memberships pending onboarding -> jury onboarding journey
• if mentor -> mentor onboarding
• if applicant team member only -> applicant team dashboard

8) Event/Audit Contract

Every significant workflow event emits:

• business event type (assignment.generated, final_confirmation.finalized, etc.)
• actor
• entity scope
• policy snapshot
• before/after state where relevant

Override events must include:

• reason code
• reason text
• impacted policy key
• reviewer chain (if applicable)

9) API Contract Evolution (Router-Level)

9.1 Keep and Evolve

• Keep existing routers (pipeline, stage, assignment, evaluation, file, mentor, live-voting, decision, user, etc.)
• Add new endpoints for purpose/policy/jury/final confirmation and deprecate ambiguous patterns progressively

9.2 New Endpoint Families

• jury.*: CRUD memberships/bindings
• assignmentPolicy.*: configure and inspect effective policy
• submissionRound.*: lifecycle and bundle state
• mentorWorkspace.*: files/comments/promotion
• finalConfirmation.*: create/collect/finalize lock, handle quorum fallback, and manage juror replacement/absence
• resultUnlock.*: super-admin unlock/relock workflow with audit capture
• access.*: debug effective permissions (admin-only)

10) Migration Safety Rules

1. Additive migrations first.
2. Backfill purposeKey and policy references from existing configs.
3. Dual-read / single-write transition windows where needed.
4. Feature flags for critical runtime path switches.
5. No silent behavior changes in production without compatibility mode.

11) End State

A coherent operating model where all functions, pages, and APIs are consistent with Monaco flow and each key behavior is explainable, testable, and auditable.