14 KiB
14 KiB
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
- Identity and invitation/onboarding
- Pipeline/stage orchestration
- Assignment/evaluation
- Documents/submission bundles
- Awards and routing
- Mentoring collaboration
- Live finals and final confirmation
- 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:
- Directly governed by competition context
pipeline,stage,stageFiltering,stageAssignment,assignment,evaluation,decision,live,liveVoting,cohort,award,specialAward,mentor,applicant,application,file,project,project-pool
- Indirectly context-dependent (must carry context metadata)
user,notification,message,dashboard,analytics,export,audit
- 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:
- It resolves effective competition context before executing business logic.
- It uses typed policy resolution (not ad hoc JSON key checks).
- It emits standardized audit/decision events.
- 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.