[Backend] Build Production-Grade Judging System (Judge Auth, Scoring, Locking, Leaderboard, Audit Trail)

[abhishek-nexgen-dev]

We are building a complete judging system for events like:

hackathons
competitions
startup demos
technical challenges

---

Core Flow

Judge invited
→ accepts invite
→ logs in
→ sees assigned submissions
→ scores criteria
→ submits score
→ score locked
→ leaderboard updated
→ (optional) public visibility

---

🎯 Goals

System must be:

• Secure (only assigned judges can score)
• Fair (criteria-based scoring)
• Immutable (no tampering after submit)
• Auditable (every action logged)
• Scalable (1000+ submissions)
• Transparent (optional public view)

---

🧱 CORE MODULES

---

1️⃣ JUDGE AUTH & INVITATION SYSTEM

---

Endpoints

POST /api/v1/judge/auth/accept-invite
POST /api/v1/judge/auth/login
POST /api/v1/judge/auth/refresh
POST /api/v1/judge/auth/logout

---

Flow

Organizer invites judge
→ token generated
→ email sent
→ judge accepts
→ account linked
→ login enabled

---

Security

• JWT + refresh token
• login rate limiting
• optional MFA
• session tracking

---

---

2️⃣ JUDGE ASSIGNMENT SYSTEM

---

Purpose

Assign judges to events and submissions

---

Rules

one judge per submission (unique)
judge must be active
judge cannot score unassigned submission

---

Assignment Types

Manual
RoundRobin
CategoryBased

---

---

3️⃣ CRITERIA SYSTEM

---

Endpoint

POST /api/v1/events/:eventId/criteria
GET /api/v1/events/:eventId/criteria
PATCH /api/v1/events/:eventId/criteria/:id
DELETE /api/v1/events/:eventId/criteria/:id

---

Rules

maxScore > 0
weight > 0
total weight = 100

---

---

4️⃣ SCORING SYSTEM

---

Endpoints

POST /api/v1/judge/events/:eventId/submissions/:id/scores/draft
POST /api/v1/judge/events/:eventId/submissions/:id/scores/submit

---

Flow

judge selects submission
→ fills criteria scores
→ saves draft
→ submits final score
→ score locked

---

Validation

score <= maxScore
all required criteria filled
judge assigned
no conflict of interest

---

---

5️⃣ SCORE LIFECYCLE & LOCKING 🔐

---

Lifecycle

Draft → Submitted → Finalized

---

Rules

• Draft → editable
• Submitted → locked
• Finalized → immutable

---

Unlock (Critical)

only LeadJudge/Admin
must provide reason
increment scoreVersion
log audit

---

---

6️⃣ LEADERBOARD SYSTEM

---

Calculation

weightedScore = (score / maxScore) * weight
finalScore = average(weightedScore)

---

Sorting

1. weightedAverageScore
2. averageScore
3. highestSingleScore
4. earliestSubmission

---

Endpoint

GET /api/v1/events/:eventId/leaderboard

---

---

7️⃣ JUDGING ROUND SYSTEM

---

Endpoints

POST /api/v1/events/:eventId/judging/rounds
PATCH /api/v1/events/:eventId/judging/rounds/:id
POST /api/v1/events/:eventId/judging/rounds/:id/finalize

---

Features

• multiple rounds
• scoring deadlines
• round finalization

---

Rules

no scoring after deadline
no scoring after finalization

---

---

8️⃣ CONFLICT OF INTEREST SYSTEM

---

Endpoint

POST /api/v1/judge/events/:eventId/conflicts

---

Rules

judge cannot score own project
must declare conflict
block scoring if conflict exists

---

---

9️⃣ AUDIT LOG SYSTEM (CRITICAL)

---

Track Everything

invite_sent
judge_login
score_draft_saved
score_submitted
score_unlocked
score_finalized
round_finalized

---

Required Fields

• actorUserId
• action
• timestamp
• IP
• userAgent

---

---

🔟 TRANSPARENCY SYSTEM

---

Modes

Private
Transparent

---

Controls

showJudgeNames
showCriteria
showFeedback
publishTiming

---

---

1️⃣1️⃣ SECURITY 🔐

---

Critical Protections

score locking
duplicate prevention
RBAC enforcement
conflict-of-interest blocking

---

Additional

• blinded judging
• anomaly detection (optional)
• rate limiting

---

---

1️⃣2️⃣ DATABASE DESIGN

---

Collections

EventJudgeAssignment
EventJudgingCriteria
EventSubmission
SubmissionScore
JudgingAudit
JudgingRound
JudgeSubmissionAssignment
JudgeConflictOfInterest

---

Indexes

(eventId, judgeId)
(eventId, submissionId)
unique score per judge

---

---

1️⃣3️⃣ NOTIFICATION SYSTEM

---

Triggers

judge invited
invite accepted
round started
deadline reminder
score submitted
round finalized
leaderboard published

---

---

1️⃣4️⃣ ERROR HANDLING

---

Format

{
  "status": 403,
  "code": "SCORE_LOCKED",
  "message": "Score cannot be edited"
}

---

---

1️⃣5️⃣ TESTING

---

Unit

• scoring logic
• validation

---

Integration

• full judging flow
• leaderboard calculation

---

Security

• unauthorized scoring
• score tampering

---

---

1️⃣6️⃣ EDGE CASES

---

duplicate scoring
judge removed mid-round
conflict declared late
deadline passed
round finalized early

---

---

⚙️ PERFORMANCE

---

• indexed queries
• leaderboard caching
• batch score calculation

---

---

🌍 ENVIRONMENT

---

DEV
STAGING
PROD

---

---

📦 ARCHITECTURE

---

/controllers
/services
/models
/validators
/middlewares
/audit

---

---

✅ ACCEPTANCE CRITERIA

---

✔ Judge invite system works
✔ Judge login works
✔ Assignment system works
✔ Criteria system works
✔ Scoring works
✔ Score locking works
✔ Leaderboard works
✔ Conflict system works
✔ Audit logs working
✔ Round system works
✔ Fully secure & tested

---

🔥 FINAL SUMMARY

This system behaves like:

Devfolio / Hackathon judging / YC Demo Day scoring system