CDeX

A production-grade, microservices platform for competitive programming, contests, and assignments — built as a NestJS monorepo with gRPC services, Kafka event streaming, and real-time WebSockets. Students submit code, Judge0 executes it in a sandbox, and live leaderboards stream to every participant.

NestJS monorepo · 11 microservices · gRPC + Protobuf · Kafka (53 topics) · multi-database

Architecture · Microservices · Tech Stack · Getting Started

---

Overview

CDeX is a complete backend platform for running coding problems, code submissions, contests, and assignments at scale. It is built with NestJS and a monorepo (Nx + Turborepo + pnpm) architecture, with 9 gRPC microservices behind a REST API gateway, an auth edge, a dedicated WebSocket gateway, and a Judge0 integration adapter.

The platform manages:

• Coding Problems — programming challenges with versioned test cases
• Code Submissions — judged in multiple languages (C++, Python, Java, …)
• Contests — competitive events with real-time leaderboards (ACM / ICPC / IOI scoring)
• Assignments — student assignments with per-student progress tracking
• User Management — role-based access (Student, Admin, Judge, Staff) with JWT + Google OAuth2
• Real-time Notifications — event-driven updates over email and WebSocket

Key Features

---

Architecture

1. Service Topology

2. Data Layer

PostgreSQL Databases: user_svc_db · problem_svc_db · submission_svc_db · assignment_svc_db · notification_svc_db · payment_svc_db

3. Kafka Event Flows

4. Redis Usage

5. S3 Storage & External Services

6. Judge Flow

7. WebSocket Message Types (cdex-ws)

Room Types: contest:{id} · assignment:{id} · submission:{id} · college:{id} · batch:{id} · problem:{id} · user:{id} · global

8. Flow: Code Submission → Verdict

9. Flow: Auth Login

10. Flow: Contest Lifecycle

---

Microservices

Plus cdex-ws (:8081) — the dedicated WebSocket gateway that fans Kafka events out to connected clients.

---

Tech Stack

---

Repository Layout

The product is split across several repos/workspaces:

CDeX/
├── cdex-server/          # NestJS monorepo — all backend microservices
│   ├── apps/
│   │   ├── api-gateway/      # REST entry point (:3000)
│   │   ├── auth-edge/        # Auth edge: OAuth + sessions (:3001)
│   │   ├── judge-adapter/    # Judge0 integration (:3002)
│   │   ├── user-svc/         # Users, roles (gRPC :50051)
│   │   ├── problem-svc/      # Problems + test cases (gRPC :50052)
│   │   ├── contest-svc/      # Contests + leaderboards (gRPC :50053)
│   │   ├── submission-svc/   # Submissions + judge queue (gRPC :50054)
│   │   ├── assignment-svc/   # Assignments + progress (gRPC :50055)
│   │   ├── notification-svc/ # Email + WS notifications (gRPC :50056)
│   │   ├── payment-svc/      # Payments (gRPC :50057)
│   │   └── ai-svc/           # Pinecone + Groq assistance
│   ├── libs/                 # Shared: kafka, redis, storage
│   ├── docker/               # Service Dockerfiles
│   └── docker-compose.yml    # Full infra stack
│
├── cdex-client/          # Next.js 16 / React 19 student & professor app
├── cdex-super-admin/     # Next.js super-admin console
├── cdex-ws/              # WebSocket gateway (:8081)
├── landing/              # Marketing landing page
└── diagrams/             # Architecture diagrams

---

Infrastructure (Docker)

---

Getting Started

Prerequisites

• Node.js 20+ and pnpm
• Docker & Docker Compose

1. Start infrastructure

cd cdex-server
docker compose up -d   # PostgreSQL, pgBouncer, MongoDB, Redis, Kafka, MinIO, Judge0 (+8 workers)

2. Install & generate protos

pnpm install
pnpm proto:generate    # generate TypeScript gRPC stubs from .proto files

3. Run the services

# Everything in watch mode
pnpm dev

# …or a single service
pnpm dev:api-gateway
pnpm dev:submission-svc

4. Run the frontends

cd ../cdex-client && pnpm install && pnpm dev    # student/professor app
cd ../cdex-ws     && pnpm install && pnpm dev    # WebSocket gateway

---

API Surface (api-gateway)

/api/v1/auth/*          Authentication
/api/v1/user/*          User management
/api/v1/problem/*       Problem CRUD
/api/v1/submission/*    Code submission
/api/v1/contest/*       Contest management
/api/v1/assignment/*    Assignment management

---

Contributing

1. Branch from the monorepo: feat/<what-you-are-building>.
2. Update protos in cdex-server/libs / service proto dirs first (proto-first), then pnpm proto:generate.
3. Keep changes scoped to a single apps/<service> where possible.
4. pnpm lint and pnpm typecheck before opening a PR.
5. Describe event-contract changes (Kafka topics) and migrations in the PR.

---

License

MIT License — see LICENSE for details.

---

Built by Varun Hotani