MOPC-App/docs/codex-architecture-redesign-docs/01-current-platform-architecture-audit.md

# 01. Current Platform Architecture Audit

## 1) Technology Baseline
- Frontend: Next.js App Router, role-based route groups
- API: tRPC router composition (`src/server/routers/_app.ts`)
- ORM/DB: Prisma + PostgreSQL (`prisma/schema.prisma`)
- Auth: NextAuth + invitation token + onboarding + password setup flows
- Storage: MinIO/S3-like presigned URLs for project files
- Notifications: email + in-app notifications + reminder logs
- AI: OpenAI-backed assignment/filtering/award eligibility/summary/mentor matching with fallback logic

## 2) Core Current Domain Model (As Implemented)

### 2.1 Stage Engine Backbone
Current schema already includes the core stage engine building blocks:
- `Pipeline` (program-level orchestration container)
- `Track` (main/award/showcase branches)
- `Stage` (typed lifecycle node)
- `StageTransition` (graph edges with optional guards)
- `ProjectStageState` (project position/state inside stage)
- `Cohort` + `CohortProject` (grouping for live/selection windows)
- `LiveProgressCursor` (live presentation pointer)
- `OverrideAction` + `DecisionAuditLog` (decision/override evidence)

### 2.2 Evaluation / Assignment / Filtering / Awards / Mentorship
The platform also has substantial supporting models:
- Assignment & judging: `Assignment`, `Evaluation`, `EvaluationForm`, `ConflictOfInterest`, `GracePeriod`
- Filtering: `FilteringRule`, `FilteringResult`, `FilteringJob`
- Awards: `SpecialAward`, `AwardEligibility`, `AwardJuror`, `AwardVote`
- Mentorship: `MentorAssignment`, `MentorMessage`, `MentorNote`, `MentorMilestone`, `MentorMilestoneCompletion`
- Documents: `FileRequirement`, `ProjectFile`
- Live voting: `LiveVotingSession`, `LiveVote`, `AudienceVoter`

### 2.3 User/Invite/Team Model
- Users: `User` with roles, invite token, onboarding state, workload fields
- Team: `TeamMember` links project/user and role (`LEAD`, `MEMBER`, `ADVISOR`)
- Invitation tokens are user-level (`inviteToken`, `inviteTokenExpiresAt`), reused across admin and team invite flows

## 3) Current Services (Behavior Layer)

### 3.1 Stage Lifecycle Services
- `stage-engine.ts`: transition validation + execution + guard evaluation
- `stage-filtering.ts`: stage-scoped deterministic + AI banding filtering with manual queue concept
- `stage-assignment.ts`: stage-scoped assignment preview/rebalance/coverage, workload/tag balancing
- `live-control.ts`: live session control (cursor, queue reorder, pause/resume, cohort windows)
- `stage-notifications.ts`: event emission + notification policy checks

### 3.2 AI and Automation Services
- `ai-assignment.ts`, `smart-assignment.ts`
- `ai-filtering.ts`
- `award-eligibility-job.ts`, `ai-award-eligibility.ts`
- `mentor-matching.ts`
- `ai-evaluation-summary.ts`

### 3.3 Deadline/Reminder Services
- `evaluation-reminders.ts` for stage deadline reminder windows and deduplicated reminder logs

## 4) Current API Surface (tRPC Router Map)
Major routers currently include:

- Competition architecture: `pipeline`, `stage`, `stageFiltering`, `stageAssignment`, `cohort`, `live`, `decision`, `award`, `specialAward`
- Judging ops: `assignment`, `evaluation`, `gracePeriod`, `filtering`
- Project/applicant/docs: `project`, `application`, `applicant`, `file`, `project-pool`
- Mentorship: `mentor`
- Identity/admin ops: `user`, `program`, `settings`, `notification`, `audit`, `dashboard`
- Platform modules: `message`, `webhook`, `learningResource`, `partner`, `tag`, imports, analytics, export

## 5) Current UI Surface (By Role)

### 5.1 Admin Surface
- Program settings, apply settings, pipeline wizard/advanced editors
- Project pool and project management
- Members + invitation workflow (`/admin/members/invite`)
- Mentors and mentorship settings
- Awards and live/reporting pages

### 5.2 Applicant Surface
- Applicant dashboard, pipeline status, stage documents, team management, mentoring page
- Team invite/remove functionality in applicant team pages

### 5.3 Jury Surface
- Stage lists, assignment lists, project review/evaluation pages, comparison, live stage pages, awards

### 5.4 Mentor Surface
- Mentor dashboard, project workspaces, notes, milestones, messaging

### 5.5 Public/Auth Surface
- Public application pages
- Accept invite page, onboarding page, set password flow
- Public live score and audience vote pages

## 6) Current Strengths
1. Strong foundational stage/pipeline schema already exists.
2. Manual override and audit models already present.
3. AI-assisted modules are implemented with fallback paths.
4. Live voting/session primitives already exist.
5. File requirements + per-stage file visibility logic already exist.
6. Team invitation and onboarding flows are functioning and integrated with email + status.

## 7) Current Mismatch Areas Against Monaco Flow

### 7.1 Stage Purpose Ambiguity
- `StageType` is generic (`INTAKE/FILTER/EVALUATION/...`) but does not encode explicit Monaco semantics (Jury 1 vs Jury 2 vs Jury 3, Submission Round 1 vs Round 2, Final Confirmation).
- Behavior depends heavily on `configJson` conventions and page-level interpretation.

### 7.2 Jury Entity Is Implicit, Not First-Class
- Jury membership is mostly inferred from `User.role` + stage assignments.
- The Monaco requirement for explicit overlapping juries (`Jury 1/2/3`, award juries) is not modeled as first-class reusable entities.

### 7.3 Assignment Policy Is Incomplete For Required Cap Semantics
- Current assignment supports limits and balancing, but lacks formal per-judge hard/soft cap contracts with explicit buffer and exhaustion handling.
- Category mix logic exists but not in the exact required startup/concept ratio semantics per judge + override flow.

### 7.4 Document Lifecycle Is Partially Structured
- Stage-level requirements are present; previous-stage visibility exists.
- But “submission bundles per round” and official round-level locking semantics are not consistently first-class.

### 7.5 Mentoring Collaboration Layer Is Not Complete
- Messaging/notes/milestones exist.
- Missing required private mentor-team file workspace with threaded comments + official submission promotion provenance.

### 7.6 Finals Confirmation Workflow Not Fully Typed
- Live voting and cursor controls exist.
- No dedicated final confirmation entity enforcing “all jury agree + one admin approval + result freeze lock”.

### 7.7 Award Mode Semantics Need Hardening
- Awards are powerful but routing mode behavior (`pull-out` vs `dual participation`) is not represented as explicit governance policy with strict validation.

### 7.8 Cross-Platform Consistency Gaps
- Critical workflows (member invite, team invite, onboarding, pre-assignment, stage visibility) are implemented across multiple modules with some duplicated logic and role assumptions.
- This increases drift risk when competition architecture changes.

## 8) Complexity/Vagueness Sources
1. Over-reliance on freeform `configJson` for core behavior.
2. Multiple overlapping assignment/filtering router/service pathways.
3. Legacy “round” nomenclature still appears in fields and comments while pipeline model is active.
4. Invite/onboarding/team and assignment logic are integrated but not governed by a single “competition operating model” contract.
5. Some stage-specific behavior depends on UI assumptions rather than centralized policy evaluation.

## 9) Conclusion (Current-State Summary)
The platform is not a blank slate. It is a capable stage-engine system with substantial functionality already built. The redesign should be an **evolutionary hardening and simplification** effort:

- Keep what is structurally strong (pipeline/stage backbone, audit, live primitives)
- Introduce explicit entities/policies where Monaco flow requires precision
- Reduce ambiguity by making flow-critical contracts typed and validated
- Unify all user-facing functions under the same stage/jury/document/decision model