██████╗ ██████╗ ██████╗ ███████╗██████╗ ██╗ ██╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔══██╗╚██╗██╔╝
██║ ██║ ██║██║ ██║█████╗ ██████╔╝ ╚███╔╝
██║ ██║ ██║██║ ██║██╔══╝ ██╔══██╗ ██╔██╗
╚██████╗╚██████╔╝██████╔╝███████╗██║ ██║██╔╝ ██╗
╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝
AI-Augmented Competitive Programming · Zero Human Curation · Fully Autonomous Judge
Most coding platforms rely on humans to write problems. coderX eliminates that bottleneck entirely —
an LLM generates problems on demand, a vector engine prevents duplicates, and an isolated Docker judge evaluates every submission in real time.
This repo is documentation-only. All services live in their own repositories.
| Service | Repository | Stack |
|---|---|---|
| 🤖 AI Service | coderX_aiService | Python · FastAPI · Groq · LangChain · AstraDB |
| 📝 Problem Service | coderX---Problem_Service | Node.js · Express · MongoDB |
| 📤 Submission Service | coderX---submissionService | Node.js · Fastify · BullMQ · Redis |
| ⚡ Evaluator Service | coderX--Evaluator-Service | TypeScript · Docker · Dockerode |
| 🔌 WebSocket Service | coderX_WebSocketService | Node.js · Socket.io · Redis |
| 🎨 Frontend | coderX_FrontEnd | React 19 · TypeScript · Vite · Tailwind |
The AI Service hits Groq's API via LangChain to produce fully-structured problems from a simple {topic, difficulty} prompt. Groq's LLaMA-3 inference runs at ~10× lower latency than OpenAI — critical when generation is a synchronous user action.
chain = prompt_template | groq_llm | output_parser
problem = chain.invoke({ "topic": "Binary Trees", "difficulty": "Hard" })
# → { title, description, test_cases, editorial, time_complexity }Before any problem is stored, it is embedded via Voyage AI and compared against every existing problem in AstraDB (a persistent, serverless Cassandra-backed vector store). Problems exceeding a tuned similarity threshold are rejected — the deduplication index survives restarts and scales automatically, unlike FAISS.
embedding = voyage_client.embed([problem.description])
similar = astra_collection.find(sort={"$vector": embedding}, limit=5, projection={"$similarity": True})
if similar[0]["$similarity"] > DEDUP_THRESHOLD:
raise DuplicateProblemError("Too similar to existing problem")The threshold was manually tuned by testing against known near-duplicate problems.
Each submission is enqueued into BullMQ (Redis-backed) and picked up by a worker in the Evaluator Service. The worker spins up a fresh Docker container per submission, injects user code via Heredocs (preventing shell injection), enforces hard resource limits, and streams the verdict back through Socket.io.
const result = await containerFactory.run({
language: 'python',
code: submission.code,
testCases: problem.testCases,
timeLimit: 2000, // ms
memoryLimit: 256, // MB
});
// Handles: TLE · MLE · OOM kills · zombie process cleanup████████████████████░░░░ 85% Complete
| Area | Status | Notes |
|---|---|---|
| Judge Engine (Docker sandbox) | ✅ Done | TLE, MLE, OOM, shell injection handled |
| AI Problem Generation Pipeline | ✅ Done | Groq + LangChain + structured output |
| Semantic Deduplication | ✅ Done | Voyage AI + AstraDB, threshold tuned |
| BullMQ Submission Queue | ✅ Done | Bull Board monitoring integrated |
| WebSocket Verdict Streaming | ✅ Done | Real-time testcase-level feedback |
| Multi-Language Support | ✅ Done | C++, Java, Python |
| Frontend UI + Monaco Editor | ✅ Done | Triple-editor with locked boilerplate |
| Glassmorphism Design System | ✅ Done | Tailwind-based |
| Generate Button → AI Service | 🔧 In Progress | Final integration wire-up |
| JWT Authentication | 🔧 Planned | Replacing demo IDs (Firebase / Clerk) |
| User Dashboard & Stats | 🔧 Planned | Heatmaps, solved count from DB |
Why BullMQ over direct execution?
Submission spikes would overwhelm the judge if handled synchronously. BullMQ decouples ingestion from execution — evaluator workers can be scaled horizontally, independently of the API layer.
Why AstraDB over FAISS?
FAISS requires an in-memory index that must be rebuilt on every restart. AstraDB is persistent and serverless — the deduplication index is always live, and storage scales automatically without ops overhead.
Why Groq over OpenAI?
Problem generation is a synchronous API call that the user waits for. Groq's LLaMA-3 inference latency is ~10× lower than GPT-4 equivalents, making the UX significantly snappier for this use case.
Why Heredocs for code injection?
Interpolating user code directly into shell commands opens shell injection attacks. Heredocs write code to stdin as a raw stream — the container's shell never interprets the user's content as a command.
| Layer | Technology |
|---|---|
| Frontend | React 19 · TypeScript · Vite · Tailwind CSS · Monaco Editor |
| Problem Service | Node.js · Express · MongoDB |
| Submission Service | Node.js · Fastify · BullMQ · Redis |
| AI Service | Python · FastAPI · LangChain · Groq (LLaMA-3) |
| Embeddings | Voyage AI — 1024-dim vectors |
| Vector Store | AstraDB (Cassandra-backed, serverless) |
| Judge | TypeScript · Docker · Dockerode |
| Real-time | Socket.io · Redis pub/sub |
| Monitoring | Bull Board (BullMQ dashboard) |
POST /api/v1/problems/generate
Body → { "topic": string, "difficulty": "Easy" | "Medium" | "Hard" }
Returns → { problem, embedding_stored, dedup_passed }
GET /api/v1/problems/
Returns → paginated list of generated problems
GET /health
Returns → service status
POST /api/submissions → enqueued to BullMQ, returns submission ID
GET /api/submissions/:id → polling endpoint for verdict
WS /ws/submissions/:id → real-time testcase-level verdict stream
GET http://localhost:3002/admin/queues → Bull Board queue dashboard
Node.js 18+ Python 3.10+ Docker Redis MongoDB
Groq API key · AstraDB credentials · Voyage AI key
# 1 — AI Service
cd coderX_aiService && pip install -r requirements.txt
uvicorn main:app --reload --port 8001
# 2 — Problem Service
cd coderX---Problem_Service && npm install && npm start # :3001
# 3 — Submission Service
cd coderX---submissionService && npm install && npm start # :3002
# 4 — Evaluator Service (queue consumer, no HTTP port)
cd coderX--Evaluator-Service && npm install && npm run dev
# 5 — Frontend
cd coderX_FrontEnd && npm install && npm run dev # :5173This is not a tutorial project. Every architectural decision was designed and implemented from scratch:
- Designed the microservices split — which service owns what, and why
- Chose AstraDB over FAISS after benchmarking persistence and restart behavior
- Tuned the deduplication threshold manually against real near-duplicate test cases
- Solved real Docker edge cases: container cleanup, OOM kills, zombie processes, Heredoc injection safety
- Integrated Bull Board for live queue health monitoring
- Built a triple-pane Monaco editor where boilerplate is read-only to prevent wrapper breakage
Abhinav Sunil — CSE (AI/ML), Lovely Professional University · Grad 2027
Code. Compete. Conquer.