letsbe
/
MOPC-App
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
MOPC-App/docs/codex-architecture-redesign.../01-current-platform-archite...

7.7 KiB
Raw Blame History

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