thirumoorthy369/vicodathon-the-interview-agent

Purpose and runtime topology

ViCoDathon is an adaptive AI technical-interview application. A React/Vite single-page client selects a candidate, runs a multi-turn interview, and displays a final scorecard. An Express/Node backend plans personalized questions, holds active sessions in memory, and calls Groq-hosted Llama models. Production deploys frontend to Vercel and backend to Railway.

Paths: frontend/src/main.jsx, backend/server.js, backend/package.json

Client entry and screen orchestration

frontend/src/main.jsx mounts the application; frontend/src/App.jsx is the primary client state/router boundary. It coordinates candidate selection, active interview/session state, localStorage restoration across refreshes, API calls, and transition between the landing, interview, and feedback screens.

Paths: frontend/src/main.jsx, frontend/src/App.jsx, frontend/src/App.css

Candidate-selection stage

The landing screen renders available candidate records and starts an assessment for the chosen profile. Candidate learning history is the central personalization input: skipped, failed, passed-first-try, and capstone status are used later by the backend planner rather than encoded as static frontend questions.

Paths: frontend/src/components/LandingScreen.jsx, backend/data/candidates.json, backend/data/curriculum.json

Personalization planning boundary

The deterministic planner converts candidate metadata plus the 31-day curriculum into a prioritized interview plan: 8–14 questions spanning at least four modules, with higher emphasis on skipped/failed material and a capstone anchor. This separates curriculum-aware question selection from LLM-driven conversational adaptation.

Paths: backend/planner.js, backend/data/candidates.json, backend/data/curriculum.json

Interview API, session lifecycle, and LLM turns

Express in backend/server.js is the service entry point and owns API endpoints, CORS/front-end origin integration, and in-memory interview sessions. Sessions retain the plan, transcript/history, and turn state; an idle-eviction process removes sessions after 30 minutes. Each submitted answer is evaluated in conversation context to either issue a targeted follow-up, advance the plan, or conclude at the required turn threshold.

Paths: backend/server.js, backend/groq.js, backend/planner.js

Model integration and prompt boundary

backend/groq.js encapsulates Groq SDK access and model invocation, using GROQ_API_KEY supplied outside source control. The model receives the structured plan and conversation history to produce text-anchored follow-ups and the final assessment; backend logic remains responsible for session/control constraints rather than delegating lifecycle decisions entirely to the model.

Paths: backend/groq.js, backend/.env.example, PROMPTS.md

Interview and feedback presentation

The interview screen is the live chat interface, including answer submission and focus behavior. The feedback screen presents the completed assessment as strengths, knowledge gaps, and curriculum-linked study guidance. These are presentation boundaries; authoritative transcript and interview progression remain backend-session concerns, while localStorage provides client refresh resilience.

Paths: frontend/src/components/InterviewScreen.jsx, frontend/src/components/FeedbackScreen.jsx, frontend/src/components/InterviewScreen.css