MOPC-App/docs/codex-architecture-redesign-docs/05-platform-wide-integration-matrix.md

# 05. Platform-Wide Integration Matrix

## 1) Integration Rule
Every function must consume the same competition context contract:
- program
- pipeline/track
- stage + `purposeKey`
- jury context (when relevant)
- submission round context (when relevant)
- resolved policy set

No page/router may hardcode Monaco behavior without passing through this context resolver.

## 2) Critical Integration Domains

1. Identity and invitation/onboarding
2. Pipeline/stage orchestration
3. Assignment/evaluation
4. Documents/submission bundles
5. Awards and routing
6. Mentoring collaboration
7. Live finals and final confirmation
8. Notifications, timeline, reporting, exports

## 3) Admin UX Integration Matrix

| Surface | Current Behavior | Required Integration To Redesigned Architecture |
|---|---|---|
| `src/app/(admin)/admin/rounds/pipeline/[id]/wizard/page.tsx` | Generic stage setup | Must require `purposeKey` assignment and validate Monaco skeleton completeness |
| `src/app/(admin)/admin/rounds/pipeline/[id]/advanced/page.tsx` | Advanced free-form editing | Add policy editors for jury binding, assignment policies, submission rounds, final confirmation |
| `src/app/(admin)/admin/rounds/pipeline/[id]/edit/page.tsx` | Pipeline editing | Prevent invalid stage-purpose combinations; show dependency impacts |
| `src/components/admin/pipeline/sections/assignment-section.tsx` | min/max load + overflow | Replace with explicit hard/soft cap + buffer + startup/concept bias controls (clearly labeled suggestive, not deterministic) |
| `src/components/admin/pipeline/sections/filtering-section.tsx` | rules + AI criteria | Bind to `eligibility_filter` purpose and standardized outcomes |
| `src/components/admin/pipeline/sections/awards-section.tsx` | award routing/scoring basic | Add participation mode (`separate_pool`/`dual_track`) and pull-out behavior |
| `src/components/admin/pipeline/sections/live-finals-section.tsx` | live/audience settings | Add Jury 3 deliberation window and final confirmation linkage |
| `src/components/admin/pipeline/stage-config-editor.tsx` | generic config rendering | render purpose-aware controls only; remove ambiguous keys |
| `src/app/(admin)/admin/projects/page.tsx` | project list by filters | Add stage-purpose-aware views and round bundle health columns |
| `src/app/(admin)/admin/projects/pool/page.tsx` | project pool ops | Use assignment intent/manual queue with reason tracking |
| `src/app/(admin)/admin/reports/stages/page.tsx` | stage reporting | Include compliance metrics (cap violations, override counts, unassigned backlog) |

## 4) Invite / Member / Onboarding Integration Matrix (High Priority)

### 4.1 Admin Member Invite (Explicit Requirement)

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(admin)/admin/members/invite/page.tsx` | invites users; optional pre-assign project-to-user by stage | Must bind invite flow to explicit `JuryMembership`. UI must support both pre-assignment modes: `AssignmentIntent` mode and policy-validated direct assignment mode. Admin chooses custom-labeled jury (main or award), stage scope, and mode. |
| `src/server/routers/user.ts` `bulkCreate` | creates users and may directly create assignments | Support dual behavior: create `AssignmentIntent` and/or direct policy-validated assignments based on request mode. Track chosen mode, source, and policy decision in audit details. |
| `src/server/routers/user.ts` `sendInvitation`/`bulkSendInvitations` | token invitation | Include context metadata (jury memberships, pending assignment intents, onboarding path) in invitation payload/logs. |

### 4.2 Team Invite / Project Team Management

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(applicant)/applicant/team/page.tsx` | team lead invites/removes members | Keep flow, but gate permissions via context resolver and ensure invite acceptance routes into project-team scope correctly. |
| `src/app/(public)/my-submission/[id]/team/page.tsx` | mirrored team flow | Must consume same backend contract as applicant team page; no divergent logic. |
| `src/server/routers/applicant.ts` `inviteTeamMember` | creates/updates user + team member + email | Add membership lifecycle states and provenance events; ensure no conflict with jury/mentor invitation states. |

### 4.3 Invite Acceptance + Onboarding

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(auth)/accept-invite/page.tsx` | validates token and signs in | After acceptance, route based on membership context (jury, mentor, team, admin) and pending obligations (onboarding, password, jury onboarding choices). |
| `src/app/(auth)/onboarding/page.tsx` | role-aware onboarding | Must collect jury cap/bias preferences (if enabled) for judges, clearly disclose that startup/concept bias is suggestive (not a rule), and tie to `JudgePolicyOverride` records. |
| `src/server/routers/user.ts` `validateInviteToken` | token validation only | include contextual invitation metadata for accurate UX preview. |
| `src/server/routers/user.ts` `needsOnboarding` | role-based onboarding check | extend to membership-aware onboarding requirements per jury/stage. |

## 5) Applicant + Submission Integration Matrix

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(public)/apply/[slug]/page.tsx` | stage/public form | enforce submission round contract (`SubmissionRound`, slots, late policy) |
| `src/app/(public)/apply/edition/[programSlug]/page.tsx` | edition mode intake | must map to `submission_r1_intake` purpose policies if Monaco profile active |
| `src/app/(applicant)/applicant/pipeline/page.tsx` | pipeline visibility | show purpose-based journey (R1, eligibility, Jury1 result, R2, etc.) |
| `src/app/(applicant)/applicant/pipeline/[stageId]/documents/page.tsx` | stage docs | enforce round-bundle write/read states by stage purpose |
| `src/app/(applicant)/applicant/documents/page.tsx` | docs view | show bundle timeline and official slot status per round |
| `src/server/routers/application.ts` | public submission & draft | create `SubmissionBundleState` and normalize category key mapping |
| `src/server/routers/applicant.ts` `getUploadUrl/saveFileMetadata/deleteFile` | upload + save + delete | enforce slot state, round lock, promotion provenance, late behavior policy |
| `src/server/routers/file.ts` | file access and grouped views | use submission round + stage purpose aware visibility consistently across roles |

## 6) Jury Integration Matrix

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(jury)/jury/stages/page.tsx` | shows active stages | show only stages bound to juries user belongs to |
| `src/app/(jury)/jury/stages/[stageId]/assignments/page.tsx` | assignment list | render cap status, ratio status, deadline countdown, completion obligations |
| `src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/page.tsx` | project details | purpose-aware document separation (Round 1 vs Round 2) |
| `src/app/(jury)/jury/stages/[stageId]/projects/[projectId]/evaluate/page.tsx` | evaluation form | enforce stage/jury policy and graceful lock behavior |
| `src/app/(jury)/jury/stages/[stageId]/live/page.tsx` | live finals interaction | require Jury 3 membership and live session permissions |
| `src/server/routers/assignment.ts` | assignment CRUD/suggestions/jobs | centralize policy engine usage for all assignment paths |
| `src/server/routers/evaluation.ts` | evaluation lifecycle | incorporate jury binding checks and final confirmation contribution rights |
| `src/server/services/stage-assignment.ts` | stage assignment preview/run | implement hard/soft cap+buffer with category bias as weighted guidance (not deterministic rule) |
| `src/server/services/smart-assignment.ts` | scoring logic | treat startup/concept preference as transparent scoring bias, not strict quota blocking |

## 7) Awards Integration Matrix

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(admin)/admin/awards/*` | award management | expose mode A/B semantics, admin-confirmed pull-out flow, and single-judge decision mode where configured |
| `src/app/(jury)/jury/awards/*` | jury award voting | bind to award jury memberships/stage windows and suppress jury voting for single-judge awards |
| `src/server/routers/award.ts` | award track governance | add strict validation for participation mode, stage bindings, admin-confirmed pull-out, and single-judge configuration |
| `src/server/routers/specialAward.ts` | eligibility + jurors + votes | include standardized filter->review->selection pipeline and override chain |
| `src/server/services/award-eligibility-job.ts` | background eligibility | persist decision reasoning under unified audit event taxonomy |

## 8) Mentor Integration Matrix

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(mentor)/mentor/projects/[id]/page.tsx` | mentor project detail | include private workspace files + threaded comments; promotion actions only where allowed by team-lead/admin authority |
| `src/app/(applicant)/applicant/mentor/page.tsx` | applicant mentor interaction | show promotion candidate files and official slot mapping |
| `src/server/routers/mentor.ts` | assignment/message/notes/milestones | add workspace file/comment/promotion endpoints and enforce team-lead/admin-only promotion permissions |
| `src/server/services/mentor-matching.ts` | AI matching | gate matching by finalist + mentorship request + stage policy |

## 9) Live Finals + Confirmation Integration Matrix

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/app/(admin)/admin/reports/stages/page.tsx` + live admin pages | live status/reporting | show stage manager controls + deliberation timer + confirmation readiness |
| `src/app/(public)/vote/*` | audience voting pages | enforce category/session mode and anti-duplicate policy |
| `src/server/routers/live.ts` | live cursor controls | require `jury3_live_finals` purpose and stage manager authority |
| `src/server/routers/live-voting.ts` | voting session mgmt | tie session lifecycle to stage purpose + deliberation/final confirmation handoff |
| `src/server/routers/cohort.ts` | cohort windows | align with live/selection policies and category boundaries |
| `src/server/routers/decision.ts` | overrides/audit | extend to final confirmation decisions and result lock events |
| **new router family** `finalConfirmation.*` | none | create and govern unanimous-with-quorum-fallback confirmation for category+award scopes, single-judge award exceptions, juror replacement/absence controls, admin override paths, and final lock snapshot |
| **new router family** `resultUnlock.*` | none | super-admin-only unlock/relock workflow with mandatory reason/audit trail |

## 10) Notifications / Messaging / Reporting / Export Integration Matrix

| Surface | Current Behavior | Required Integration |
|---|---|---|
| `src/server/services/stage-notifications.ts` | event-based notifications | expand event taxonomy for jury membership, promotion, confirmation lock |
| `src/server/services/evaluation-reminders.ts` | stage deadline reminders | include jury-specific obligations and final confirmation reminders |
| `src/server/routers/message.ts` | messaging | ensure context tags reference stage/jury/project where applicable |
| `src/server/routers/export.ts` | report generation | include final lock version and policy-compliance evidence |
| `src/server/routers/audit.ts` | audit search | add filter facets for stage purpose, jury id, confirmation session |
| `src/server/routers/analytics.ts` | platform analytics | add Monaco flow KPIs (assignment saturation, override rate, policy compliance) |

## 11) Router Integration Checklist (All tRPC Domains)

Each router in `src/server/routers/_app.ts` must be classified into one of three buckets:

1. **Directly governed by competition context**
- `pipeline`, `stage`, `stageFiltering`, `stageAssignment`, `assignment`, `evaluation`, `decision`, `live`, `liveVoting`, `cohort`, `award`, `specialAward`, `mentor`, `applicant`, `application`, `file`, `project`, `project-pool`

2. **Indirectly context-dependent (must carry context metadata)**
- `user`, `notification`, `message`, `dashboard`, `analytics`, `export`, `audit`

3. **Context-independent utilities**
- `avatar`, `logo`, `tag`, imports, generic settings/webhooks

Requirement:
- Bucket 1 and 2 routers must accept/derive stage/jury context when touching competition entities.

## 12) Services Refactor Boundaries

| Service | Keep | Refactor Requirement |
|---|---|---|
| `stage-engine.ts` | yes | purpose-aware transition guards |
| `stage-filtering.ts` | yes | standardized eligibility outcomes + reason schema |
| `stage-assignment.ts` | yes | full hard/soft cap policy engine |
| `smart-assignment.ts` | partial | convert soft heuristics into policy-compliant scoring only |
| `live-control.ts` | yes | bind to Jury3 and confirmation handoff |
| `mentor-matching.ts` | yes | finalist-stage gating and workspace policy awareness |
| `evaluation-reminders.ts` | yes | purpose-aware reminder templates |

## 13) Integration Acceptance Criteria
A module is considered integrated only if:
1. It resolves effective competition context before executing business logic.
2. It uses typed policy resolution (not ad hoc JSON key checks).
3. It emits standardized audit/decision events.
4. It fails safely when required context/policy is missing.

## 14) Special Note: “All Functions Deeply Integrated”
Your requirement is satisfied only when invite/member/team/onboarding pages are not treated as peripheral admin UX, but as first-class entry points into the jury/stage/assignment model. This is explicitly mandatory in Phases 2 and 3 of the roadmap.