letsbe
/
MOPC-App
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
MOPC-App/docs/claude-architecture-redesign/13-notifications-deadlines.md

2899 lines
96 KiB
Markdown
Raw Blame History

# Notifications & Deadlines
## Overview
The Notifications & Deadlines system is a cross-cutting concern that supports every round type in the MOPC platform. It provides:
1. **Event-driven notifications** — In-app and email notifications triggered by pipeline events
2. **Deadline management** — Configurable deadline policies with grace periods
3. **Reminder scheduling** — Automated reminders at configurable intervals before deadlines
4. **Countdown timers** — Real-time visual countdowns for participants
5. **Admin controls** — Competition-wide and per-round notification configuration
6. **Multi-channel delivery** — Email, in-app, and future webhook integrations
This system ensures that all participants (jury, applicants, mentors, admins) are informed about critical events and approaching deadlines across all round types.
---
## Current System Analysis
### How Notifications Work Today
The current notification system (Phase 6 — Pipeline/Track/Stage architecture) has these components:
#### 1. Event-Driven Notifications (stage-notifications.ts)
**Core function:**
```typescript
export async function emitStageEvent(
eventType: string, // e.g., "stage.transitioned"
entityType: string, // e.g., "ProjectStageState"
entityId: string, // Entity ID
actorId: string, // User who triggered the event
details: StageEventDetails,
prisma: PrismaClient
): Promise<void>
```
**Process:**
1. Creates `DecisionAuditLog` entry (immutable event record)
2. Checks `NotificationPolicy` for the event type
3. Resolves recipients based on event type (admins, jury, etc.)
4. Creates `InAppNotification` records
5. Optionally sends emails via `sendStyledNotificationEmail()`
6. Never throws — all errors caught and logged
**Current event types:**
```typescript
const EVENT_TYPES = {
STAGE_TRANSITIONED: 'stage.transitioned',
FILTERING_COMPLETED: 'filtering.completed',
ASSIGNMENT_GENERATED: 'assignment.generated',
CURSOR_UPDATED: 'live.cursor_updated',
DECISION_OVERRIDDEN: 'decision.overridden',
}
```
**Notification flow:**
```
Pipeline Event
↓
stage-notifications.emitStageEvent()
↓
1. DecisionAuditLog.create()
2. NotificationPolicy.findUnique(eventType)
3. resolveRecipients() → [NotificationTarget[]]
4. InAppNotification.createMany()
5. sendStyledNotificationEmail() (if channel = EMAIL or BOTH)
```
#### 2. Deadline Reminders (evaluation-reminders.ts)
**Core function:**
```typescript
export async function processEvaluationReminders(
stageId?: string
): Promise<ReminderResult>
```
**Process:**
1. Finds active stages with `windowCloseAt` in the future
2. Calculates `msUntilDeadline` for each stage
3. Checks which reminder types apply (3_DAYS, 24H, 1H)
4. Finds jurors with incomplete assignments
5. Checks `ReminderLog` to avoid duplicates
6. Sends email via `sendStyledNotificationEmail()`
7. Creates `ReminderLog` entry
**Reminder thresholds:**
```typescript
const REMINDER_TYPES = [
{ type: '3_DAYS', thresholdMs: 3 * 24 * 60 * 60 * 1000 },
{ type: '24H', thresholdMs: 24 * 60 * 60 * 1000 },
{ type: '1H', thresholdMs: 60 * 60 * 1000 },
]
```
**Cron integration:**
```
External cron job (every 15 min)
↓
GET /api/cron/reminders
↓
Header: x-cron-secret = CRON_SECRET
↓
processEvaluationReminders()
↓
Returns: { ok: true, sent: number, errors: number }
```
#### 3. Grace Periods (GracePeriod model + gracePeriod router)
**Model:**
```prisma
model GracePeriod {
id String @id @default(cuid())
stageId String
userId String
projectId String? // Optional: specific project or all in stage
extendedUntil DateTime
reason String? @db.Text
grantedById String
createdAt DateTime @default(now())
}
```
**Admin operations:**
- `gracePeriod.grant({ stageId, userId, extendedUntil, reason })` — Grant to single user
- `gracePeriod.bulkGrant({ stageId, userIds[], extendedUntil })` — Bulk grant
- `gracePeriod.update({ id, extendedUntil, reason })` — Modify existing
- `gracePeriod.revoke({ id })` — Delete grace period
- `gracePeriod.listByStage({ stageId })` — View all for stage
- `gracePeriod.listActiveByStage({ stageId })` — View active (extendedUntil >= now)
**Usage in code:**
Grace periods are checked during submission and evaluation deadline enforcement:
```typescript
// Check if user has active grace period
const gracePeriod = await prisma.gracePeriod.findFirst({
where: {
stageId,
userId,
extendedUntil: { gte: new Date() },
},
})
const effectiveDeadline = gracePeriod?.extendedUntil ?? stage.windowCloseAt
```
#### 4. Countdown Timer Component (countdown-timer.tsx)
**Client-side countdown:**
```tsx
<CountdownTimer
deadline={new Date(stage.windowCloseAt)}
label="Time remaining"
/>
```
**Features:**
- Real-time countdown (updates every 1 second)
- Color-coded urgency:
- `expired`: Gray (deadline passed)
- `critical`: Red (< 1 hour remaining)
- `warning`: Amber (< 24 hours remaining)
- `normal`: Green (> 24 hours remaining)
- Adaptive display:
- < 1 hour: "15m 30s"
- < 24 hours: "5h 15m 30s"
- > 24 hours: "3d 5h 15m"
- Icons: Clock (normal/warning) or AlertTriangle (critical)
#### 5. In-App Notification Center
**Model:**
```prisma
model InAppNotification {
id String @id @default(cuid())
userId String
type String // Event type
priority String @default("normal") // low, normal, high, urgent
icon String? // lucide icon name
title String
message String @db.Text
linkUrl String? // Where to navigate when clicked
linkLabel String? // CTA text
metadata Json? @db.JsonB
groupKey String? // For batching similar notifications
isRead Boolean @default(false)
readAt DateTime?
expiresAt DateTime? // Auto-dismiss after date
createdAt DateTime @default(now())
}
```
**Notification bell UI:**
- Shows unread count badge
- Dropdown with recent notifications (last 50)
- "Mark all as read" action
- Click notification → navigate to `linkUrl`
- Auto-refresh via tRPC subscription or polling
#### 6. Email Delivery (Nodemailer + Poste.io)
**Email function:**
```typescript
export async function sendStyledNotificationEmail(
to: string,
name: string,
type: string, // Template type
data: {
title: string
message: string
linkUrl?: string
metadata?: Record<string, unknown>
}
): Promise<void>
```
**Email service:**
- SMTP via Poste.io (`:587`)
- HTML templates with brand colors (Red `#de0f1e`, Dark Blue `#053d57`)
- Support for template variables: `{{name}}`, `{{title}}`, `{{message}}`, `{{linkUrl}}`
- Retry logic (3 attempts)
- Logs sent emails to `NotificationLog` table
**Current template types:**
```typescript
const EMAIL_TEMPLATES = {
MAGIC_LINK: 'magic-link',
REMINDER_24H: '24-hour-reminder',
REMINDER_1H: '1-hour-reminder',
ASSIGNMENT_CREATED: 'assignment-created',
FILTERING_COMPLETE: 'filtering-complete',
STAGE_TRANSITIONED: 'stage-transitioned',
DECISION_OVERRIDDEN: 'decision-overridden',
}
```
#### 7. Notification Policy Configuration
**Model:**
```prisma
model NotificationPolicy {
id String @id @default(cuid())
eventType String @unique // e.g., "stage.transitioned"
channel String @default("EMAIL") // EMAIL | IN_APP | BOTH | NONE
templateId String? // Optional reference to MessageTemplate
isActive Boolean @default(true)
configJson Json? @db.JsonB // Additional config
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
```
**Admin UI (future):**
```
┌─ Notification Settings ──────────────────────────────┐
│ │
│ Event Type: stage.transitioned │
│ Channel: [x] Email [x] In-App [ ] Webhook │
│ Active: [x] Enabled │
│ Template: [Stage Transition Email ▼] │
│ │
│ Recipients: [ ] All Admins [x] Program Admins Only │
│ │
│ [Save] [Test Notification] │
└───────────────────────────────────────────────────────┘
```
---
## Redesigned Notification Architecture
### Key Changes from Current System
| Aspect | Current (Stage-based) | Redesigned (Round-based) |
|--------|----------------------|--------------------------|
| **Event naming** | `stage.transitioned` | `round.transitioned` |
| **Entity references** | `stageId`, `trackId` | `roundId` only (no trackId) |
| **Deadline config** | Per-stage in `Stage.configJson` | Per-SubmissionWindow + per-Round |
| **Reminder targets** | Jury only | Jury, applicants, mentors (role-based) |
| **Competition-wide settings** | None (per-stage only) | `Competition.notifyOn*` fields |
| **Grace periods** | Stage-level only | Round-level + window-level |
| **Template system** | Hardcoded types | Zod-validated templates with variables |
### Enhanced Notification Event Model
**New/renamed events:**
```typescript
export const ROUND_EVENT_TYPES = {
// Core round events
ROUND_OPENED: 'round.opened',
ROUND_CLOSED: 'round.closed',
ROUND_TRANSITIONED: 'round.transitioned',
// INTAKE events
SUBMISSION_RECEIVED: 'intake.submission_received',
SUBMISSION_DEADLINE_APPROACHING: 'intake.deadline_approaching',
SUBMISSION_DEADLINE_PASSED: 'intake.deadline_passed',
// FILTERING events
FILTERING_STARTED: 'filtering.started',
FILTERING_COMPLETED: 'filtering.completed',
FILTERING_FLAGGED: 'filtering.flagged_for_review',
PROJECT_ADVANCED: 'filtering.project_advanced',
PROJECT_REJECTED: 'filtering.project_rejected',
// EVALUATION events
ASSIGNMENT_CREATED: 'evaluation.assignment_created',
EVALUATION_DEADLINE_APPROACHING: 'evaluation.deadline_approaching',
EVALUATION_SUBMITTED: 'evaluation.submitted',
EVALUATION_ROUND_COMPLETE: 'evaluation.round_complete',
// SUBMISSION events (round 2+ docs)
SUBMISSION_WINDOW_OPENED: 'submission.window_opened',
NEW_DOCS_REQUIRED: 'submission.new_docs_required',
DOCS_SUBMITTED: 'submission.docs_submitted',
DOCS_DEADLINE_APPROACHING: 'submission.deadline_approaching',
// MENTORING events
MENTOR_ASSIGNED: 'mentoring.assigned',
MENTOR_MESSAGE_RECEIVED: 'mentoring.message_received',
MENTOR_FILE_UPLOADED: 'mentoring.file_uploaded',
MENTOR_FILE_PROMOTED: 'mentoring.file_promoted',
// LIVE_FINAL events
CEREMONY_STARTING: 'live_final.ceremony_starting',
VOTE_REQUIRED: 'live_final.vote_required',
DELIBERATION_STARTED: 'live_final.deliberation_started',
RESULTS_READY: 'live_final.results_ready',
// CONFIRMATION events
WINNER_APPROVAL_REQUIRED: 'confirmation.approval_required',
WINNER_APPROVED: 'confirmation.approved',
RESULTS_FROZEN: 'confirmation.frozen',
// Admin events
DECISION_OVERRIDDEN: 'admin.decision_overridden',
GRACE_PERIOD_GRANTED: 'admin.grace_period_granted',
DEADLINE_EXTENDED: 'admin.deadline_extended',
}
```
### Competition-Wide Notification Settings
**Enhanced Competition model:**
```prisma
model Competition {
// ... existing fields ...
// Global notification preferences
notifyOnRoundAdvance Boolean @default(true)
notifyOnDeadlineApproach Boolean @default(true)
notifyOnAssignmentCreated Boolean @default(true)
notifyOnSubmissionReceived Boolean @default(true)
notifyOnFilteringComplete Boolean @default(true)
// Reminder configuration
deadlineReminderDays Int[] @default([7, 3, 1]) // Days before deadline
deadlineReminderHours Int[] @default([24, 3, 1]) // Hours before deadline (final stretch)
// Email templates
notificationEmailFromName String? // Override default "MOPC Platform"
notificationEmailReplyTo String? // Custom reply-to for this competition
// Advanced settings
batchNotifications Boolean @default(false) // Group similar notifications
batchIntervalMinutes Int @default(30) // Batch every 30 min
notificationTimezone String @default("UTC") // For deadline display
}
```
### Per-Round Notification Overrides
**Round-level overrides:**
```prisma
model Round {
// ... existing fields ...
// Notification overrides (null = use competition defaults)
notifyOnRoundOpen Boolean? // Override competition.notifyOnRoundAdvance
notifyOnDeadline Boolean? // Override competition.notifyOnDeadlineApproach
customReminderSchedule Json? @db.JsonB // { days: [7, 3, 1], hours: [24, 6, 1] }
// Email template overrides
openEmailTemplateId String? // Custom template for round open
reminderEmailTemplateId String? // Custom template for reminders
}
```
**Example custom schedule:**
```typescript
// For Live Finals round — aggressive reminders
{
days: [7, 3], // 7 days before, 3 days before
hours: [24, 12, 6, 1] // 24h, 12h, 6h, 1h before ceremony
}
```
---
## Deadline Management System
### DeadlinePolicy Enum
**Three deadline modes:**
```prisma
enum DeadlinePolicy {
HARD // Submissions rejected after windowCloseAt (strict cutoff)
FLAG // Submissions accepted but marked late (isLate = true)
GRACE // Grace period after windowCloseAt, then hard cutoff
}
```
**Applied at SubmissionWindow level:**
```prisma
model SubmissionWindow {
// ... existing fields ...
deadlinePolicy DeadlinePolicy @default(FLAG)
graceHours Int? // For GRACE policy: hours after windowCloseAt
}
```
**Evaluation rounds use Round.windowCloseAt + GracePeriod model:**
```prisma
model Round {
windowOpenAt DateTime?
windowCloseAt DateTime?
// Jury evaluation deadline behavior
evaluationDeadlinePolicy String @default("FLAG") // "HARD" | "FLAG" | "GRACE"
evaluationGraceHours Int?
}
```
### Deadline Enforcement Logic
**Submission deadline check:**
```typescript
type SubmissionDeadlineCheck = {
allowed: boolean
isLate: boolean
reason?: string
}
export async function checkSubmissionDeadline(
submissionWindowId: string,
userId: string,
prisma: PrismaClient
): Promise<SubmissionDeadlineCheck> {
const window = await prisma.submissionWindow.findUnique({
where: { id: submissionWindowId },
select: {
windowOpenAt: true,
windowCloseAt: true,
deadlinePolicy: true,
graceHours: true,
},
})
const now = new Date()
// Before window opens
if (window.windowOpenAt && now < window.windowOpenAt) {
return { allowed: false, reason: 'Window not yet open' }
}
// Within normal window
if (!window.windowCloseAt || now <= window.windowCloseAt) {
return { allowed: true, isLate: false }
}
// After window close
switch (window.deadlinePolicy) {
case 'HARD':
return { allowed: false, reason: 'Deadline passed (hard cutoff)' }
case 'FLAG':
return { allowed: true, isLate: true }
case 'GRACE': {
if (!window.graceHours) {
return { allowed: false, reason: 'Grace period not configured' }
}
const graceEnd = new Date(
window.windowCloseAt.getTime() + window.graceHours * 60 * 60 * 1000
)
if (now <= graceEnd) {
return { allowed: true, isLate: true }
} else {
return { allowed: false, reason: 'Grace period expired' }
}
}
}
}
```
**Evaluation deadline check (with per-user grace periods):**
```typescript
export async function checkEvaluationDeadline(
roundId: string,
userId: string,
prisma: PrismaClient
): Promise<SubmissionDeadlineCheck> {
const round = await prisma.round.findUnique({
where: { id: roundId },
select: {
windowCloseAt: true,
evaluationDeadlinePolicy: true,
evaluationGraceHours: true,
},
})
// Check for user-specific grace period (highest priority)
const userGrace = await prisma.gracePeriod.findFirst({
where: {
roundId,
userId,
extendedUntil: { gte: new Date() },
},
orderBy: { extendedUntil: 'desc' },
})
const effectiveDeadline = userGrace?.extendedUntil ?? round.windowCloseAt
const now = new Date()
if (!effectiveDeadline || now <= effectiveDeadline) {
return { allowed: true, isLate: false }
}
// Past effective deadline
switch (round.evaluationDeadlinePolicy) {
case 'HARD':
return { allowed: false, reason: 'Evaluation deadline passed' }
case 'FLAG':
return { allowed: true, isLate: true }
case 'GRACE': {
if (!round.evaluationGraceHours) {
return { allowed: false, reason: 'Grace period not configured' }
}
const graceEnd = new Date(
effectiveDeadline.getTime() + round.evaluationGraceHours * 60 * 60 * 1000
)
if (now <= graceEnd) {
return { allowed: true, isLate: true }
} else {
return { allowed: false, reason: 'Grace period expired' }
}
}
}
}
```
### Deadline Extension by Admin
**Admin deadline extension workflow:**
```typescript
// Option 1: Extend round window (affects everyone)
trpc.round.extendDeadline.useMutation({
roundId: 'round-123',
newWindowCloseAt: new Date('2026-03-15T23:59:59Z'),
reason: 'Extended due to technical issues',
notifyParticipants: true, // Send email to all affected users
})
// Option 2: Grant individual grace periods (granular)
trpc.gracePeriod.grant.useMutation({
roundId: 'round-123',
userId: 'jury-456',
extendedUntil: new Date('2026-03-15T23:59:59Z'),
reason: 'Medical emergency',
})
// Option 3: Bulk grace periods for entire jury
trpc.gracePeriod.bulkGrant.useMutation({
roundId: 'round-123',
userIds: ['jury-1', 'jury-2', 'jury-3'], // All Jury 1 members
extendedUntil: new Date('2026-03-15T23:59:59Z'),
reason: 'Extended for Jury 1',
})
```
**Audit trail:**
All deadline changes create:
1. `DecisionAuditLog` entry with `eventType: "admin.deadline_extended"`
2. `OverrideAction` entry (if overriding automated behavior)
3. In-app notification to affected users
4. Email notification (if `notifyParticipants: true`)
---
## Notification Events by Round Type
### Complete Event Matrix
| Round Type | Event | Triggered When | Recipients | Channel |
|------------|-------|----------------|------------|---------|
| **INTAKE** | `intake.window_opened` | Round status → ACTIVE | All applicants | Email + In-app |
| | `intake.submission_received` | ProjectFile.create() | Applicant (team lead) | Email + In-app |
| | `intake.deadline_approaching` | Cron: 7d, 3d, 1d before close | Applicants without submission | Email + In-app |
| | `intake.deadline_passed` | windowCloseAt reached | All applicants | In-app only |
| | `intake.window_extended` | Admin extends deadline | All applicants | Email + In-app |
| **FILTERING** | `filtering.started` | FilteringJob.create() | Admins | In-app only |
| | `filtering.completed` | FilteringJob.status → COMPLETED | Admins | Email + In-app |
| | `filtering.flagged_for_review` | FilteringResult.outcome → FLAGGED | Admins | Email (high priority) |
| | `filtering.project_advanced` | ProjectRoundState.state → PASSED | Applicant (team lead) | Email + In-app |
| | `filtering.project_rejected` | ProjectRoundState.state → REJECTED | Applicant (team lead) | Email + In-app |
| **EVALUATION** | `evaluation.assignment_created` | Assignment.create() | Assigned juror | Email + In-app |
| | `evaluation.deadline_approaching` | Cron: 7d, 3d, 1d, 24h, 3h, 1h before close | Jurors with incomplete assignments | Email + In-app |
| | `evaluation.submitted` | Evaluation.status → SUBMITTED | Admin, jury lead | In-app only |
| | `evaluation.round_complete` | All assignments completed | Admins | Email + In-app |
| | `evaluation.summary_generated` | EvaluationSummary.create() | Admins | In-app only |
| **SUBMISSION** | `submission.window_opened` | SubmissionWindow opens | Eligible teams (PASSED from prev round) | Email + In-app |
| | `submission.new_docs_required` | Round status → ACTIVE | Eligible teams | Email (high priority) |
| | `submission.docs_submitted` | ProjectFile.create() for window | Applicant (team lead) | Email + In-app |
| | `submission.deadline_approaching` | Cron: 7d, 3d, 1d before close | Teams without complete submission | Email + In-app |
| | `submission.docs_reviewed` | Admin marks review complete | Applicant (team lead) | Email + In-app |
| **MENTORING** | `mentoring.assigned` | MentorAssignment.create() | Mentor + Team | Email + In-app |
| | `mentoring.workspace_opened` | Round status → ACTIVE | Mentor + Team | Email + In-app |
| | `mentoring.message_received` | MentorMessage.create() | Recipient (mentor or team) | Email + In-app |
| | `mentoring.file_uploaded` | MentorFile.create() | Other party (mentor or team) | In-app + Email |
| | `mentoring.file_promoted` | MentorFile.isPromoted → true | Team lead | Email + In-app |
| | `mentoring.milestone_completed` | MentorMilestoneCompletion.create() | Mentor + Team | In-app only |
| **LIVE_FINAL** | `live_final.ceremony_starting` | LiveVotingSession.status → IN_PROGRESS | Jury + Audience | Email + In-app |
| | `live_final.vote_required` | LiveProgressCursor updated | Jury members | In-app only (real-time) |
| | `live_final.deliberation_started` | Deliberation period begins | Jury | In-app only |
| | `live_final.results_ready` | All votes cast | Admins | In-app only |
| **CONFIRMATION** | `confirmation.approval_required` | WinnerProposal.create() | Jury members + Admins | Email (urgent) + In-app |
| | `confirmation.approval_received` | WinnerApproval.approved → true | Admins | In-app only |
| | `confirmation.approved` | All approvals received | Admins + Jury | Email + In-app |
| | `confirmation.frozen` | WinnerProposal.frozenAt set | All participants | Email + In-app |
| **ADMIN** | `admin.decision_overridden` | OverrideAction.create() | Admins | Email (audit alert) |
| | `admin.grace_period_granted` | GracePeriod.create() | Affected user | Email + In-app |
| | `admin.deadline_extended` | Round.windowCloseAt updated | All affected users | Email + In-app |
### Event Payload Schemas (Zod)
**Base event schema:**
```typescript
import { z } from 'zod'
export const BaseEventSchema = z.object({
eventType: z.string(),
entityType: z.string(),
entityId: z.string(),
actorId: z.string(),
timestamp: z.date(),
metadata: z.record(z.unknown()).optional(),
})
export type BaseEvent = z.infer<typeof BaseEventSchema>
```
**Intake events:**
```typescript
export const IntakeWindowOpenedSchema = BaseEventSchema.extend({
eventType: z.literal('intake.window_opened'),
entityType: z.literal('Round'),
roundId: z.string(),
roundName: z.string(),
windowOpenAt: z.date(),
windowCloseAt: z.date(),
competitionId: z.string(),
})
export const SubmissionReceivedSchema = BaseEventSchema.extend({
eventType: z.literal('intake.submission_received'),
entityType: z.literal('ProjectFile'),
projectId: z.string(),
projectTitle: z.string(),
submittedByUserId: z.string(),
fileCount: z.number(),
isComplete: z.boolean(), // All required files uploaded
})
export const DeadlineApproachingSchema = BaseEventSchema.extend({
eventType: z.literal('intake.deadline_approaching'),
entityType: z.literal('SubmissionWindow'),
roundId: z.string(),
roundName: z.string(),
windowCloseAt: z.date(),
daysRemaining: z.number(),
hoursRemaining: z.number().optional(),
})
```
**Evaluation events:**
```typescript
export const AssignmentCreatedSchema = BaseEventSchema.extend({
eventType: z.literal('evaluation.assignment_created'),
entityType: z.literal('Assignment'),
assignmentId: z.string(),
roundId: z.string(),
roundName: z.string(),
projectId: z.string(),
projectTitle: z.string(),
juryGroupId: z.string(),
juryGroupName: z.string(),
deadline: z.date(),
})
export const EvaluationDeadlineApproachingSchema = BaseEventSchema.extend({
eventType: z.literal('evaluation.deadline_approaching'),
entityType: z.literal('Round'),
roundId: z.string(),
roundName: z.string(),
incompleteCount: z.number(),
totalCount: z.number(),
deadline: z.date(),
reminderType: z.enum(['7d', '3d', '1d', '24h', '3h', '1h']),
})
```
**Mentoring events:**
```typescript
export const MentorAssignedSchema = BaseEventSchema.extend({
eventType: z.literal('mentoring.assigned'),
entityType: z.literal('MentorAssignment'),
mentorId: z.string(),
mentorName: z.string(),
projectId: z.string(),
projectTitle: z.string(),
teamLeadId: z.string(),
teamLeadName: z.string(),
workspaceOpenAt: z.date().optional(),
})
export const MentorFileUploadedSchema = BaseEventSchema.extend({
eventType: z.literal('mentoring.file_uploaded'),
entityType: z.literal('MentorFile'),
fileId: z.string(),
fileName: z.string(),
uploadedByUserId: z.string(),
uploadedByRole: z.enum(['MENTOR', 'APPLICANT']),
mentorAssignmentId: z.string(),
projectId: z.string(),
})
```
**Confirmation events:**
```typescript
export const WinnerApprovalRequiredSchema = BaseEventSchema.extend({
eventType: z.literal('confirmation.approval_required'),
entityType: z.literal('WinnerProposal'),
proposalId: z.string(),
category: z.enum(['STARTUP', 'BUSINESS_CONCEPT']),
rankedProjectIds: z.array(z.string()),
requiredApprovers: z.array(z.object({
userId: z.string(),
role: z.enum(['JURY_MEMBER', 'ADMIN']),
})),
deadline: z.date().optional(),
})
export const ResultsFrozenSchema = BaseEventSchema.extend({
eventType: z.literal('confirmation.frozen'),
entityType: z.literal('WinnerProposal'),
proposalId: z.string(),
category: z.enum(['STARTUP', 'BUSINESS_CONCEPT']),
frozenAt: z.date(),
frozenByUserId: z.string(),
rankedProjectIds: z.array(z.string()),
})
```
---
## Notification Channels
### 1. Email Channel
**Email service interface:**
```typescript
export interface EmailNotificationData {
to: string // Recipient email
name: string // Recipient name
subject: string // Email subject
template: string // Template ID
variables: Record<string, unknown> // Template variables
replyTo?: string // Custom reply-to
priority?: 'low' | 'normal' | 'high' | 'urgent'
}
export async function sendNotificationEmail(
data: EmailNotificationData
): Promise<void>
```
**Email templates with variables:**
```typescript
// Template: evaluation-deadline-reminder
const template = `
<!DOCTYPE html>
<html>
<head>
<style>
body { font-family: Montserrat, Arial, sans-serif; }
.header { background: #053d57; color: white; padding: 20px; }
.content { padding: 20px; }
.countdown { background: #fef5f5; border-left: 4px solid #de0f1e; padding: 15px; margin: 20px 0; }
.cta { background: #de0f1e; color: white; padding: 12px 24px; text-decoration: none; border-radius: 4px; }
</style>
</head>
<body>
<div class="header">
<h1>{{competitionName}}</h1>
</div>
<div class="content">
<p>Dear {{name}},</p>
<p>This is a reminder that you have <strong>{{incompleteCount}} pending evaluation{{incompleteCount > 1 ? 's' : ''}}</strong> for <strong>{{roundName}}</strong>.</p>
<div class="countdown">
<h3>⏰ Deadline: {{deadline}}</h3>
<p>{{timeRemaining}} remaining</p>
</div>
<p>Please complete your evaluations before the deadline.</p>
<p style="text-align: center; margin: 30px 0;">
<a href="{{linkUrl}}" class="cta">Complete Evaluations</a>
</p>
<p>If you need an extension, please contact the program administrator.</p>
<p>Best regards,<br>{{competitionName}} Team</p>
</div>
</body>
</html>
`
// Variables passed to template:
{
name: "Dr. Smith",
competitionName: "MOPC 2026",
roundName: "Jury 1 - Semi-finalist Selection",
incompleteCount: 5,
deadline: "March 15, 2026 at 11:59 PM CET",
timeRemaining: "2 days 5 hours",
linkUrl: "https://monaco-opc.com/jury/rounds/round-123/assignments"
}
```
**Email delivery tracking:**
```prisma
model NotificationLog {
id String @id @default(cuid())
userId String
channel NotificationChannel // EMAIL, WHATSAPP, BOTH, NONE
provider String? // SMTP, META, TWILIO
type String // Event type
status String // PENDING, SENT, DELIVERED, FAILED
externalId String? // Message ID from provider
errorMsg String? @db.Text
createdAt DateTime @default(now())
}
```
### 2. In-App Notification Center
**UI components:**
**Notification Bell (Header):**
```tsx
// src/components/layout/notification-bell.tsx
'use client'
import { Bell } from 'lucide-react'
import { Button } from '@/components/ui/button'
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu'
import { trpc } from '@/lib/trpc/client'
import { NotificationItem } from './notification-item'
export function NotificationBell() {
const { data: unreadCount } = trpc.notification.getUnreadCount.useQuery()
const { data: recent } = trpc.notification.getRecent.useQuery({ limit: 10 })
const markAllRead = trpc.notification.markAllRead.useMutation()
return (
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button variant="ghost" size="icon" className="relative">
<Bell className="h-5 w-5" />
{unreadCount > 0 && (
<span className="absolute -top-1 -right-1 flex h-5 w-5 items-center justify-center rounded-full bg-red-600 text-xs text-white">
{unreadCount > 9 ? '9+' : unreadCount}
</span>
)}
</Button>
</DropdownMenuTrigger>
<DropdownMenuContent align="end" className="w-80">
<div className="flex items-center justify-between px-3 py-2 border-b">
<h3 className="font-semibold">Notifications</h3>
{unreadCount > 0 && (
<Button
variant="ghost"
size="sm"
onClick={() => markAllRead.mutate()}
>
Mark all read
</Button>
)}
</div>
<div className="max-h-96 overflow-y-auto">
{recent?.map((notification) => (
<NotificationItem key={notification.id} notification={notification} />
))}
{recent?.length === 0 && (
<div className="p-6 text-center text-muted-foreground">
No notifications
</div>
)}
</div>
<div className="border-t p-2">
<Button variant="ghost" size="sm" className="w-full" asChild>
<Link href="/notifications">View all notifications</Link>
</Button>
</div>
</DropdownMenuContent>
</DropdownMenu>
)
}
```
**Notification Item:**
```tsx
// src/components/layout/notification-item.tsx
'use client'
import { useRouter } from 'next/navigation'
import { formatDistanceToNow } from 'date-fns'
import { cn } from '@/lib/utils'
import { trpc } from '@/lib/trpc/client'
import * as Icons from 'lucide-react'
type Notification = {
id: string
type: string
title: string
message: string
icon?: string
priority: string
linkUrl?: string
isRead: boolean
createdAt: Date
}
export function NotificationItem({ notification }: { notification: Notification }) {
const router = useRouter()
const markRead = trpc.notification.markRead.useMutation()
const Icon = notification.icon ? Icons[notification.icon] : Icons.Bell
const handleClick = () => {
if (!notification.isRead) {
markRead.mutate({ id: notification.id })
}
if (notification.linkUrl) {
router.push(notification.linkUrl)
}
}
return (
<div
onClick={handleClick}
className={cn(
'flex gap-3 p-3 cursor-pointer hover:bg-accent transition-colors border-b last:border-0',
!notification.isRead && 'bg-blue-50 dark:bg-blue-950/20'
)}
>
{Icon && (
<div className={cn(
'flex-shrink-0 w-8 h-8 rounded-full flex items-center justify-center',
notification.priority === 'urgent' && 'bg-red-100 text-red-600',
notification.priority === 'high' && 'bg-orange-100 text-orange-600',
notification.priority === 'normal' && 'bg-blue-100 text-blue-600',
notification.priority === 'low' && 'bg-gray-100 text-gray-600'
)}>
<Icon className="h-4 w-4" />
</div>
)}
<div className="flex-1 min-w-0">
<div className="flex items-center justify-between gap-2">
<h4 className={cn(
'text-sm font-medium truncate',
!notification.isRead && 'font-semibold'
)}>
{notification.title}
</h4>
{!notification.isRead && (
<div className="w-2 h-2 bg-blue-600 rounded-full flex-shrink-0" />
)}
</div>
<p className="text-sm text-muted-foreground line-clamp-2 mt-0.5">
{notification.message}
</p>
<p className="text-xs text-muted-foreground mt-1">
{formatDistanceToNow(notification.createdAt, { addSuffix: true })}
</p>
</div>
</div>
)
}
```
**Notification Center Page:**
```tsx
// src/app/(authenticated)/notifications/page.tsx
'use client'
import { useState } from 'react'
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
import { trpc } from '@/lib/trpc/client'
import { NotificationItem } from '@/components/layout/notification-item'
export default function NotificationsPage() {
const [filter, setFilter] = useState<'all' | 'unread'>('all')
const { data: notifications } = trpc.notification.getAll.useQuery({
filter,
limit: 100,
})
return (
<div className="container max-w-4xl py-8">
<h1 className="text-3xl font-bold mb-6">Notifications</h1>
<Tabs value={filter} onValueChange={(v) => setFilter(v as any)}>
<TabsList>
<TabsTrigger value="all">All</TabsTrigger>
<TabsTrigger value="unread">Unread</TabsTrigger>
</TabsList>
<TabsContent value={filter} className="mt-4">
<div className="border rounded-lg divide-y">
{notifications?.map((n) => (
<NotificationItem key={n.id} notification={n} />
))}
{notifications?.length === 0 && (
<div className="p-8 text-center text-muted-foreground">
No notifications to show
</div>
)}
</div>
</TabsContent>
</Tabs>
</div>
)
}
```
### 3. Future: Webhook Channel
**Webhook integration (future enhancement):**
```typescript
// Future: Webhook delivery for external integrations
export interface WebhookNotificationPayload {
event: string
timestamp: string
data: Record<string, unknown>
signature: string // HMAC signature for verification
}
// Example webhook payload
{
event: "evaluation.deadline_approaching",
timestamp: "2026-03-10T15:00:00Z",
data: {
competitionId: "comp-123",
roundId: "round-456",
roundName: "Jury 1 - Semi-finalist Selection",
deadline: "2026-03-15T23:59:59Z",
daysRemaining: 5,
incompleteAssignments: 12,
totalAssignments: 60
},
signature: "sha256=..."
}
```
**Webhook configuration (future):**
```prisma
model Webhook {
id String @id @default(cuid())
name String
url String
secret String // For HMAC signature
events String[] // Event types to subscribe to
headers Json? @db.JsonB
maxRetries Int @default(3)
isActive Boolean @default(true)
createdById String
}
```
---
## Countdown Timer System
### Real-Time Countdown Component
**Enhanced countdown timer:**
```tsx
// src/components/shared/countdown-timer.tsx
'use client'
import { useState, useEffect } from 'react'
import { cn } from '@/lib/utils'
import { Clock, AlertTriangle, CheckCircle } from 'lucide-react'
export interface CountdownTimerProps {
deadline: Date
label?: string
className?: string
showIcon?: boolean
size?: 'sm' | 'md' | 'lg'
onExpire?: () => void
}
interface TimeRemaining {
days: number
hours: number
minutes: number
seconds: number
totalMs: number
}
function getTimeRemaining(deadline: Date): TimeRemaining {
const totalMs = deadline.getTime() - Date.now()
if (totalMs <= 0) {
return { days: 0, hours: 0, minutes: 0, seconds: 0, totalMs: 0 }
}
const seconds = Math.floor((totalMs / 1000) % 60)
const minutes = Math.floor((totalMs / 1000 / 60) % 60)
const hours = Math.floor((totalMs / (1000 * 60 * 60)) % 24)
const days = Math.floor(totalMs / (1000 * 60 * 60 * 24))
return { days, hours, minutes, seconds, totalMs }
}
function formatCountdown(time: TimeRemaining, size: 'sm' | 'md' | 'lg'): string {
if (time.totalMs <= 0) return 'Deadline passed'
const { days, hours, minutes, seconds } = time
// Small size: compact format
if (size === 'sm') {
if (days === 0 && hours === 0) return `${minutes}m ${seconds}s`
if (days === 0) return `${hours}h ${minutes}m`
return `${days}d ${hours}h`
}
// Medium/large: more detail
if (days === 0 && hours === 0) {
return `${minutes} minutes ${seconds} seconds`
}
if (days === 0) {
return `${hours} hours ${minutes} minutes`
}
return `${days} days ${hours} hours ${minutes} minutes`
}
type Urgency = 'expired' | 'critical' | 'warning' | 'normal'
function getUrgency(totalMs: number): Urgency {
if (totalMs <= 0) return 'expired'
if (totalMs < 60 * 60 * 1000) return 'critical' // < 1 hour
if (totalMs < 24 * 60 * 60 * 1000) return 'warning' // < 24 hours
if (totalMs < 7 * 24 * 60 * 60 * 1000) return 'normal' // < 7 days
return 'normal'
}
const urgencyStyles: Record<Urgency, string> = {
expired: 'text-muted-foreground bg-muted border-muted',
critical: 'text-red-700 bg-red-50 border-red-200 dark:text-red-400 dark:bg-red-950/50 dark:border-red-900',
warning: 'text-amber-700 bg-amber-50 border-amber-200 dark:text-amber-400 dark:bg-amber-950/50 dark:border-amber-900',
normal: 'text-green-700 bg-green-50 border-green-200 dark:text-green-400 dark:bg-green-950/50 dark:border-green-900',
}
const sizeStyles = {
sm: 'text-xs px-2 py-0.5',
md: 'text-sm px-2.5 py-1',
lg: 'text-base px-3 py-1.5',
}
export function CountdownTimer({
deadline,
label,
className,
showIcon = true,
size = 'md',
onExpire,
}: CountdownTimerProps) {
const [time, setTime] = useState<TimeRemaining>(() => getTimeRemaining(deadline))
const [hasExpired, setHasExpired] = useState(false)
useEffect(() => {
const timer = setInterval(() => {
const remaining = getTimeRemaining(deadline)
setTime(remaining)
if (remaining.totalMs <= 0 && !hasExpired) {
clearInterval(timer)
setHasExpired(true)
onExpire?.()
}
}, 1000)
return () => clearInterval(timer)
}, [deadline, hasExpired, onExpire])
const urgency = getUrgency(time.totalMs)
const displayText = formatCountdown(time, size)
const IconComponent =
urgency === 'expired' ? CheckCircle :
urgency === 'critical' ? AlertTriangle :
Clock
return (
<div
className={cn(
'inline-flex items-center gap-1.5 rounded-md border font-medium',
urgencyStyles[urgency],
sizeStyles[size],
className
)}
>
{showIcon && <IconComponent className={cn(
'shrink-0',
size === 'sm' && 'h-3 w-3',
size === 'md' && 'h-4 w-4',
size === 'lg' && 'h-5 w-5'
)} />}
{label && <span className="hidden sm:inline">{label}</span>}
<span className="tabular-nums">{displayText}</span>
</div>
)
}
```
**Usage examples:**
```tsx
// Jury dashboard - evaluation deadline
<CountdownTimer
deadline={round.windowCloseAt}
label="Evaluation deadline:"
size="lg"
onExpire={() => toast.info('Deadline has passed')}
/>
// Applicant dashboard - submission deadline
<CountdownTimer
deadline={submissionWindow.windowCloseAt}
label="Submit by:"
size="md"
/>
// Admin dashboard - compact view
<CountdownTimer
deadline={round.windowCloseAt}
size="sm"
showIcon={false}
/>
```
### Server-Side Time Sync
**Prevent client clock drift:**
```typescript
// src/server/routers/time.ts
import { router, publicProcedure } from '../trpc'
export const timeRouter = router({
/**
* Get server time (for clock sync)
*/
getServerTime: publicProcedure.query(() => {
return {
serverTime: new Date().toISOString(),
timezone: 'UTC',
}
}),
})
// Client-side sync
// src/hooks/use-server-time-sync.ts
'use client'
import { useEffect, useState } from 'use'
import { trpc } from '@/lib/trpc/client'
export function useServerTimeSync() {
const [timeOffset, setTimeOffset] = useState(0)
const { data } = trpc.time.getServerTime.useQuery()
useEffect(() => {
if (data) {
const serverTime = new Date(data.serverTime).getTime()
const clientTime = Date.now()
setTimeOffset(serverTime - clientTime)
}
}, [data])
const getSyncedTime = () => Date.now() + timeOffset
return { getSyncedTime, timeOffset }
}
// Use in countdown
function getTimeRemaining(deadline: Date): TimeRemaining {
const { getSyncedTime } = useServerTimeSync()
const totalMs = deadline.getTime() - getSyncedTime()
// ... rest of logic
}
```
---
## Reminder Scheduling
### Cron-Based Reminder System
**Cron endpoint:**
```typescript
// src/app/api/cron/reminders/route.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { processDeadlineReminders } from '@/server/services/deadline-reminders'
export async function GET(request: NextRequest): Promise<NextResponse> {
// Verify cron secret
const cronSecret = request.headers.get('x-cron-secret')
if (!cronSecret || cronSecret !== process.env.CRON_SECRET) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
}
try {
const result = await processDeadlineReminders()
return NextResponse.json({
ok: true,
sent: result.sent,
errors: result.errors,
timestamp: new Date().toISOString(),
})
} catch (error) {
console.error('Cron reminder processing failed:', error)
return NextResponse.json(
{ error: 'Internal server error' },
{ status: 500 }
)
}
}
```
**Reminder processor (redesigned):**
```typescript
// src/server/services/deadline-reminders.ts
import { prisma } from '@/lib/prisma'
import { sendNotificationEmail } from '@/lib/email'
import { emitRoundEvent } from './round-notifications'
interface ReminderResult {
sent: number
errors: number
}
/**
* Process deadline reminders for all active rounds and submission windows.
* Called by cron job every 15 minutes.
*/
export async function processDeadlineReminders(): Promise<ReminderResult> {
const now = new Date()
let totalSent = 0
let totalErrors = 0
// Process evaluation round reminders
const evalResults = await processEvaluationReminders(now)
totalSent += evalResults.sent
totalErrors += evalResults.errors
// Process submission window reminders
const submissionResults = await processSubmissionReminders(now)
totalSent += submissionResults.sent
totalErrors += submissionResults.errors
return { sent: totalSent, errors: totalErrors }
}
/**
* Send reminders to jurors with incomplete evaluations.
*/
async function processEvaluationReminders(now: Date): Promise<ReminderResult> {
let sent = 0
let errors = 0
// Find active evaluation rounds with upcoming deadlines
const rounds = await prisma.round.findMany({
where: {
roundType: 'EVALUATION',
status: 'ROUND_ACTIVE',
windowCloseAt: { gt: now },
windowOpenAt: { lte: now },
},
select: {
id: true,
name: true,
windowCloseAt: true,
competition: {
select: {
id: true,
name: true,
deadlineReminderDays: true,
deadlineReminderHours: true,
},
},
},
})
for (const round of rounds) {
if (!round.windowCloseAt) continue
const msUntilDeadline = round.windowCloseAt.getTime() - now.getTime()
// Determine which reminders should fire
const reminderTypes = getReminderTypesForDeadline(
msUntilDeadline,
round.competition.deadlineReminderDays,
round.competition.deadlineReminderHours
)
if (reminderTypes.length === 0) continue
for (const reminderType of reminderTypes) {
const result = await sendEvaluationReminders(round, reminderType, now)
sent += result.sent
errors += result.errors
}
}
return { sent, errors }
}
/**
* Send reminders to applicants with incomplete submissions.
*/
async function processSubmissionReminders(now: Date): Promise<ReminderResult> {
let sent = 0
let errors = 0
// Find active submission windows with upcoming deadlines
const windows = await prisma.submissionWindow.findMany({
where: {
windowCloseAt: { gt: now },
windowOpenAt: { lte: now },
},
select: {
id: true,
name: true,
windowCloseAt: true,
competition: {
select: {
id: true,
name: true,
deadlineReminderDays: true,
deadlineReminderHours: true,
},
},
fileRequirements: {
select: { id: true, isRequired: true },
},
rounds: {
select: { id: true, name: true },
where: { roundType: { in: ['INTAKE', 'SUBMISSION'] } },
},
},
})
for (const window of windows) {
if (!window.windowCloseAt) continue
const msUntilDeadline = window.windowCloseAt.getTime() - now.getTime()
const reminderTypes = getReminderTypesForDeadline(
msUntilDeadline,
window.competition.deadlineReminderDays,
window.competition.deadlineReminderHours
)
if (reminderTypes.length === 0) continue
for (const reminderType of reminderTypes) {
const result = await sendSubmissionReminders(window, reminderType, now)
sent += result.sent
errors += result.errors
}
}
return { sent, errors }
}
/**
* Determine which reminder types should fire based on time until deadline.
*/
function getReminderTypesForDeadline(
msUntilDeadline: number,
reminderDays: number[],
reminderHours: number[]
): string[] {
const types: string[] = []
// Check day-based reminders
for (const days of reminderDays) {
const thresholdMs = days * 24 * 60 * 60 * 1000
const windowMs = 15 * 60 * 1000 // 15-minute cron window
if (Math.abs(msUntilDeadline - thresholdMs) < windowMs) {
types.push(`${days}d`)
}
}
// Check hour-based reminders (only if < 48 hours remaining)
if (msUntilDeadline < 48 * 60 * 60 * 1000) {
for (const hours of reminderHours) {
const thresholdMs = hours * 60 * 60 * 1000
const windowMs = 15 * 60 * 1000
if (Math.abs(msUntilDeadline - thresholdMs) < windowMs) {
types.push(`${hours}h`)
}
}
}
return types
}
/**
* Send evaluation deadline reminders to jurors.
*/
async function sendEvaluationReminders(
round: any,
reminderType: string,
now: Date
): Promise<ReminderResult> {
let sent = 0
let errors = 0
// Find jurors with incomplete assignments
const incompleteAssignments = await prisma.assignment.findMany({
where: {
roundId: round.id,
isCompleted: false,
},
select: {
userId: true,
user: {
select: {
id: true,
name: true,
email: true,
},
},
},
})
// Group by user
const userAssignments = new Map<string, number>()
for (const assignment of incompleteAssignments) {
userAssignments.set(
assignment.userId,
(userAssignments.get(assignment.userId) || 0) + 1
)
}
// Check who already received this reminder
const existingReminders = await prisma.reminderLog.findMany({
where: {
roundId: round.id,
type: reminderType,
},
select: { userId: true },
})
const alreadySent = new Set(existingReminders.map((r) => r.userId))
// Send reminders
for (const [userId, incompleteCount] of userAssignments.entries()) {
if (alreadySent.has(userId)) continue
const assignment = incompleteAssignments.find((a) => a.userId === userId)
if (!assignment) continue
try {
await sendNotificationEmail({
to: assignment.user.email,
name: assignment.user.name || '',
subject: `Reminder: ${incompleteCount} pending evaluation${incompleteCount > 1 ? 's' : ''}`,
template: 'evaluation-deadline-reminder',
variables: {
name: assignment.user.name,
competitionName: round.competition.name,
roundName: round.name,
incompleteCount,
totalCount: userAssignments.get(userId),
deadline: round.windowCloseAt.toISOString(),
reminderType,
linkUrl: `${process.env.NEXTAUTH_URL}/jury/rounds/${round.id}/assignments`,
},
priority: reminderType.includes('h') ? 'high' : 'normal',
})
// Log reminder
await prisma.reminderLog.create({
data: {
roundId: round.id,
userId,
type: reminderType,
},
})
// Emit event
await emitRoundEvent(
'evaluation.deadline_approaching',
'Round',
round.id,
'system',
{
roundId: round.id,
roundName: round.name,
userId,
incompleteCount,
reminderType,
deadline: round.windowCloseAt,
},
prisma
)
sent++
} catch (error) {
console.error(
`Failed to send ${reminderType} reminder to ${assignment.user.email}:`,
error
)
errors++
}
}
return { sent, errors }
}
/**
* Send submission deadline reminders to applicants.
*/
async function sendSubmissionReminders(
window: any,
reminderType: string,
now: Date
): Promise<ReminderResult> {
let sent = 0
let errors = 0
// Find projects in this submission window's rounds
const roundIds = window.rounds.map((r: any) => r.id)
const eligibleProjects = await prisma.projectRoundState.findMany({
where: {
roundId: { in: roundIds },
state: { in: ['PENDING', 'IN_PROGRESS'] },
},
select: {
projectId: true,
project: {
select: {
id: true,
title: true,
submittedByUserId: true,
submittedBy: {
select: {
id: true,
name: true,
email: true,
},
},
},
},
},
})
// Check which projects have incomplete submissions
const requiredFileCount = window.fileRequirements.filter(
(r: any) => r.isRequired
).length
for (const state of eligibleProjects) {
if (!state.project.submittedBy) continue
// Count uploaded files for this window
const uploadedFiles = await prisma.projectFile.count({
where: {
projectId: state.projectId,
submissionWindowId: window.id,
},
})
const isIncomplete = uploadedFiles < requiredFileCount
if (!isIncomplete) continue
// Check if already sent this reminder
const existing = await prisma.reminderLog.findUnique({
where: {
roundId_userId_type: {
roundId: window.rounds[0].id,
userId: state.project.submittedByUserId,
type: reminderType,
},
},
})
if (existing) continue
try {
await sendNotificationEmail({
to: state.project.submittedBy.email,
name: state.project.submittedBy.name || '',
subject: `Reminder: Complete your submission for ${window.name}`,
template: 'submission-deadline-reminder',
variables: {
name: state.project.submittedBy.name,
competitionName: window.competition.name,
windowName: window.name,
projectTitle: state.project.title,
uploadedCount: uploadedFiles,
requiredCount: requiredFileCount,
deadline: window.windowCloseAt.toISOString(),
reminderType,
linkUrl: `${process.env.NEXTAUTH_URL}/applicant/submissions/${window.id}`,
},
priority: reminderType.includes('h') ? 'high' : 'normal',
})
// Log reminder
await prisma.reminderLog.create({
data: {
roundId: window.rounds[0].id,
userId: state.project.submittedByUserId,
type: reminderType,
},
})
sent++
} catch (error) {
console.error(
`Failed to send ${reminderType} reminder to ${state.project.submittedBy.email}:`,
error
)
errors++
}
}
return { sent, errors }
}
```
### Deduplication Strategy
**ReminderLog unique constraint:**
```prisma
model ReminderLog {
id String @id @default(cuid())
roundId String
userId String
type String // "7d", "3d", "1d", "24h", "3h", "1h"
sentAt DateTime @default(now())
@@unique([roundId, userId, type]) // Prevent duplicate reminders
@@index([roundId])
@@index([userId])
}
```
**Logic:**
1. Cron runs every 15 minutes
2. For each active round/window with deadline, calculate `msUntilDeadline`
3. Check if any reminder threshold matches (within 15-min window)
4. For each matching reminder type, query `ReminderLog` to see if already sent
5. Send only to users without existing log entry
6. Create `ReminderLog` entry after successful send
**Example timeline:**
```
Deadline: March 15, 2026 at 11:59 PM
Now: March 8, 2026 at 12:00 PM (7 days before)
Cron check at 12:00 PM:
- msUntilDeadline = 7 * 24 * 60 * 60 * 1000 = 604,800,000 ms
- Match "7d" reminder (within 15-min window)
- Query ReminderLog for (roundId, userId, type="7d")
- If not exists → send email + create log
- If exists → skip
Cron check at 12:15 PM:
- msUntilDeadline = 604,800,000 ms - 900,000 ms = slightly less
- No longer within 15-min window of "7d" threshold
- No reminders sent
Cron check at 3:00 PM (3 days before):
- msUntilDeadline = 3 * 24 * 60 * 60 * 1000
- Match "3d" reminder
- Send to users without "3d" log
```
---
## Admin Notification Controls
### Competition-Wide Settings UI
**ASCII mockup:**
```
┌─ Competition Settings: MOPC 2026 ─────────────────────────────────────┐
│ │
│ ┌─ Notification Preferences ──────────────────────────────────────┐ │
│ │ │ │
│ │ Global Toggles: │ │
│ │ [x] Notify on round advancement │ │
│ │ [x] Notify on deadline approaching │ │
│ │ [x] Notify on assignment created │ │
│ │ [x] Notify on submission received │ │
│ │ [x] Notify on filtering complete │ │
│ │ │ │
│ │ Reminder Schedule: │ │
│ │ Days before deadline: [7] [3] [1] [+ Add] │ │
│ │ Hours before deadline (final 48h): [24] [3] [1] [+ Add] │ │
│ │ │ │
│ │ Email Settings: │ │
│ │ From name: [MOPC 2026 Platform ] │ │
│ │ Reply-to: [admin@monaco-opc.com ] │ │
│ │ │ │
│ │ Advanced: │ │
│ │ [ ] Batch similar notifications (group within 30 min) │ │
│ │ Timezone: [UTC ▼] │ │
│ │ │ │
│ │ [Save Changes] [Reset to Defaults] │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Notification History ─────────────────────────────────────────┐ │
│ │ │ │
│ │ Last 24 hours: │ │
│ │ ✉ 156 emails sent │ │
│ │ 📱 243 in-app notifications created │ │
│ │ ⚠ 2 delivery failures │ │
│ │ │ │
│ │ [View Full Log] [Download Report] │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
### Per-Round Notification Overrides
**ASCII mockup:**
```
┌─ Round Settings: Jury 1 - Semi-finalist Selection ────────────────────┐
│ │
│ ┌─ Notification Overrides ────────────────────────────────────────┐ │
│ │ │ │
│ │ Inherit from competition: │ │
│ │ [x] Use competition reminder schedule │ │
│ │ [x] Use competition email templates │ │
│ │ │ │
│ │ Custom Reminder Schedule (overrides competition): │ │
│ │ [ ] Enable custom schedule │ │
│ │ Days before: [ ] [ ] [ ] │ │
│ │ Hours before: [ ] [ ] [ ] │ │
│ │ │ │
│ │ Email Templates: │ │
│ │ Round open: [Default Template ▼] │ │
│ │ Reminder: [Default Template ▼] │ │
│ │ Deadline passed:[Default Template ▼] │ │
│ │ │ │
│ │ Notification Toggles: │ │
│ │ [x] Notify jurors when round opens │ │
│ │ [x] Send deadline reminders │ │
│ │ [ ] Notify admins on each evaluation submission (high volume) │ │
│ │ │ │
│ │ [Save Overrides] [Clear All Overrides] │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
### Manual Notification Sending
**Broadcast notification UI:**
```
┌─ Send Manual Notification ──────────────────────────────────────────┐
│ │
│ Target Audience: │
│ ( ) All jury members in this competition │
│ ( ) All applicants with active projects │
│ ( ) Specific jury group: [Jury 1 ▼] │
│ ( ) Specific round participants: [Round 3 ▼] │
│ (•) Custom user list │
│ │
│ ┌─ Custom Users ───────────────────────────────────────────────┐ │
│ │ [Search users by name or email... ] [+ Add] │ │
│ │ │ │
│ │ Selected (3): │ │
│ │ • Dr. Alice Smith (alice@example.com) [Remove] │ │
│ │ • Prof. Bob Johnson (bob@example.com) [Remove] │ │
│ │ • Dr. Carol White (carol@example.com) [Remove] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ Subject: │
│ [Important: Competition Schedule Update ] │
│ │
│ Message: │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Dear {{name}}, │ │
│ │ │ │
│ │ Due to unforeseen circumstances, the evaluation deadline │ │
│ │ for Jury 1 has been extended to March 20, 2026. │ │
│ │ │ │
│ │ Please complete your evaluations by the new deadline. │ │
│ │ │ │
│ │ Best regards, │ │
│ │ MOPC Team │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Delivery: │
│ [x] Send email │
│ [x] Create in-app notification │
│ Priority: [Normal ▼] │
│ │
│ [Preview] [Send Now] [Schedule for Later] │
└───────────────────────────────────────────────────────────────────────┘
```
### Notification Log/History
**Admin notification log:**
```
┌─ Notification Log ─────────────────────────────────────────────────────┐
│ │
│ Filters: │
│ Date range: [Last 7 days ▼] Type: [All types ▼] │
│ Channel: [All ▼] Status: [All ▼] User: [ ] │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Timestamp │ Type │ User │ Ch.│ Status│ │
│ ├────────────────────────────────────────────────────────────────────┤ │
│ │ 2026-03-10 15:30 │ evaluation.deadline │ Dr. Smith │ ✉ │ ✓ Sent│ │
│ │ 2026-03-10 15:30 │ evaluation.deadline │ Prof. Lee │ ✉ │ ✓ Sent│ │
│ │ 2026-03-10 15:30 │ evaluation.deadline │ Dr. Garcia │ ✉ │ ✗ Fail│ │
│ │ 2026-03-10 14:00 │ filtering.completed │ Admin │ ✉📱│ ✓ Sent│ │
│ │ 2026-03-10 12:15 │ intake.submission │ Team Alpha │ ✉ │ ✓ Sent│ │
│ │ 2026-03-09 18:00 │ mentoring.message │ Team Beta │ 📱 │ ✓ Sent│ │
│ │ 2026-03-09 16:45 │ assignment.created │ Dr. Kim │ ✉📱│ ✓ Sent│ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Showing 7 of 482 notifications │
│ [Previous] [1] [2] [3] ... [69] [Next] │
│ │
│ [Export CSV] [Download Full Report] │
└──────────────────────────────────────────────────────────────────────────┘
```
---
## Template System
### Email Template Model
**Enhanced MessageTemplate model:**
```prisma
model MessageTemplate {
id String @id @default(cuid())
name String
category String // 'SYSTEM', 'EVALUATION', 'SUBMISSION', 'MENTORING', 'LIVE_FINAL'
eventType String? // Optional: link to specific event type
subject String
body String @db.Text // HTML template
variables Json? @db.JsonB // Available template variables
isActive Boolean @default(true)
isSystem Boolean @default(false) // System templates can't be deleted
createdBy String
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
creator User @relation("MessageTemplateCreator", fields: [createdBy], references: [id])
messages Message[]
@@index([category])
@@index([isActive])
@@index([eventType])
}
```
### Template Variables
**Standard variables available in all templates:**
```typescript
export const STANDARD_VARIABLES = {
// User variables
name: 'Recipient name',
email: 'Recipient email',
role: 'User role',
// Competition variables
competitionName: 'Competition name',
competitionYear: 'Competition year',
// Round variables
roundName: 'Round name',
roundType: 'Round type',
deadline: 'Deadline (formatted)',
windowOpenAt: 'Window open date',
windowCloseAt: 'Window close date',
// Link variables
linkUrl: 'Call-to-action link',
baseUrl: 'Platform base URL',
// Meta
currentDate: 'Current date',
timestamp: 'Current timestamp',
}
```
**Event-specific variables:**
```typescript
// evaluation.deadline_approaching
export const EVALUATION_DEADLINE_VARIABLES = {
...STANDARD_VARIABLES,
incompleteCount: 'Number of incomplete evaluations',
totalCount: 'Total assigned evaluations',
daysRemaining: 'Days until deadline',
hoursRemaining: 'Hours until deadline',
reminderType: 'Reminder type (7d, 3d, 1d, etc.)',
}
// intake.submission_received
export const SUBMISSION_RECEIVED_VARIABLES = {
...STANDARD_VARIABLES,
projectTitle: 'Project title',
projectId: 'Project ID',
fileCount: 'Number of files uploaded',
requiredFileCount: 'Number of required files',
isComplete: 'Whether submission is complete',
}
// mentoring.file_uploaded
export const MENTOR_FILE_VARIABLES = {
...STANDARD_VARIABLES,
fileName: 'Uploaded file name',
uploadedByName: 'Name of uploader',
uploadedByRole: 'Role of uploader (MENTOR or APPLICANT)',
projectTitle: 'Project title',
}
```
### Template Editor UI
**ASCII mockup:**
```
┌─ Email Template Editor ────────────────────────────────────────────────┐
│ │
│ Template Name: [Evaluation Deadline Reminder ] │
│ Category: [Evaluation ▼] │
│ Event Type: [evaluation.deadline_approaching ▼] │
│ │
│ Subject: │
│ [Reminder: {{incompleteCount}} pending evaluation(s) ] │
│ │
│ ┌─ Available Variables ──────────────────────────────────────────────┐ │
│ │ Click to insert: │ │
│ │ {{name}} {{competitionName}} {{roundName}} {{deadline}} │ │
│ │ {{incompleteCount}} {{totalCount}} {{linkUrl}} [View all...] │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Body (HTML): │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ <!DOCTYPE html> │ │
│ │ <html> │ │
│ │ <head> │ │
│ │ <style> │ │
│ │ .header { background: #053d57; color: white; padding: 20px; }│ │
│ │ .content { padding: 20px; } │ │
│ │ .cta { background: #de0f1e; color: white; ... } │ │
│ │ </style> │ │
│ │ </head> │ │
│ │ <body> │ │
│ │ <div class="header"> │ │
│ │ <h1>{{competitionName}}</h1> │ │
│ │ </div> │ │
│ │ <div class="content"> │ │
│ │ <p>Dear {{name}},</p> │ │
│ │ <p>You have <strong>{{incompleteCount}}</strong> pending ... │ │
│ │ ... │ │
│ │ [40 more lines] │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ Preview with sample data: [Generate Preview] │
│ │
│ [Save Draft] [Save & Activate] [Send Test Email] [Cancel] │
└──────────────────────────────────────────────────────────────────────────┘
```
### Template Validation
**Zod schema for template validation:**
```typescript
import { z } from 'zod'
export const TemplateVariableSchema = z.object({
key: z.string(),
label: z.string(),
type: z.enum(['string', 'number', 'date', 'boolean', 'url']),
required: z.boolean().default(false),
description: z.string().optional(),
})
export const MessageTemplateSchema = z.object({
name: z.string().min(1, 'Name is required'),
category: z.enum(['SYSTEM', 'EVALUATION', 'SUBMISSION', 'MENTORING', 'LIVE_FINAL']),
eventType: z.string().optional(),
subject: z.string().min(1, 'Subject is required'),
body: z.string().min(1, 'Body is required'),
variables: z.array(TemplateVariableSchema).optional(),
isActive: z.boolean().default(true),
})
export type TemplateVariable = z.infer<typeof TemplateVariableSchema>
export type MessageTemplateInput = z.infer<typeof MessageTemplateSchema>
```
**Template validation function:**
```typescript
export function validateTemplate(
template: string,
variables: Record<string, unknown>
): { valid: boolean; errors: string[] } {
const errors: string[] = []
// Extract all {{variable}} references
const variableRefs = template.match(/\{\{(\w+)\}\}/g) || []
for (const ref of variableRefs) {
const varName = ref.replace(/\{\{|\}\}/g, '')
if (!(varName in variables)) {
errors.push(`Unknown variable: ${varName}`)
}
}
// Check for malformed syntax
const malformed = template.match(/\{[^{]|\}[^}]/g)
if (malformed) {
errors.push('Malformed variable syntax detected')
}
return {
valid: errors.length === 0,
errors,
}
}
```
---
## API Changes (tRPC)
### Notification Router
**Complete notification router:**
```typescript
// src/server/routers/notification.ts
import { z } from 'zod'
import { router, protectedProcedure, adminProcedure } from '../trpc'
import { logAudit } from '../utils/audit'
export const notificationRouter = router({
/**
* Get unread count for current user
*/
getUnreadCount: protectedProcedure.query(async ({ ctx }) => {
return ctx.prisma.inAppNotification.count({
where: {
userId: ctx.user.id,
isRead: false,
},
})
}),
/**
* Get recent notifications
*/
getRecent: protectedProcedure
.input(z.object({ limit: z.number().default(10) }))
.query(async ({ ctx, input }) => {
return ctx.prisma.inAppNotification.findMany({
where: { userId: ctx.user.id },
orderBy: { createdAt: 'desc' },
take: input.limit,
})
}),
/**
* Get all notifications with filtering
*/
getAll: protectedProcedure
.input(
z.object({
filter: z.enum(['all', 'unread']).default('all'),
limit: z.number().default(100),
offset: z.number().default(0),
})
)
.query(async ({ ctx, input }) => {
return ctx.prisma.inAppNotification.findMany({
where: {
userId: ctx.user.id,
...(input.filter === 'unread' && { isRead: false }),
},
orderBy: { createdAt: 'desc' },
take: input.limit,
skip: input.offset,
})
}),
/**
* Mark notification as read
*/
markRead: protectedProcedure
.input(z.object({ id: z.string() }))
.mutation(async ({ ctx, input }) => {
return ctx.prisma.inAppNotification.update({
where: { id: input.id, userId: ctx.user.id },
data: { isRead: true, readAt: new Date() },
})
}),
/**
* Mark all notifications as read
*/
markAllRead: protectedProcedure.mutation(async ({ ctx }) => {
return ctx.prisma.inAppNotification.updateMany({
where: { userId: ctx.user.id, isRead: false },
data: { isRead: true, readAt: new Date() },
})
}),
/**
* Delete notification
*/
delete: protectedProcedure
.input(z.object({ id: z.string() }))
.mutation(async ({ ctx, input }) => {
return ctx.prisma.inAppNotification.delete({
where: { id: input.id, userId: ctx.user.id },
})
}),
/**
* Get notification policies (admin)
*/
listPolicies: adminProcedure.query(async ({ ctx }) => {
return ctx.prisma.notificationPolicy.findMany({
orderBy: { eventType: 'asc' },
})
}),
/**
* Update notification policy (admin)
*/
updatePolicy: adminProcedure
.input(
z.object({
id: z.string(),
channel: z.enum(['EMAIL', 'IN_APP', 'BOTH', 'NONE']).optional(),
isActive: z.boolean().optional(),
templateId: z.string().optional(),
configJson: z.record(z.unknown()).optional(),
})
)
.mutation(async ({ ctx, input }) => {
const { id, ...data } = input
const policy = await ctx.prisma.notificationPolicy.update({
where: { id },
data,
})
await logAudit({
prisma: ctx.prisma,
userId: ctx.user.id,
action: 'UPDATE_NOTIFICATION_POLICY',
entityType: 'NotificationPolicy',
entityId: id,
detailsJson: data,
ipAddress: ctx.ip,
userAgent: ctx.userAgent,
})
return policy
}),
/**
* Send manual notification (admin)
*/
sendManual: adminProcedure
.input(
z.object({
userIds: z.array(z.string()),
subject: z.string(),
message: z.string(),
linkUrl: z.string().optional(),
priority: z.enum(['low', 'normal', 'high', 'urgent']).default('normal'),
channels: z.array(z.enum(['EMAIL', 'IN_APP'])),
})
)
.mutation(async ({ ctx, input }) => {
const { userIds, channels, ...notificationData } = input
// Create in-app notifications
if (channels.includes('IN_APP')) {
await ctx.prisma.inAppNotification.createMany({
data: userIds.map((userId) => ({
userId,
type: 'admin.manual_broadcast',
title: notificationData.subject,
message: notificationData.message,
linkUrl: notificationData.linkUrl,
priority: notificationData.priority,
icon: 'Bell',
})),
})
}
// Send emails
if (channels.includes('EMAIL')) {
const users = await ctx.prisma.user.findMany({
where: { id: { in: userIds } },
select: { id: true, email: true, name: true },
})
const { sendNotificationEmail } = await import('@/lib/email')
for (const user of users) {
try {
await sendNotificationEmail({
to: user.email,
name: user.name || '',
subject: notificationData.subject,
template: 'admin-manual-notification',
variables: {
name: user.name,
message: notificationData.message,
linkUrl: notificationData.linkUrl,
},
priority: notificationData.priority,
})
} catch (error) {
console.error(`Failed to send email to ${user.email}:`, error)
}
}
}
// Audit log
await logAudit({
prisma: ctx.prisma,
userId: ctx.user.id,
action: 'SEND_MANUAL_NOTIFICATION',
entityType: 'InAppNotification',
detailsJson: {
recipientCount: userIds.length,
channels,
subject: notificationData.subject,
},
ipAddress: ctx.ip,
userAgent: ctx.userAgent,
})
return { sent: userIds.length }
}),
/**
* Get notification log (admin)
*/
getLog: adminProcedure
.input(
z.object({
startDate: z.date().optional(),
endDate: z.date().optional(),
channel: z.enum(['EMAIL', 'IN_APP', 'ALL']).default('ALL'),
status: z.enum(['SENT', 'FAILED', 'ALL']).default('ALL'),
limit: z.number().default(100),
offset: z.number().default(0),
})
)
.query(async ({ ctx, input }) => {
return ctx.prisma.notificationLog.findMany({
where: {
...(input.startDate && { createdAt: { gte: input.startDate } }),
...(input.endDate && { createdAt: { lte: input.endDate } }),
...(input.channel !== 'ALL' && { channel: input.channel }),
...(input.status !== 'ALL' && { status: input.status }),
},
include: {
user: { select: { id: true, name: true, email: true } },
},
orderBy: { createdAt: 'desc' },
take: input.limit,
skip: input.offset,
})
}),
})
```
### Deadline Router
**Deadline management router:**
```typescript
// src/server/routers/deadline.ts
import { z } from 'zod'
import { router, adminProcedure } from '../trpc'
import { logAudit } from '../utils/audit'
import { emitRoundEvent } from '../services/round-notifications'
export const deadlineRouter = router({
/**
* Extend round deadline (affects all participants)
*/
extendRound: adminProcedure
.input(
z.object({
roundId: z.string(),
newWindowCloseAt: z.date(),
reason: z.string(),
notifyParticipants: z.boolean().default(true),
})
)
.mutation(async ({ ctx, input }) => {
const round = await ctx.prisma.round.update({
where: { id: input.roundId },
data: { windowCloseAt: input.newWindowCloseAt },
include: {
competition: true,
juryGroup: { include: { members: true } },
},
})
// Create override action
await ctx.prisma.overrideAction.create({
data: {
entityType: 'Round',
entityId: input.roundId,
previousValue: { windowCloseAt: round.windowCloseAt },
newValueJson: { windowCloseAt: input.newWindowCloseAt },
reasonCode: 'ADMIN_DISCRETION',
reasonText: input.reason,
actorId: ctx.user.id,
},
})
// Emit event
await emitRoundEvent(
'admin.deadline_extended',
'Round',
input.roundId,
ctx.user.id,
{
roundId: input.roundId,
previousDeadline: round.windowCloseAt,
newDeadline: input.newWindowCloseAt,
reason: input.reason,
},
ctx.prisma
)
// Notify participants if requested
if (input.notifyParticipants) {
// Get affected users (jury members for this round)
const affectedUserIds = round.juryGroup?.members.map((m) => m.userId) || []
if (affectedUserIds.length > 0) {
await ctx.prisma.inAppNotification.createMany({
data: affectedUserIds.map((userId) => ({
userId,
type: 'admin.deadline_extended',
title: 'Deadline Extended',
message: `The deadline for ${round.name} has been extended to ${input.newWindowCloseAt.toLocaleString()}. Reason: ${input.reason}`,
linkUrl: `/jury/rounds/${input.roundId}`,
priority: 'high',
icon: 'Clock',
})),
})
}
}
// Audit log
await logAudit({
prisma: ctx.prisma,
userId: ctx.user.id,
action: 'EXTEND_ROUND_DEADLINE',
entityType: 'Round',
entityId: input.roundId,
detailsJson: {
previousDeadline: round.windowCloseAt?.toISOString(),
newDeadline: input.newWindowCloseAt.toISOString(),
reason: input.reason,
notified: input.notifyParticipants,
},
ipAddress: ctx.ip,
userAgent: ctx.userAgent,
})
return round
}),
/**
* Extend submission window deadline
*/
extendSubmissionWindow: adminProcedure
.input(
z.object({
windowId: z.string(),
newWindowCloseAt: z.date(),
reason: z.string(),
notifyApplicants: z.boolean().default(true),
})
)
.mutation(async ({ ctx, input }) => {
const window = await ctx.prisma.submissionWindow.update({
where: { id: input.windowId },
data: { windowCloseAt: input.newWindowCloseAt },
include: {
competition: true,
rounds: {
include: {
projectRoundStates: {
include: {
project: {
include: { submittedBy: true },
},
},
},
},
},
},
})
// Notify affected applicants
if (input.notifyApplicants) {
const affectedUserIds = new Set<string>()
for (const round of window.rounds) {
for (const state of round.projectRoundStates) {
if (state.project.submittedByUserId) {
affectedUserIds.add(state.project.submittedByUserId)
}
}
}
if (affectedUserIds.size > 0) {
await ctx.prisma.inAppNotification.createMany({
data: Array.from(affectedUserIds).map((userId) => ({
userId,
type: 'admin.deadline_extended',
title: 'Submission Deadline Extended',
message: `The submission deadline for ${window.name} has been extended to ${input.newWindowCloseAt.toLocaleString()}. Reason: ${input.reason}`,
linkUrl: `/applicant/submissions/${input.windowId}`,
priority: 'high',
icon: 'Clock',
})),
})
}
}
// Audit log
await logAudit({
prisma: ctx.prisma,
userId: ctx.user.id,
action: 'EXTEND_SUBMISSION_DEADLINE',
entityType: 'SubmissionWindow',
entityId: input.windowId,
detailsJson: {
previousDeadline: window.windowCloseAt?.toISOString(),
newDeadline: input.newWindowCloseAt.toISOString(),
reason: input.reason,
},
ipAddress: ctx.ip,
userAgent: ctx.userAgent,
})
return window
}),
})
```
---
## Service Functions
### Round Notifications Service
**Complete service interface:**
```typescript
// src/server/services/round-notifications.ts
import type { PrismaClient } from '@prisma/client'
/**
* Emit a round event with notification support.
*/
export async function emitRoundEvent(
eventType: string,
entityType: string,
entityId: string,
actorId: string,
details: Record<string, unknown>,
prisma: PrismaClient
): Promise<void>
/**
* Convenience producers for common events.
*/
export async function onRoundOpened(
roundId: string,
actorId: string,
prisma: PrismaClient
): Promise<void>
export async function onRoundClosed(
roundId: string,
actorId: string,
prisma: PrismaClient
): Promise<void>
export async function onSubmissionReceived(
projectId: string,
submissionWindowId: string,
submittedByUserId: string,
fileCount: number,
isComplete: boolean,
prisma: PrismaClient
): Promise<void>
export async function onFilteringCompleted(
jobId: string,
roundId: string,
total: number,
passed: number,
rejected: number,
flagged: number,
actorId: string,
prisma: PrismaClient
): Promise<void>
export async function onAssignmentCreated(
assignmentId: string,
roundId: string,
projectId: string,
userId: string,
actorId: string,
prisma: PrismaClient
): Promise<void>
export async function onMentorFileUploaded(
fileId: string,
mentorAssignmentId: string,
uploadedByUserId: string,
prisma: PrismaClient
): Promise<void>
export async function onWinnerApprovalRequired(
proposalId: string,
category: string,
requiredApprovers: Array<{ userId: string; role: string }>,
actorId: string,
prisma: PrismaClient
): Promise<void>
export async function onResultsFrozen(
proposalId: string,
category: string,
frozenByUserId: string,
prisma: PrismaClient
): Promise<void>
```
### Deadline Reminder Service
**Service interface:**
```typescript
// src/server/services/deadline-reminders.ts
export interface ReminderResult {
sent: number
errors: number
}
/**
* Process all deadline reminders (called by cron).
*/
export async function processDeadlineReminders(): Promise<ReminderResult>
/**
* Process evaluation round reminders.
*/
export async function processEvaluationReminders(
now: Date
): Promise<ReminderResult>
/**
* Process submission window reminders.
*/
export async function processSubmissionReminders(
now: Date
): Promise<ReminderResult>
/**
* Send reminders for a specific round.
*/
export async function sendEvaluationReminders(
round: any,
reminderType: string,
now: Date
): Promise<ReminderResult>
/**
* Send reminders for a specific submission window.
*/
export async function sendSubmissionReminders(
window: any,
reminderType: string,
now: Date
): Promise<ReminderResult>
/**
* Determine which reminder types should fire.
*/
export function getReminderTypesForDeadline(
msUntilDeadline: number,
reminderDays: number[],
reminderHours: number[]
): string[]
```
---
## Edge Cases
| Edge Case | Scenario | Handling |
|-----------|----------|----------|
| **Midnight deadline** | Round closes at 23:59:59, cron runs at 00:00 | Grace period calculations account for timezone. Use `<=` comparison for windowCloseAt. |
| **Clock drift** | Client clock is 5 minutes fast | Server-side time sync via `trpc.time.getServerTime()`. Countdown uses synced time. |
| **Duplicate reminders** | Cron runs twice (overlapping) | `ReminderLog` unique constraint prevents duplicates. Idempotent reminder sending. |
| **Grace period overlap** | User has grace period + round is extended | Use whichever deadline is later: `max(userGrace, round.windowCloseAt)`. |
| **Notification flood** | 100 users receive reminder at once | Batch email sending (max 50/min). Use queue for large batches. |
| **Timezone confusion** | User in PST, server in UTC | All deadlines stored in UTC. Display in user's timezone (future enhancement). |
| **Email delivery failure** | SMTP server down | Retry 3 times with exponential backoff. Log failure in `NotificationLog`. In-app notification still created. |
| **Cron secret leak** | CRON_SECRET exposed | Rotate immediately. Use header validation. Log all cron requests. |
| **Reminder after deadline** | Cron delayed, now > deadline | Skip reminder. No reminders sent after deadline passes. |
| **User opts out of emails** | User sets `notificationPreference: NONE` | Respect preference. Still create in-app notifications. |
| **Template variable missing** | Template uses {{foo}} but data has no foo | Replace with empty string. Log warning. Don't fail email send. |
| **Round extended mid-reminder** | Deadline extended after 3d reminder sent | 1d reminder will still fire (based on new deadline). No duplicate 3d reminder. |
| **Bulk notification failure** | 1 out of 50 emails fails | Log failure, continue with remaining. Return `{ sent: 49, errors: 1 }`. |
---
## Integration Points
### How Notifications Connect to Every Round Type
**INTAKE Round:**
- `intake.window_opened` → Triggered when round status changes to ACTIVE
- `intake.submission_received` → Triggered by `ProjectFile.create()` via `trpc.application.uploadFile`
- `intake.deadline_approaching` → Triggered by cron checking `SubmissionWindow.windowCloseAt`
- Email sent to: All applicants (window opened), team lead (submission received), incomplete applicants (deadline reminder)
**FILTERING Round:**
- `filtering.started` → Triggered by `trpc.filtering.runStageFiltering` creating `FilteringJob`
- `filtering.completed` → Triggered when `FilteringJob.status → COMPLETED`
- `filtering.project_advanced` → Triggered when `ProjectRoundState.state → PASSED`
- `filtering.project_rejected` → Triggered when `ProjectRoundState.state → REJECTED`
- Email sent to: Admins (started/completed), team lead (advanced/rejected)
**EVALUATION Round:**
- `evaluation.assignment_created` → Triggered by `trpc.assignment.create` or AI assignment
- `evaluation.deadline_approaching` → Triggered by cron checking `Round.windowCloseAt`
- `evaluation.submitted` → Triggered when `Evaluation.status → SUBMITTED`
- `evaluation.round_complete` → Triggered when all assignments completed
- Email sent to: Assigned juror (created, deadline), admins (round complete)
**SUBMISSION Round:**
- `submission.window_opened` → Triggered when SubmissionWindow opens + round ACTIVE
- `submission.new_docs_required` → Triggered when eligible projects enter round
- `submission.docs_submitted` → Triggered by `ProjectFile.create()` for window
- `submission.deadline_approaching` → Triggered by cron
- Email sent to: Eligible teams (window opened, new docs), team lead (submitted, deadline)
**MENTORING Round:**
- `mentoring.assigned` → Triggered by `MentorAssignment.create()`
- `mentoring.workspace_opened` → Triggered when round ACTIVE
- `mentoring.message_received` → Triggered by `MentorMessage.create()`
- `mentoring.file_uploaded` → Triggered by `MentorFile.create()`
- `mentoring.file_promoted` → Triggered when `MentorFile.isPromoted → true`
- Email sent to: Mentor + team (assigned, workspace), recipient (message), other party (file)
**LIVE_FINAL Round:**
- `live_final.ceremony_starting` → Triggered when `LiveVotingSession.status → IN_PROGRESS`
- `live_final.vote_required` → Triggered when `LiveProgressCursor` updated
- `live_final.deliberation_started` → Triggered when deliberation period begins
- `live_final.results_ready` → Triggered when all votes cast
- Email sent to: Jury + audience (ceremony starting), jury (vote required), admins (results ready)
- In-app only: Real-time vote required notifications
**CONFIRMATION Round:**
- `confirmation.approval_required` → Triggered by `WinnerProposal.create()`
- `confirmation.approval_received` → Triggered when `WinnerApproval.approved → true`
- `confirmation.approved` → Triggered when all approvals received
- `confirmation.frozen` → Triggered when `WinnerProposal.frozenAt` set
- Email sent to: Jury + admins (approval required), admins + jury (approved, frozen)
### Cross-Round Notification Scenarios
**Scenario 1: Project advances from Filtering to Evaluation**
1. `FilteringJob` completes → `filtering.completed` (admin email)
2. Admin reviews flagged projects → Manual override
3. `ProjectRoundState.state → PASSED` → `filtering.project_advanced` (team email)
4. Admin clicks "Advance to Evaluation" → Projects moved to Evaluation round
5. `Round.status → ACTIVE` for Evaluation round → `round.opened` (admin in-app)
6. AI assignment runs → Creates assignments
7. `Assignment.create()` → `evaluation.assignment_created` (each juror email)
**Scenario 2: Deadline approaching with grace periods**
1. Cron runs 3 days before deadline
2. Finds 5 jurors with incomplete evaluations
3. Checks `ReminderLog` — 2 already received "3d" reminder
4. Checks `GracePeriod` — 1 juror has extended deadline (no reminder)
5. Sends "3d" reminder to 2 jurors
6. Creates `ReminderLog` entries for those 2
7. Emits `evaluation.deadline_approaching` event
8. Creates in-app notifications for all 5 jurors (including grace period)
**Scenario 3: Round deadline extended mid-cycle**
1. Admin extends deadline from March 15 to March 20
2. `Round.windowCloseAt` updated
3. `admin.deadline_extended` event emitted
4. In-app + email notifications sent to all assigned jurors
5. Existing `ReminderLog` entries remain (prevent duplicate "7d", "3d")
6. New reminders fire based on new deadline:
- If extension happens after "3d" reminder: "1d" and "24h" reminders still fire
- If extension happens before "3d" reminder: All reminders fire normally
---
## Summary
This Notifications & Deadlines system provides:
1. **Event-driven architecture** — All significant round events trigger notifications
2. **Multi-channel delivery** — Email, in-app, and future webhook support
3. **Flexible deadline policies** — HARD, FLAG, GRACE modes per window/round
4. **Automated reminders** — Configurable intervals (days and hours) before deadlines
5. **Grace period management** — Individual and bulk extensions with audit trail
6. **Real-time countdowns** — Client-side timers with server time sync
7. **Admin controls** — Competition-wide and per-round configuration
8. **Template system** — Reusable email templates with variable substitution
9. **Deduplication** — Unique constraints prevent duplicate reminders
10. **Integration** — Deep connections to all round types and pipeline events
This system ensures participants are always informed, deadlines are clear, and admins have full control over notification behavior across the entire competition lifecycle.
Reference in New Issue View Git Blame Copy Permalink