Nibras Student Dashboard - Competitions Service

Backend service for contest discovery, bookmarking/reminders, competitive account linking, profile sync, and problem progress tracking.

Current Scope

• Primary user flow scope: Codeforces + LeetCode
• Internal implementation also contains additional platform paths in some services/validators
• Full endpoint contract is documented in API_DOCUMENTATION.md

Core Features

• Contest ingestion & updates
  • Scheduled contest sync
  • Manual admin sync
  • Contest status transitions (upcoming -> running -> finished)
• User contest actions
  • Bookmark contests
  • Set/remove reminders
  • Join contests and view participation history
• Competitive account integration
  • Link external accounts
  • Start/check account verification
  • View aggregated profile
  • Trigger manual profile sync
• Problem tracking
  • Internal problem catalog
  • Per-user solved state
  • Progress aggregation by difficulty/platform
  • Solved state is updated via sync flow
• Background jobs
  • Contest sync
  • Contest status update
  • Reminder notifications
  • Competitive profile auto-sync
  • Verification revalidation

Tech Stack

• Runtime: Node.js (CommonJS)
• Framework: Express
• Database: MongoDB + Mongoose
• Scheduling: node-cron
• Auth: JWT
• Validation: express-validator
• Email: nodemailer
• Caching/locks/rate keys: Redis (optional but required for manual profile sync path)

Prerequisites

• Node.js 14+
• MongoDB (local or cloud)
• SMTP credentials (for reminder emails)
• (Recommended) Redis instance for profile sync lock/rate-limit/cache behavior

Installation

cd D:\Projects\Nibras\nibras-student-dashboard\competitions
npm install

Environment Configuration

Create/update .env with at least:

# Server
PORT=5000
NODE_ENV=development

# Database
MONGODB_URL=mongodb+srv://<your-connection-string>

# Auth
JWT_SECRET=<strong-secret>
JWT_EXPIRE=1h

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=<smtp-user>
SMTP_PASS=<smtp-password>
EMAIL_FROM=noreply@nibras.com

# Redis (recommended; required for manual profile sync path)
REDIS_URL=redis://localhost:6379

# Contest jobs
CONTEST_SYNC_CRON=0 */6 * * *
STATUS_UPDATE_CRON=*/5 * * * *
REMINDER_CHECK_CRON=*/5 * * * *
REMINDER_TIME_BEFORE=15

# Profile jobs
PROFILE_SYNC_CRON=0 */6 * * *
ACCOUNT_REVALIDATION_CRON=0 2 * * *

Additional optional profile-sync tuning variables are used in competitiveProfile.service.js (cooldown, lock TTL, retry window, etc.).

Run

# Development
npm run st

# Production
npm start

API Overview

Auth

• POST /auth/register
• POST /auth/login
• GET /auth/me

Contests

• GET /contests
• GET /contests/:id
• POST /contests/sync (admin)
• POST /contests/update-statuses (admin)

User Contest Actions

• POST /user/contests/:id/bookmark
• DELETE /user/contests/:id/bookmark
• GET /user/contests/bookmarks
• POST /user/contests/:id/reminder
• DELETE /user/contests/:id/reminder
• GET /user/contests/reminders
• POST /user/contests/:id/join
• GET /user/contests/history (alias also available at /user-contests/history)

Account Linking / Verification / Sync

• POST /accounts/link
• POST /accounts/verify/start
• POST /accounts/verify/check
• GET /accounts/profile/:userId
• POST /accounts/profile/sync

Problems & Progress

• GET /problems
• GET /problems/roadmap
• GET /problems/progress
• PATCH /problems/:id/solved (disabled by design; sync-driven)
• POST /problems (admin)
• PATCH /problems/:id (admin)
• DELETE /problems/:id (admin)

For request/response examples, headers, query/body definitions, and error cases, use:

• API_DOCUMENTATION.md

Scheduled Jobs

1. Contest Sync Job (jobs-contestSync.job.js)
   • Default: every 6 hours
   • Fetches and stores/updates contests
2. Contest Status Update Job (jobs-contestStatusUpdate.job.js)
   • Default: every 5 minutes
   • Moves contests across lifecycle statuses
3. Reminder Notification Job (jobs-reminderNotification.job.js)
   • Default: every 5 minutes
   • Sends reminder emails before contest start
4. Competitive Profile Sync Job (jobs-competitiveProfileSync.job.js)
   • Default: every 6 hours
   • Refreshes due competitive profiles
5. Verification Revalidation Job (jobs-verificationRevalidation.job.js)
   • Default: daily at 02:00
   • Expires verification states requiring revalidation

Project Structure (High Level)

src/
  app.js
  server.js
  config/
  constants/
  controllers/
  jobs/
  middlewares/
  model/
  repositories/
  routes/
  services/
  utils/
  validators/

Troubleshooting

• Manual profile sync returns 503: check REDIS_URL and Redis connectivity.
• Reminders not sent: verify SMTP credentials and EMAIL_FROM.
• No contests syncing: verify upstream API access and sync job schedule/env values.
• Auth failures: verify JWT_SECRET consistency across environments.

License

ISC