⚙️ GetAlphaBit Backend – Placement Test Engine

The backend API for GetAlphaBit, an AI-Powered Placement Test Platform. This server manages authentication validation, user sync, dynamic question generation, AI-powered evaluation, history retrieval, and administrator aggregation dashboards. Built using Node.js, Express.js, Mongoose (MongoDB), Clerk, and OpenAI.

---

🚀 Key Features

• 🔒 Clerk Integration: Implements secure, token-based verification using @clerk/express middleware. No passwords or accounts are stored locally; session verification happens on every request via JWT authorization headers.
• 🧠 AI-Powered Test Generator: Communicates with OpenAI's API to dynamically construct exactly 10 comprehensive interview questions (5 JavaScript, 5 Node.js) spanning 5 distinct styles (MCQ, Output, UseCase, Theory, Code).
• 🤖 Automated Grading & Feedback: Grades candidate submissions out of 10 points and provides qualitative feedback explanations for each submitted answer via the OpenAI API.
• 🔄 State Idempotency: Resumes incomplete attempts for a user instead of consuming rate limits or generating duplicate tests.
• ⏳ Smart Rate Limiting: Restricts test generation to a maximum of 2 tests per 24 hours per user to manage API resource utilization.
• 💤 Built-in Render Keep-Alive: Automatically self-pings the /health endpoint to bypass sleep triggers on free cloud environments (like Render).

---

🛠️ Tech Stack

• Runtime: Node.js
• Framework: Express.js
• Database: MongoDB via Mongoose ODM
• Authentication: Clerk SDK (@clerk/express, @clerk/clerk-sdk-node)
• AI Integrations: OpenAI API (for generation and grading prompts)
• Utilities: CORS, dotenv, express-rate-limit, express-async-errors, axios

---

🗂️ Project Layout

mytestbackend/
├── middleware/
│   ├── clerkAuth.js         # JWT Token validation
│   └── errorHandler.js      # Global Express error filter
├── models/
│   ├── User.js              # Syncs profiles and scores
│   └── TestRecord.js        # Questions, user answers, and AI grading logs
├── routes/
│   ├── admin.js             # Dossiers & metric aggregates
│   ├── auth.js              # Token synchronization
│   └── test.js              # Question generation & grading
├── scripts/
│   └── ping.js              # Standalone CLI utility to keep servers awake
├── utils/
│   ├── keepAlive.js         # Embedded self-ping worker
│   └── openai.js            # Prompt builders for generation & evaluation
├── server.js                # Server entry point
├── API_DOCUMENTATION.md     # Detailed REST endpoint schemas
└── RENDER_KEEP_ALIVE.md     # Render-specific keep-awake instructions

---

⚙️ Configuration & Environment Variables

Create a .env file in the root of the backend folder:

# MongoDB Connection URI (Local or MongoDB Atlas)
MONGODB_URI=mongodb://localhost:27017/placement_test

# Clerk Credentials (from the Clerk Dashboard)
CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# OpenAI API Key (Required for GPT-based questions and grading)
OPENAI_API_KEY=sk-proj-...

# Port for the Express server (defaults to 5000)
PORT=3000

---

📥 Getting Started

1. Install Dependencies

npm install

2. Run the Development Server

npm run dev

The server will start on the configured PORT (e.g., http://localhost:3000).

3. Run in Production Mode

npm start

---

🗺️ API Routes At-A-Glance

For full details, JSON payloads, and response examples, refer to the API Documentation.

Method	Endpoint	Protection	Description
GET	/health	Public	Unprotected server health status & uptime checklist
GET	/api/auth/me	Protected	Syncs Clerk authenticated user and returns profile
GET	/api/test/generate	Protected	Returns existing incomplete test or generates 10 new questions
POST	/api/test/submit	Protected	Submits test answers, prompts AI grading, and stores final score
GET	/api/test/history	Protected	Retrieves past test history for the current user
GET	/api/admin/results	Admin Only	Retrieves aggregate metrics and complete logs of all candidates

---

💤 Preventing Cold Starts (Render Keep-Alive)

On Render's free tier, services spin down after 15 minutes of inactivity. To prevent this:

1. Self-Pinging: When deployed, the server automatically reads RENDER_EXTERNAL_URL or PING_URL and self-pings /health every 13 minutes.
2. Standalone Cron Script: Run the ping script externally:

   npm run ping https://your-app-name.onrender.com

3. Third-party Keep-Alives: Detailed instructions on configuring cron-job.org or UptimeRobot can be found in RENDER_KEEP_ALIVE.md.