docs/collaboration.md

Collaboration Handoff — AI InterviewMentor

READ THIS FIRST before touching any code. Two developers are working on this project simultaneously using Claude Code. This file tracks what has been done, who owns what, and the exact API contracts each side expects.

---

Who Owns What

Area	Owner	Status
Phases 1–4 (scaffolding, auth, instructor batch/topics, CSV upload)	Done	✅
Phase 5 — LangGraph backend engine	Other dev	🔄 In progress
Phases 6–9 (student UI, reports, dashboards, analytics)	This dev	✅ Done
Phase 10 — Docker + deploy	Shared	⏳ Pending

Rule: Do not touch files owned by the other dev without coordinating first.

---

Phase 5 — What the Backend Must Deliver (Other Dev's Contract)

The frontend (Phases 6–7) is already wired to these endpoints. Do not change the request/response shapes.

POST /api/interview/start

Request: { "topic_id": "<uuid>" } Response: { "session_id": "<uuid>", "message": "<first AI question>" }

Behaviour:

• Creates a row in interview_sessions with status='active'
• Initialises LangGraph state with thread_id = session_id
• Returns the first AI question as message

POST /api/interview/turn

Request: { "session_id": "<uuid>", "answer": "<student text>" } Response: { "message": "<AI response or next question>", "turn_count": <int>, "status": "ongoing"|"finished" }

Behaviour:

• Appends the student answer + AI response to LangGraph state
• When interview ends: sets interview_sessions.status='completed', writes score and feedback JSON
• Returns "finished" status when done (max 8 turns or question bank exhausted)

GET /api/interview/state/{session_id}

Response:

{
  "id": "<uuid>",
  "topic_id": "<uuid>",
  "status": "ongoing|finished",
  "turn_count": 3,
  "messages": [{"role": "ai|student", "content": "..."}]
}

Behaviour: used to resume a session after tab close/reload.

feedback JSONB shape (written to interview_sessions.feedback)

The frontend's Feedback type expects:

{
  "score": 82,
  "summary": "Good understanding of concepts...",
  "concept_score": 80,
  "depth_score": 85,
  "mistakes": ["Missed edge case in X", "..."],
  "tips": ["Strong on Y", "..."]
}

---

Routers Already Registered in backend/main.py

/api/auth/*       — auth.router      (signup, login, refresh, logout)
/api/batches/*    — batches.router   (create, get mine, get by id)
/api/topics/*     — topics.router    (create, list, unlock/lock)
/api/upload       — upload.router    (CSV parse + bulk insert)
/api/student/*    — student.router   (topics for student, sessions list)
/api/sessions/*   — sessions.router  (get session detail/report)
/api/instructor/* — instructor.router (student list + detail)

Phase 5 must also register:

from backend.routers import interview
app.include_router(interview.router, prefix="/api/interview")

---

Completed Frontend Files (Do Not Overwrite)

API Layer (frontend/src/api/)

File	Functions
auth.ts	login, signup, logout, refreshToken
client.ts	apiFetch — returns Promise<Response>, auto-refreshes on 401
topics.ts	getMyBatch, createBatch, getTopics, createTopic, setTopicUnlock, getStudentTopics, getStudentSessions
interview.ts	startInterview(topicId), sendTurn(sessionId, answer), getInterviewState(sessionId)
sessions.ts	getSession(sessionId)
upload.ts	uploadCSV(topicId, file)
student.ts	getStudentDashboard()
instructor.ts	getInstructorStudents(), getStudentDetail(studentId)

Store (frontend/src/store/)

File	State
authStore.ts	accessToken, user, setAuth, clearAuth — persisted to localStorage
interviewStore.ts	sessionId, messages, turnCount, status, startSession, addMessage, setTurnCount, setStatus, reset

Pages (frontend/src/pages/)

All pages implemented: Login, Signup, StudentDashboard, Interview, Report, InstructorDashboard, Upload, StudentDetail

Types (frontend/src/types/index.ts)

User, AuthResponse, Message, Feedback, InterviewSession, SessionReport, StudentSession, StudentTopic, InstructorStudent, StudentAttempt

---

Key Patterns to Follow

apiFetch usage (always check .ok):

const res = await apiFetch('/api/something')
if (!res.ok) {
  const err = await res.json()
  throw new Error(err.detail ?? 'Request failed')
}
return res.json()

Tailwind dark theme conventions:

• Page bg: bg-gray-950
• Card: bg-gray-900 border border-gray-800 rounded-xl
• Input: bg-gray-800 border border-gray-700 rounded-lg focus:border-indigo-500
• Primary button: bg-indigo-600 hover:bg-indigo-500
• Muted text: text-gray-400, text-gray-500

Backend router pattern:

from fastapi import APIRouter, Depends, HTTPException
from backend.auth.deps import require_student  # or require_instructor
from backend.db import queries

router = APIRouter()
# user dict has: user_id, role, batch_id, email

---

DB Schema Reference

users          — id, full_name, email, password_hash, role, batch_id, created_at
batches        — id, name, instructor_id, class_code, created_at
topics         — id, batch_id, name, is_unlocked, order_index, created_at
questions      — id, topic_id, question_text, difficulty, created_at
interview_sessions — id, student_id, topic_id, status('active'|'completed'), score, feedback(JSONB), started_at, completed_at
refresh_tokens — id, user_id, token_hash, expires_at