v1.1

.gitignore

@@ -0,0 +1,10 @@
+venv
+.env
+.env.local
+node_modules
+__pycache__
+*.pyc
+uploads/
+.next
+dist
+.vercel

backend/auth/jwt.py

@@ -0,0 +1,53 @@
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+from jose import JWTError, jwt
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from config import get_settings
+
+settings = get_settings()
+security = HTTPBearer()
+
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    to_encode = data.copy()
+    expire = datetime.now(timezone.utc) + (expires_delta or timedelta(seconds=settings.JWT_EXPIRY))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
+
+
+def verify_token(token: str) -> dict:
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET, algorithms=[settings.JWT_ALGORITHM])
+        return payload
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+        )
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+) -> dict:
+    payload = verify_token(credentials.credentials)
+    user_id = payload.get("sub")
+    if not user_id:
+        raise HTTPException(status_code=401, detail="Invalid token payload")
+    return {
+        "user_id": user_id,
+        "email": payload.get("email", ""),
+        "role": payload.get("role", "student"),
+        "name": payload.get("name", ""),
+    }
+
+
+def require_role(role: str):
+    async def role_checker(current_user: dict = Depends(get_current_user)):
+        if current_user.get("role") != role:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Access denied. Requires '{role}' role.",
+            )
+        return current_user
+    return role_checker

backend/config.py

@@ -0,0 +1,44 @@
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+import os
+from dotenv import load_dotenv
+
+# Load .env from backend directory
+load_dotenv(os.path.join(os.path.dirname(__file__), ".env"))
+
+
+class Settings(BaseSettings):
+    # App
+    APP_ENV: str = "production"
+    APP_PORT: int = 8000
+
+    # Gemini
+    GEMINI_API_KEY: str
+    GEMINI_MODEL: str = "gemini-2.5-flash"
+
+    # MongoDB Atlas
+    MONGO_URI: str
+    MONGO_DB_NAME: str = "interview_bot"
+
+    # Redis
+    REDIS_URL: str
+
+    # JWT
+    JWT_SECRET: str
+    JWT_ALGORITHM: str = "HS256"
+    JWT_EXPIRY: int = 3600
+
+    # File Storage
+    UPLOAD_DIR: str = "./uploads"
+
+    # Frontend
+    NEXT_PUBLIC_API_URL: str = "http://localhost:3000"
+
+    class Config:
+        env_file = ".env"
+        extra = "ignore"
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()

backend/database.py

@@ -0,0 +1,59 @@
+from motor.motor_asyncio import AsyncIOMotorClient
+import redis.asyncio as aioredis
+from config import get_settings
+
+settings = get_settings()
+
+# MongoDB Atlas
+mongo_client: AsyncIOMotorClient = None
+db = None
+
+# Redis
+redis_client: aioredis.Redis = None
+
+
+async def connect_db():
+    """Initialize MongoDB and Redis connections."""
+    global mongo_client, db, redis_client
+
+    # MongoDB Atlas
+    mongo_client = AsyncIOMotorClient(settings.MONGO_URI)
+    db = mongo_client[settings.MONGO_DB_NAME]
+
+    # Create indexes
+    await db.users.create_index("email", unique=True)
+    await db.resumes.create_index("user_id", unique=True)
+    await db.skills.create_index("user_id")
+    await db.sessions.create_index("user_id")
+    await db.results.create_index("session_id")
+    await db.results.create_index("user_id")
+    await db.questions.create_index("role_id")
+
+    # Redis
+    redis_client = aioredis.from_url(
+        settings.REDIS_URL,
+        decode_responses=True,
+    )
+
+    # Test connections
+    await mongo_client.admin.command("ping")
+    await redis_client.ping()
+    print("✅ Connected to MongoDB Atlas and Redis")
+
+
+async def close_db():
+    """Close database connections."""
+    global mongo_client, redis_client
+    if mongo_client:
+        mongo_client.close()
+    if redis_client:
+        await redis_client.close()
+    print("🔌 Database connections closed")
+
+
+def get_db():
+    return db
+
+
+def get_redis():
+    return redis_client

backend/main.py

@@ -0,0 +1,53 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+import os
+
+from config import get_settings
+from database import connect_db, close_db
+
+from routers import auth, resume, profile, interview, reports, admin
+
+settings = get_settings()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await connect_db()
+    os.makedirs(settings.UPLOAD_DIR, exist_ok=True)
+    print(f"🚀 Interview Bot API running in {settings.APP_ENV} mode")
+    yield
+    # Shutdown
+    await close_db()
+
+
+app = FastAPI(
+    title="AI Mock Interview Trainer",
+    description="Production-ready AI-powered mock interview platform",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Routers
+app.include_router(auth.router, prefix="/auth", tags=["Authentication"])
+app.include_router(resume.router, prefix="/resume", tags=["Resume"])
+app.include_router(profile.router, prefix="/profile", tags=["Profile"])
+app.include_router(interview.router, prefix="/interview", tags=["Interview"])
+app.include_router(reports.router, prefix="/reports", tags=["Reports"])
+app.include_router(admin.router, prefix="/admin", tags=["Admin"])
+
+
+@app.get("/health")
+async def health_check():
+    return {"status": "healthy", "version": "1.0.0"}

backend/models/collections.py

@@ -0,0 +1,11 @@
+# MongoDB collection name constants
+
+USERS = "users"
+RESUMES = "resumes"
+SKILLS = "skills"
+JOB_ROLES = "job_roles"
+ROLE_REQUIREMENTS = "role_requirements"
+QUESTIONS = "questions"
+SESSIONS = "sessions"
+ANSWERS = "answers"
+RESULTS = "results"

backend/requirements.txt

@@ -0,0 +1,13 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.0
+motor==3.5.0
+redis[hiredis]==5.0.0
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+bcrypt==4.0.1
+python-multipart==0.0.9
+google-genai==1.5.0
+langgraph==0.2.0
+pydantic-settings==2.5.0
+python-dotenv==1.0.1
+aiofiles==24.1.0

backend/routers/admin.py

@@ -0,0 +1,167 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from auth.jwt import require_role, get_current_user
+from schemas.admin import (
+    JobRoleCreate, JobRoleUpdate,
+    QuestionCreate, QuestionUpdate,
+    RoleRequirementCreate,
+)
+from services.admin_service import (
+    create_role, update_role, delete_role, list_roles,
+    create_question, update_question, delete_question, list_questions,
+    create_requirement, list_requirements, delete_requirement,
+)
+from services.analytics_service import get_admin_analytics
+
+router = APIRouter()
+
+
+# ─── Job Roles ───
+
+@router.get("/roles")
+async def get_roles(current_user: dict = Depends(get_current_user)):
+    """List all job roles (accessible by all authenticated users for interview selection)."""
+    roles = await list_roles()
+    return {"roles": roles}
+
+
+@router.post("/roles")
+async def create_role_endpoint(
+    request: JobRoleCreate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Create a new job role (admin only)."""
+    result = await create_role(
+        title=request.title,
+        description=request.description,
+        department=request.department,
+    )
+    return result
+
+
+@router.put("/roles/{role_id}")
+async def update_role_endpoint(
+    role_id: str,
+    request: JobRoleUpdate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Update a job role (admin only)."""
+    try:
+        result = await update_role(role_id, request.model_dump())
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/roles/{role_id}")
+async def delete_role_endpoint(
+    role_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Delete a job role (admin only)."""
+    success = await delete_role(role_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Role not found")
+    return {"message": "Role deleted"}
+
+
+# ─── Questions ───
+
+@router.get("/questions")
+async def get_questions(
+    role_id: str = Query(None),
+    current_user: dict = Depends(require_role("admin")),
+):
+    """List questions, optionally filtered by role."""
+    questions = await list_questions(role_id)
+    return {"questions": questions}
+
+
+@router.post("/questions")
+async def create_question_endpoint(
+    request: QuestionCreate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Create a new question (admin only)."""
+    result = await create_question(
+        role_id=request.role_id,
+        question=request.question,
+        difficulty=request.difficulty,
+        category=request.category,
+        expected_answer=request.expected_answer,
+    )
+    return result
+
+
+@router.put("/questions/{question_id}")
+async def update_question_endpoint(
+    question_id: str,
+    request: QuestionUpdate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Update a question (admin only)."""
+    try:
+        result = await update_question(question_id, request.model_dump())
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/questions/{question_id}")
+async def delete_question_endpoint(
+    question_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Delete a question (admin only)."""
+    success = await delete_question(question_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Question not found")
+    return {"message": "Question deleted"}
+
+
+# ─── Role Requirements ───
+
+@router.get("/requirements/{role_id}")
+async def get_requirements(
+    role_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """List requirements for a role."""
+    requirements = await list_requirements(role_id)
+    return {"requirements": requirements}
+
+
+@router.post("/requirements")
+async def create_requirement_endpoint(
+    request: RoleRequirementCreate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Create a role requirement (admin only)."""
+    result = await create_requirement(
+        role_id=request.role_id,
+        skill=request.skill,
+        level=request.level,
+    )
+    return result
+
+
+@router.delete("/requirements/{req_id}")
+async def delete_requirement_endpoint(
+    req_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Delete a role requirement (admin only)."""
+    success = await delete_requirement(req_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Requirement not found")
+    return {"message": "Requirement deleted"}
+
+
+# ─── Analytics ───
+
+@router.get("/analytics")
+async def get_analytics(
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Get admin analytics dashboard data."""
+    analytics = await get_admin_analytics()
+    return analytics

backend/routers/auth.py

@@ -0,0 +1,29 @@
+from fastapi import APIRouter, HTTPException
+from schemas.auth import SignupRequest, LoginRequest, AuthResponse
+from services.auth_service import signup_user, login_user
+
+router = APIRouter()
+
+
+@router.post("/signup", response_model=AuthResponse)
+async def signup(request: SignupRequest):
+    """Register a new user."""
+    try:
+        result = await signup_user(
+            name=request.name,
+            email=request.email,
+            password=request.password,
+        )
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/login", response_model=AuthResponse)
+async def login(request: LoginRequest):
+    """Authenticate and get JWT token."""
+    try:
+        result = await login_user(email=request.email, password=request.password)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=401, detail=str(e))

backend/routers/interview.py

@@ -0,0 +1,65 @@
+from fastapi import APIRouter, Depends, HTTPException
+from auth.jwt import get_current_user
+from schemas.interview import (
+    StartInterviewRequest,
+    SubmitAnswerRequest,
+    InterviewStartResponse,
+    AnswerResponse,
+)
+from services.interview_service import start_interview, submit_answer
+from services.evaluation_service import generate_report
+
+router = APIRouter()
+
+
+@router.post("/start")
+async def start_interview_endpoint(
+    request: StartInterviewRequest,
+    current_user: dict = Depends(get_current_user),
+):
+    """Start a new interview session."""
+    try:
+        result = await start_interview(
+            user_id=current_user["user_id"],
+            role_id=request.role_id,
+        )
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/answer")
+async def submit_answer_endpoint(
+    request: SubmitAnswerRequest,
+    current_user: dict = Depends(get_current_user),
+):
+    """Submit an answer and get next question."""
+    try:
+        result = await submit_answer(
+            session_id=request.session_id,
+            question_id=request.question_id,
+            answer=request.answer,
+        )
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/report")
+async def get_interview_report(
+    session_id: str,
+    current_user: dict = Depends(get_current_user),
+):
+    """Generate and retrieve interview report."""
+    try:
+        result = await generate_report(
+            session_id=session_id,
+            user_id=current_user["user_id"],
+        )
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

backend/routers/profile.py

@@ -0,0 +1,61 @@
+from fastapi import APIRouter, Depends
+from auth.jwt import get_current_user
+from database import get_db
+from models.collections import USERS, RESUMES, SKILLS
+from utils.helpers import str_objectid
+from bson import ObjectId
+
+router = APIRouter()
+
+
+@router.get("")
+async def get_profile(current_user: dict = Depends(get_current_user)):
+    """Get current user's profile with skills and resume info."""
+    db = get_db()
+
+    user = await db[USERS].find_one({"_id": ObjectId(current_user["user_id"])})
+    if not user:
+        # Fallback: try finding by email
+        user = await db[USERS].find_one({"email": current_user["email"]})
+
+    profile = {
+        "user_id": current_user["user_id"],
+        "name": current_user.get("name", ""),
+        "email": current_user.get("email", ""),
+        "role": current_user.get("role", "student"),
+    }
+
+    # Get resume info
+    resume = await db[RESUMES].find_one({"user_id": current_user["user_id"]})
+    if resume:
+        profile["resume"] = {
+            "filename": resume.get("original_filename", ""),
+            "uploaded_at": resume.get("uploaded_at", ""),
+            "parsed_text": resume.get("parsed_text", ""),
+        }
+    else:
+        profile["resume"] = None
+
+    # Get skills
+    skills_doc = await db[SKILLS].find_one({"user_id": current_user["user_id"]})
+    profile["skills"] = skills_doc.get("skills", []) if skills_doc else []
+
+    return profile
+
+@router.put("/skills")
+async def update_user_skills(
+    request_data: dict,  # Or use UpdateSkillsRequest if imported
+    current_user: dict = Depends(get_current_user)
+):
+    """Update the current user's extracted skills."""
+    db = get_db()
+    skills = request_data.get("skills", [])
+    
+    # Upsert the skills document for this user
+    await db[SKILLS].update_one(
+        {"user_id": current_user["user_id"]},
+        {"$set": {"skills": skills, "user_id": current_user["user_id"]}},
+        upsert=True
+    )
+    
+    return {"message": "Skills updated successfully", "skills": skills}

backend/routers/reports.py

@@ -0,0 +1,12 @@
+from fastapi import APIRouter, Depends
+from auth.jwt import get_current_user
+from services.analytics_service import get_student_history
+
+router = APIRouter()
+
+
+@router.get("/history")
+async def get_reports_history(current_user: dict = Depends(get_current_user)):
+    """Get student's interview history."""
+    history = await get_student_history(current_user["user_id"])
+    return {"reports": history}

backend/routers/resume.py

@@ -0,0 +1,36 @@
+from fastapi import APIRouter, UploadFile, File, Depends, HTTPException
+from auth.jwt import get_current_user
+from services.resume_service import upload_and_parse_resume
+
+router = APIRouter()
+
+
+@router.post("/upload")
+async def upload_resume(
+    file: UploadFile = File(...),
+    current_user: dict = Depends(get_current_user),
+):
+    """Upload and parse a resume using Gemini AI."""
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="No file provided")
+
+    allowed_types = [
+        "application/pdf",
+        "text/plain",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ]
+
+    content = await file.read()
+    if len(content) > 5 * 1024 * 1024:  # 5MB limit
+        raise HTTPException(status_code=400, detail="File too large. Maximum 5MB.")
+
+    try:
+        result = await upload_and_parse_resume(
+            user_id=current_user["user_id"],
+            filename=file.filename,
+            file_content=content,
+        )
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to process resume: {str(e)}")

backend/schemas/admin.py

@@ -0,0 +1,59 @@
+from pydantic import BaseModel
+from typing import Optional, List
+
+
+class JobRoleCreate(BaseModel):
+    title: str
+    description: str
+    department: Optional[str] = None
+
+
+class JobRoleUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    department: Optional[str] = None
+
+
+class JobRoleResponse(BaseModel):
+    id: str
+    title: str
+    description: str
+    department: Optional[str] = None
+    created_at: str
+
+
+class QuestionCreate(BaseModel):
+    role_id: str
+    question: str
+    difficulty: str = "medium"
+    category: Optional[str] = None
+    expected_answer: Optional[str] = None
+
+
+class QuestionUpdate(BaseModel):
+    question: Optional[str] = None
+    difficulty: Optional[str] = None
+    category: Optional[str] = None
+    expected_answer: Optional[str] = None
+
+
+class QuestionResponse(BaseModel):
+    id: str
+    role_id: str
+    question: str
+    difficulty: str
+    category: Optional[str] = None
+    created_at: str
+
+
+class RoleRequirementCreate(BaseModel):
+    role_id: str
+    skill: str
+    level: str = "intermediate"
+
+
+class RoleRequirementResponse(BaseModel):
+    id: str
+    role_id: str
+    skill: str
+    level: str

backend/schemas/analytics.py

@@ -0,0 +1,30 @@
+from pydantic import BaseModel
+from typing import List, Optional, Dict
+
+
+class StudentAnalytics(BaseModel):
+    user_id: str
+    name: str
+    email: str
+    total_interviews: int
+    average_score: float
+    best_score: int
+    worst_score: int
+    weak_topics: List[str]
+    strong_topics: List[str]
+
+
+class OverallAnalytics(BaseModel):
+    total_students: int
+    total_interviews: int
+    average_score: float
+    top_performers: List[Dict]
+    common_weak_areas: List[str]
+
+
+class ReportHistory(BaseModel):
+    session_id: str
+    overall_score: int
+    total_questions: int
+    completed_at: str
+    role_title: Optional[str] = None

backend/schemas/auth.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel, EmailStr
+from typing import Optional
+
+
+class SignupRequest(BaseModel):
+    name: str
+    email: EmailStr
+    password: str
+
+
+class LoginRequest(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class AuthResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    user: dict

backend/schemas/interview.py

@@ -0,0 +1,51 @@
+from pydantic import BaseModel
+from typing import Optional, List, Dict
+
+
+class StartInterviewRequest(BaseModel):
+    role_id: Optional[str] = None
+
+
+class SubmitAnswerRequest(BaseModel):
+    session_id: str
+    question_id: str
+    answer: str
+
+
+class InterviewQuestion(BaseModel):
+    question_id: str
+    question: str
+    difficulty: str = "medium"
+    question_number: int = 1
+    total_questions: int = 10
+
+
+class InterviewStartResponse(BaseModel):
+    session_id: str
+    question: InterviewQuestion
+    message: str = "Interview started"
+
+
+class AnswerResponse(BaseModel):
+    session_id: str
+    next_question: Optional[InterviewQuestion] = None
+    is_complete: bool = False
+    message: str = ""
+
+
+class QuestionScore(BaseModel):
+    question: str
+    answer: str
+    score: int
+    feedback: str
+
+
+class InterviewReport(BaseModel):
+    session_id: str
+    overall_score: int
+    total_questions: int
+    strengths: List[str]
+    weaknesses: List[str]
+    detailed_scores: List[QuestionScore]
+    recommendations: List[str]
+    completed_at: str

backend/schemas/resume.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel
+from typing import Optional, List
+
+
+class ResumeResponse(BaseModel):
+    id: str
+    user_id: str
+    filename: str
+    parsed_text: Optional[str] = None
+    skills: List[str] = []
+    uploaded_at: str
+
+class UpdateSkillsRequest(BaseModel):
+    skills: List[str]

backend/services/admin_service.py

@@ -0,0 +1,118 @@
+from bson import ObjectId
+from database import get_db
+from models.collections import JOB_ROLES, ROLE_REQUIREMENTS, QUESTIONS
+from utils.helpers import utc_now, str_objectid, str_objectids
+
+
+# ─── Job Roles ───
+
+async def create_role(title: str, description: str, department: str = None) -> dict:
+    db = get_db()
+    doc = {
+        "title": title,
+        "description": description,
+        "department": department,
+        "created_at": utc_now(),
+    }
+    result = await db[JOB_ROLES].insert_one(doc)
+    doc["_id"] = result.inserted_id
+    return str_objectid(doc)
+
+
+async def update_role(role_id: str, data: dict) -> dict:
+    db = get_db()
+    update_data = {k: v for k, v in data.items() if v is not None}
+    if not update_data:
+        raise ValueError("No fields to update")
+    update_data["updated_at"] = utc_now()
+    await db[JOB_ROLES].update_one({"_id": ObjectId(role_id)}, {"$set": update_data})
+    doc = await db[JOB_ROLES].find_one({"_id": ObjectId(role_id)})
+    if not doc:
+        raise ValueError("Role not found")
+    return str_objectid(doc)
+
+
+async def delete_role(role_id: str) -> bool:
+    db = get_db()
+    result = await db[JOB_ROLES].delete_one({"_id": ObjectId(role_id)})
+    return result.deleted_count > 0
+
+
+async def list_roles() -> list:
+    db = get_db()
+    cursor = db[JOB_ROLES].find().sort("created_at", -1)
+    docs = await cursor.to_list(length=100)
+    return str_objectids(docs)
+
+
+# ─── Questions ───
+
+async def create_question(role_id: str, question: str, difficulty: str = "medium",
+                          category: str = None, expected_answer: str = None) -> dict:
+    db = get_db()
+    doc = {
+        "role_id": role_id,
+        "question": question,
+        "difficulty": difficulty,
+        "category": category,
+        "expected_answer": expected_answer,
+        "created_at": utc_now(),
+    }
+    result = await db[QUESTIONS].insert_one(doc)
+    doc["_id"] = result.inserted_id
+    return str_objectid(doc)
+
+
+async def update_question(question_id: str, data: dict) -> dict:
+    db = get_db()
+    update_data = {k: v for k, v in data.items() if v is not None}
+    if not update_data:
+        raise ValueError("No fields to update")
+    update_data["updated_at"] = utc_now()
+    await db[QUESTIONS].update_one({"_id": ObjectId(question_id)}, {"$set": update_data})
+    doc = await db[QUESTIONS].find_one({"_id": ObjectId(question_id)})
+    if not doc:
+        raise ValueError("Question not found")
+    return str_objectid(doc)
+
+
+async def delete_question(question_id: str) -> bool:
+    db = get_db()
+    result = await db[QUESTIONS].delete_one({"_id": ObjectId(question_id)})
+    return result.deleted_count > 0
+
+
+async def list_questions(role_id: str = None) -> list:
+    db = get_db()
+    query = {"role_id": role_id} if role_id else {}
+    cursor = db[QUESTIONS].find(query).sort("created_at", -1)
+    docs = await cursor.to_list(length=200)
+    return str_objectids(docs)
+
+
+# ─── Role Requirements ───
+
+async def create_requirement(role_id: str, skill: str, level: str = "intermediate") -> dict:
+    db = get_db()
+    doc = {
+        "role_id": role_id,
+        "skill": skill,
+        "level": level,
+        "created_at": utc_now(),
+    }
+    result = await db[ROLE_REQUIREMENTS].insert_one(doc)
+    doc["_id"] = result.inserted_id
+    return str_objectid(doc)
+
+
+async def list_requirements(role_id: str) -> list:
+    db = get_db()
+    cursor = db[ROLE_REQUIREMENTS].find({"role_id": role_id})
+    docs = await cursor.to_list(length=100)
+    return str_objectids(docs)
+
+
+async def delete_requirement(req_id: str) -> bool:
+    db = get_db()
+    result = await db[ROLE_REQUIREMENTS].delete_one({"_id": ObjectId(req_id)})
+    return result.deleted_count > 0

backend/services/analytics_service.py

@@ -0,0 +1,118 @@
+from database import get_db
+from models.collections import RESULTS, SESSIONS, USERS
+from utils.helpers import str_objectid, str_objectids
+
+
+async def get_student_history(user_id: str) -> list:
+    """Get all interview reports for a student."""
+    db = get_db()
+    cursor = db[RESULTS].find({"user_id": user_id}).sort("completed_at", -1)
+    docs = await cursor.to_list(length=50)
+    results = []
+    for doc in docs:
+        results.append({
+            "session_id": doc.get("session_id"),
+            "overall_score": doc.get("overall_score", 0),
+            "total_questions": doc.get("total_questions", 0),
+            "completed_at": doc.get("completed_at", ""),
+            "role_title": doc.get("role_title", ""),
+        })
+    return results
+
+
+async def get_admin_analytics() -> dict:
+    """Get aggregated analytics for admin dashboard."""
+    db = get_db()
+
+    # Total students
+    total_students = await db[USERS].count_documents({"role": "student"})
+
+    # Total interviews
+    total_interviews = await db[RESULTS].count_documents({})
+
+    # Average score
+    pipeline = [
+        {"$group": {"_id": None, "avg_score": {"$avg": "$overall_score"}}},
+    ]
+    avg_result = await db[RESULTS].aggregate(pipeline).to_list(length=1)
+    avg_score = round(avg_result[0]["avg_score"], 1) if avg_result else 0
+
+    # Top performers
+    top_pipeline = [
+        {"$group": {
+            "_id": "$user_id",
+            "avg_score": {"$avg": "$overall_score"},
+            "interview_count": {"$sum": 1},
+        }},
+        {"$sort": {"avg_score": -1}},
+        {"$limit": 10},
+    ]
+    top_results = await db[RESULTS].aggregate(top_pipeline).to_list(length=10)
+
+    top_performers = []
+    for r in top_results:
+        user = await db[USERS].find_one({"_id": __import__("bson").ObjectId(r["_id"])})
+        if not user:
+            # user_id might be stored as string
+            user = await db[USERS].find_one({"email": {"$exists": True}})
+        top_performers.append({
+            "user_id": r["_id"],
+            "name": user.get("name", "Unknown") if user else "Unknown",
+            "avg_score": round(r["avg_score"], 1),
+            "interview_count": r["interview_count"],
+        })
+
+    # Common weak areas
+    weakness_pipeline = [
+        {"$unwind": "$weaknesses"},
+        {"$group": {"_id": "$weaknesses", "count": {"$sum": 1}}},
+        {"$sort": {"count": -1}},
+        {"$limit": 10},
+    ]
+    weakness_results = await db[RESULTS].aggregate(weakness_pipeline).to_list(length=10)
+    common_weak = [w["_id"] for w in weakness_results]
+
+    return {
+        "total_students": total_students,
+        "total_interviews": total_interviews,
+        "average_score": avg_score,
+        "top_performers": top_performers,
+        "common_weak_areas": common_weak,
+    }
+
+
+async def get_student_analytics(user_id: str) -> dict:
+    """Get analytics for a specific student."""
+    db = get_db()
+
+    results = await db[RESULTS].find({"user_id": user_id}).to_list(length=100)
+    if not results:
+        return {
+            "total_interviews": 0,
+            "average_score": 0,
+            "best_score": 0,
+            "worst_score": 0,
+            "weak_topics": [],
+            "strong_topics": [],
+        }
+
+    scores = [r.get("overall_score", 0) for r in results]
+    all_weaknesses = []
+    all_strengths = []
+    for r in results:
+        all_weaknesses.extend(r.get("weaknesses", []))
+        all_strengths.extend(r.get("strengths", []))
+
+    # Count frequencies
+    from collections import Counter
+    weak_counts = Counter(all_weaknesses)
+    strong_counts = Counter(all_strengths)
+
+    return {
+        "total_interviews": len(results),
+        "average_score": round(sum(scores) / len(scores), 1),
+        "best_score": max(scores),
+        "worst_score": min(scores),
+        "weak_topics": [w for w, _ in weak_counts.most_common(5)],
+        "strong_topics": [s for s, _ in strong_counts.most_common(5)],
+    }

backend/services/auth_service.py

@@ -0,0 +1,67 @@
+from passlib.context import CryptContext
+from database import get_db
+from models.collections import USERS
+from utils.helpers import utc_now, str_objectid
+from auth.jwt import create_access_token
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+async def signup_user(name: str, email: str, password: str, role: str = None) -> dict:
+    """Register a new user."""
+    db = get_db()
+
+    # Check if user exists
+    existing = await db[USERS].find_one({"email": email})
+    if existing:
+        raise ValueError("User with this email already exists")
+
+    # Enforce role logic
+    determined_role = "admin" if email.endswith("@admin.com") else "student"
+
+    hashed_password = pwd_context.hash(password)
+    user_doc = {
+        "name": name,
+        "email": email,
+        "password": hashed_password,
+        "role": determined_role,
+        "created_at": utc_now(),
+    }
+
+    result = await db[USERS].insert_one(user_doc)
+    user_doc["_id"] = result.inserted_id
+    user = str_objectid(user_doc)
+    del user["password"]
+
+    token = create_access_token({
+        "sub": user["id"],
+        "email": user["email"],
+        "role": user["role"],
+        "name": user["name"],
+    })
+
+    return {"access_token": token, "token_type": "bearer", "user": user}
+
+
+async def login_user(email: str, password: str) -> dict:
+    """Authenticate a user and return JWT."""
+    db = get_db()
+
+    user_doc = await db[USERS].find_one({"email": email})
+    if not user_doc:
+        raise ValueError("Invalid email or password")
+
+    if not pwd_context.verify(password, user_doc["password"]):
+        raise ValueError("Invalid email or password")
+
+    user = str_objectid(user_doc)
+    del user["password"]
+
+    token = create_access_token({
+        "sub": user["id"],
+        "email": user["email"],
+        "role": user["role"],
+        "name": user["name"],
+    })
+
+    return {"access_token": token, "token_type": "bearer", "user": user}

backend/services/evaluation_service.py

@@ -0,0 +1,83 @@
+from database import get_db, get_redis
+from models.collections import RESULTS, ANSWERS, SESSIONS
+from utils.helpers import utc_now
+from utils.gemini import evaluate_interview
+from services.interview_service import get_session_qa
+
+
+async def generate_report(session_id: str, user_id: str) -> dict:
+    """Generate final evaluation report from Redis Q&A data using Gemini."""
+    db = get_db()
+    redis = get_redis()
+
+    # Check if report already exists
+    existing = await db[RESULTS].find_one({"session_id": session_id})
+    if existing:
+        existing["id"] = str(existing["_id"])
+        del existing["_id"]
+        return existing
+
+    # Get session info
+    session = await db[SESSIONS].find_one({"session_id": session_id})
+    if not session:
+        raise ValueError("Session not found")
+
+    if session.get("user_id") != user_id:
+        raise ValueError("Unauthorized access to session")
+
+    role_title = session.get("role_title", "Software Developer")
+
+    # Get all Q&A from Redis
+    qa_pairs = await get_session_qa(session_id)
+    if not qa_pairs:
+        raise ValueError("No Q&A data found for this session")
+
+    # Batch evaluate with Gemini
+    evaluation = await evaluate_interview(qa_pairs, role_title)
+
+    # Store results in MongoDB
+    result_doc = {
+        "session_id": session_id,
+        "user_id": user_id,
+        "role_title": role_title,
+        "overall_score": evaluation.get("overall_score", 0),
+        "total_questions": len(qa_pairs),
+        "detailed_scores": evaluation.get("detailed_scores", []),
+        "strengths": evaluation.get("strengths", []),
+        "weaknesses": evaluation.get("weaknesses", []),
+        "recommendations": evaluation.get("recommendations", []),
+        "completed_at": utc_now(),
+    }
+    await db[RESULTS].insert_one(result_doc)
+
+    # Store final answers in MongoDB
+    for qa in qa_pairs:
+        answer_doc = {
+            "session_id": session_id,
+            "user_id": user_id,
+            "question_id": qa["question_id"],
+            "question": qa["question"],
+            "answer": qa["answer"],
+            "difficulty": qa["difficulty"],
+            "category": qa["category"],
+            "stored_at": utc_now(),
+        }
+        await db[ANSWERS].insert_one(answer_doc)
+
+    # Clean up Redis session data
+    question_ids = await redis.lrange(f"session:{session_id}:questions", 0, -1)
+    keys_to_delete = [
+        f"session:{session_id}",
+        f"session:{session_id}:questions",
+        f"session:{session_id}:answers",
+    ]
+    for qid in question_ids:
+        keys_to_delete.append(f"session:{session_id}:q:{qid}")
+        keys_to_delete.append(f"session:{session_id}:a:{qid}")
+
+    if keys_to_delete:
+        await redis.delete(*keys_to_delete)
+
+    result_doc["id"] = str(result_doc["_id"])
+    del result_doc["_id"]
+    return result_doc

backend/services/interview_service.py

@@ -0,0 +1,227 @@
+import json
+from database import get_db, get_redis
+from models.collections import SESSIONS, JOB_ROLES, SKILLS, QUESTIONS
+from utils.helpers import generate_id, utc_now, str_objectid
+from utils.gemini import generate_interview_question
+
+MAX_QUESTIONS = 10
+SESSION_TTL = 7200  # 2 hours
+
+
+async def start_interview(user_id: str, role_id: str = None) -> dict:
+    """Start a new interview session."""
+    db = get_db()
+    redis = get_redis()
+
+    # Get user skills
+    skills_doc = await db[SKILLS].find_one({"user_id": user_id})
+    skills = skills_doc.get("skills", ["general"]) if skills_doc else ["general"]
+
+    # Get role
+    role_title = "Software Developer"
+    if role_id:
+        from bson import ObjectId
+        role = await db[JOB_ROLES].find_one({"_id": ObjectId(role_id)})
+        if role:
+            role_title = role["title"]
+
+    # Check for existing questions in question bank
+    bank_questions = []
+    if role_id:
+        cursor = db[QUESTIONS].find({"role_id": role_id}).limit(5)
+        async for q in cursor:
+            bank_questions.append(q["question"])
+
+    # Generate first question
+    question_data = await generate_interview_question(
+        skills=skills,
+        role_title=role_title,
+        difficulty="medium",
+    )
+
+    session_id = generate_id()
+    question_id = generate_id()
+
+    # Create session in MongoDB
+    session_doc = {
+        "session_id": session_id,
+        "user_id": user_id,
+        "role_id": role_id,
+        "role_title": role_title,
+        "status": "in_progress",
+        "question_count": 1,
+        "max_questions": MAX_QUESTIONS,
+        "current_difficulty": "medium",
+        "started_at": utc_now(),
+    }
+    await db[SESSIONS].insert_one(session_doc)
+
+    # Store session state in Redis
+    session_state = {
+        "user_id": user_id,
+        "role_title": role_title,
+        "skills": json.dumps(skills),
+        "question_count": 1,
+        "max_questions": MAX_QUESTIONS,
+        "current_difficulty": "medium",
+        "status": "in_progress",
+    }
+    await redis.hset(f"session:{session_id}", mapping=session_state)
+    await redis.expire(f"session:{session_id}", SESSION_TTL)
+
+    # Store question in Redis
+    q_data = {
+        "question_id": question_id,
+        "question": question_data.get("question", "Tell me about yourself."),
+        "difficulty": question_data.get("difficulty", "medium"),
+        "category": question_data.get("category", "general"),
+    }
+    await redis.hset(f"session:{session_id}:q:{question_id}", mapping=q_data)
+    await redis.rpush(f"session:{session_id}:questions", question_id)
+    await redis.expire(f"session:{session_id}:q:{question_id}", SESSION_TTL)
+    await redis.expire(f"session:{session_id}:questions", SESSION_TTL)
+
+    return {
+        "session_id": session_id,
+        "question": {
+            "question_id": question_id,
+            "question": q_data["question"],
+            "difficulty": q_data["difficulty"],
+            "question_number": 1,
+            "total_questions": MAX_QUESTIONS,
+        },
+        "message": "Interview started. Good luck!",
+    }
+
+
+async def submit_answer(session_id: str, question_id: str, answer: str) -> dict:
+    """Submit an answer and generate next question."""
+    db = get_db()
+    redis = get_redis()
+
+    # Get session state from Redis
+    session = await redis.hgetall(f"session:{session_id}")
+    if not session:
+        raise ValueError("Interview session not found or expired")
+
+    if session.get("status") != "in_progress":
+        raise ValueError("Interview is not in progress")
+
+    # Store answer in Redis
+    await redis.hset(f"session:{session_id}:a:{question_id}", mapping={
+        "question_id": question_id,
+        "answer": answer,
+        "submitted_at": utc_now(),
+    })
+    await redis.rpush(f"session:{session_id}:answers", question_id)
+    await redis.expire(f"session:{session_id}:a:{question_id}", SESSION_TTL)
+    await redis.expire(f"session:{session_id}:answers", SESSION_TTL)
+
+    question_count = int(session.get("question_count", 1))
+    max_questions = int(session.get("max_questions", MAX_QUESTIONS))
+
+    # Check if interview is complete
+    if question_count >= max_questions:
+        # Mark session as completed
+        await redis.hset(f"session:{session_id}", "status", "completed")
+        await db[SESSIONS].update_one(
+            {"session_id": session_id},
+            {"$set": {"status": "completed", "completed_at": utc_now()}},
+        )
+        return {
+            "session_id": session_id,
+            "next_question": None,
+            "is_complete": True,
+            "message": "Interview complete! Generating your report...",
+        }
+
+    # Adjust difficulty based on question count
+    difficulty = _adjust_difficulty(question_count, session.get("current_difficulty", "medium"))
+
+    # Get previous questions from Redis
+    question_ids = await redis.lrange(f"session:{session_id}:questions", 0, -1)
+    previous_questions = []
+    for qid in question_ids:
+        q = await redis.hgetall(f"session:{session_id}:q:{qid}")
+        if q:
+            previous_questions.append(q.get("question", ""))
+
+    # Get the current question text for context
+    current_q = await redis.hgetall(f"session:{session_id}:q:{question_id}")
+
+    skills = json.loads(session.get("skills", "[]"))
+    role_title = session.get("role_title", "Software Developer")
+
+    # Generate next question
+    next_question_data = await generate_interview_question(
+        skills=skills,
+        role_title=role_title,
+        previous_questions=previous_questions,
+        previous_answer=answer,
+        difficulty=difficulty,
+    )
+
+    new_question_id = generate_id()
+    new_count = question_count + 1
+
+    # Store new question in Redis
+    q_data = {
+        "question_id": new_question_id,
+        "question": next_question_data.get("question", "Can you elaborate further?"),
+        "difficulty": next_question_data.get("difficulty", difficulty),
+        "category": next_question_data.get("category", "general"),
+    }
+    await redis.hset(f"session:{session_id}:q:{new_question_id}", mapping=q_data)
+    await redis.rpush(f"session:{session_id}:questions", new_question_id)
+    await redis.expire(f"session:{session_id}:q:{new_question_id}", SESSION_TTL)
+
+    # Update session state
+    await redis.hset(f"session:{session_id}", mapping={
+        "question_count": str(new_count),
+        "current_difficulty": difficulty,
+    })
+
+    return {
+        "session_id": session_id,
+        "next_question": {
+            "question_id": new_question_id,
+            "question": q_data["question"],
+            "difficulty": q_data["difficulty"],
+            "question_number": new_count,
+            "total_questions": max_questions,
+        },
+        "is_complete": False,
+        "message": f"Question {new_count} of {max_questions}",
+    }
+
+
+def _adjust_difficulty(question_number: int, current: str) -> str:
+    """Dynamically adjust difficulty based on progress."""
+    if question_number <= 3:
+        return "easy"
+    elif question_number <= 6:
+        return "medium"
+    else:
+        return "hard"
+
+
+async def get_session_qa(session_id: str) -> list:
+    """Get all Q&A pairs from Redis for a session."""
+    redis = get_redis()
+
+    question_ids = await redis.lrange(f"session:{session_id}:questions", 0, -1)
+    qa_pairs = []
+
+    for qid in question_ids:
+        q = await redis.hgetall(f"session:{session_id}:q:{qid}")
+        a = await redis.hgetall(f"session:{session_id}:a:{qid}")
+        if q and a:
+            qa_pairs.append({
+                "question_id": qid,
+                "question": q.get("question", ""),
+                "answer": a.get("answer", ""),
+                "difficulty": q.get("difficulty", "medium"),
+                "category": q.get("category", "general"),
+            })
+
+    return qa_pairs

backend/services/resume_service.py

@@ -0,0 +1,75 @@
+import os
+import aiofiles
+from database import get_db
+from models.collections import RESUMES, SKILLS
+from utils.helpers import utc_now, str_objectid
+from utils.gemini import parse_resume_with_gemini
+from config import get_settings
+
+settings = get_settings()
+
+
+async def upload_and_parse_resume(user_id: str, filename: str, file_content: bytes) -> dict:
+    """Upload resume file, parse with Gemini, extract skills."""
+    db = get_db()
+
+    # Save file locally
+    safe_filename = f"{user_id}_{filename}"
+    file_path = os.path.join(settings.UPLOAD_DIR, safe_filename)
+
+    async with aiofiles.open(file_path, "wb") as f:
+        await f.write(file_content)
+
+    # Read file text (for parsing)
+    resume_text = file_content.decode("utf-8", errors="ignore")
+
+    # Parse with Gemini
+    parsed_data = await parse_resume_with_gemini(resume_text)
+    skills = parsed_data.get("skills", [])
+
+    # Upsert resume document
+    resume_doc = {
+        "user_id": user_id,
+        "filename": safe_filename,
+        "original_filename": filename,
+        "file_path": file_path,
+        "parsed_text": parsed_data.get("experience_summary", ""),
+        "parsed_data": parsed_data,
+        "uploaded_at": utc_now(),
+    }
+
+    await db[RESUMES].update_one(
+        {"user_id": user_id},
+        {"$set": resume_doc},
+        upsert=True,
+    )
+
+    # Upsert skills
+    await db[SKILLS].update_one(
+        {"user_id": user_id},
+        {"$set": {
+            "user_id": user_id,
+            "skills": skills,
+            "updated_at": utc_now(),
+        }},
+        upsert=True,
+    )
+
+    result = await db[RESUMES].find_one({"user_id": user_id})
+    return {
+        "id": str(result["_id"]),
+        "user_id": user_id,
+        "filename": filename,
+        "parsed_text": resume_doc["parsed_text"],
+        "skills": skills,
+        "uploaded_at": resume_doc["uploaded_at"],
+    }
+
+
+async def get_user_skills(user_id: str) -> list:
+    """Get extracted skills for a user."""
+    db = get_db()
+    skills_doc = await db[SKILLS].find_one({"user_id": user_id})
+    if skills_doc:
+        return skills_doc.get("skills", [])
+    return []

backend/utils/gemini.py

@@ -0,0 +1,150 @@
+from google import genai
+from config import get_settings
+
+settings = get_settings()
+
+client = genai.Client(api_key=settings.GEMINI_API_KEY)
+
+
+async def call_gemini(prompt: str, system_instruction: str = None) -> str:
+    """Call Gemini API with a prompt and optional system instruction."""
+    config = {}
+    if system_instruction:
+        config["system_instruction"] = system_instruction
+
+    response = client.models.generate_content(
+        model=settings.GEMINI_MODEL,
+        contents=prompt,
+        config=config if config else None,
+    )
+    return response.text
+
+
+async def parse_resume_with_gemini(resume_text: str) -> dict:
+    """Parse resume text and extract structured data using Gemini."""
+    prompt = f"""Analyze the following resume and extract structured information.
+Return a JSON object with these fields:
+- "skills": list of technical and soft skills
+- "experience_summary": brief summary of work experience
+- "education": list of educational qualifications
+- "projects": list of notable projects
+
+Resume text:
+---
+{resume_text}
+---
+
+Return ONLY valid JSON, no markdown formatting."""
+
+    result = await call_gemini(prompt)
+    # Clean up markdown code blocks if present
+    result = result.strip()
+    if result.startswith("```"):
+        result = result.split("\n", 1)[1]
+    if result.endswith("```"):
+        result = result.rsplit("```", 1)[0]
+    result = result.strip()
+
+    import json
+    try:
+        return json.loads(result)
+    except json.JSONDecodeError:
+        return {"skills": [], "experience_summary": result, "education": [], "projects": []}
+
+
+async def generate_interview_question(
+    skills: list,
+    role_title: str,
+    previous_questions: list = None,
+    previous_answer: str = None,
+    difficulty: str = "medium",
+) -> dict:
+    """Generate an interview question using Gemini."""
+    context = f"Role: {role_title}\nCandidate Skills: {', '.join(skills)}\nDifficulty: {difficulty}"
+
+    if previous_questions:
+        context += f"\n\nPrevious questions asked (do NOT repeat these):\n"
+        for i, q in enumerate(previous_questions, 1):
+            context += f"{i}. {q}\n"
+
+    if previous_answer:
+        context += f"\nCandidate's last answer: {previous_answer}"
+        context += "\nGenerate a follow-up question based on this answer to probe deeper."
+
+    prompt = f"""{context}
+
+Generate ONE interview question for this candidate. The question should:
+1. Be relevant to the role and candidate's skills
+2. Match the {difficulty} difficulty level
+3. Be clear and specific
+4. Test practical knowledge
+
+Return ONLY a JSON object with:
+- "question": the interview question text
+- "difficulty": "{difficulty}"
+- "category": the skill category this tests
+
+Return ONLY valid JSON, no markdown formatting."""
+
+    result = await call_gemini(prompt)
+    result = result.strip()
+    if result.startswith("```"):
+        result = result.split("\n", 1)[1]
+    if result.endswith("```"):
+        result = result.rsplit("```", 1)[0]
+    result = result.strip()
+
+    import json
+    try:
+        return json.loads(result)
+    except json.JSONDecodeError:
+        return {
+            "question": f"Tell me about your experience with {skills[0] if skills else 'software development'}.",
+            "difficulty": difficulty,
+            "category": "general",
+        }
+
+
+async def evaluate_interview(questions_and_answers: list, role_title: str) -> dict:
+    """Batch evaluate all interview Q&A pairs using Gemini."""
+    qa_text = ""
+    for i, qa in enumerate(questions_and_answers, 1):
+        qa_text += f"\nQ{i}: {qa['question']}\nA{i}: {qa['answer']}\n"
+
+    prompt = f"""You are an expert technical interviewer evaluating a candidate for the role: {role_title}
+
+Here are the interview questions and the candidate's answers:
+{qa_text}
+
+Evaluate the candidate and return a JSON object with:
+- "overall_score": integer from 0-100
+- "detailed_scores": list of objects, each with:
+  - "question": the question text
+  - "answer": the answer text
+  - "score": integer 0-100
+  - "feedback": specific feedback for this answer
+- "strengths": list of 3-5 strength areas
+- "weaknesses": list of 3-5 areas for improvement
+- "recommendations": list of 3-5 actionable recommendations
+
+Be fair but thorough. Return ONLY valid JSON, no markdown formatting."""
+
+    result = await call_gemini(prompt)
+    result = result.strip()
+    if result.startswith("```"):
+        result = result.split("\n", 1)[1]
+    if result.endswith("```"):
+        result = result.rsplit("```", 1)[0]
+    result = result.strip()
+
+    import json
+    try:
+        return json.loads(result)
+    except json.JSONDecodeError:
+        return {
+            "overall_score": 50,
+            "detailed_scores": [],
+            "strengths": ["Unable to evaluate"],
+            "weaknesses": ["Unable to evaluate"],
+            "recommendations": ["Please retry the interview"],
+        }

backend/utils/helpers.py

@@ -0,0 +1,26 @@
+from bson import ObjectId
+from datetime import datetime, timezone
+import uuid
+
+
+def generate_id() -> str:
+    """Generate a unique string ID."""
+    return str(uuid.uuid4())
+
+
+def utc_now() -> str:
+    """Get current UTC timestamp as ISO string."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def str_objectid(doc: dict) -> dict:
+    """Convert MongoDB ObjectId to string in a document."""
+    if doc and "_id" in doc:
+        doc["id"] = str(doc["_id"])
+        del doc["_id"]
+    return doc
+
+
+def str_objectids(docs: list) -> list:
+    """Convert MongoDB ObjectIds to strings in a list of documents."""
+    return [str_objectid(doc) for doc in docs]