# thirumoorthy369/vicodathon-the-interview-agent architecture

> Architecture diagram of the GitHub repository thirumoorthy369/vicodathon-the-interview-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thirumoorthy369/vicodathon-the-interview-agent
- Repository: https://github.com/thirumoorthy369/vicodathon-the-interview-agent

## Overview

#### 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`

Main entry points: [`backend/server.js`](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/server.js) (Express interview API), [`frontend/src/App.jsx`](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/App.jsx) (App state and routing), [`backend/groq.js`](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/groq.js) (Groq model adapter), [`backend/planner.js`](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/planner.js) (Curriculum planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_entry["Vite client entry<br/>React bootstrap<br/>[main.jsx]"]
  node_app["App state and routing<br/>client orchestrator<br/>[App.jsx]"]
  node_landing["Candidate selection<br/>landing screen<br/>[LandingScreen.jsx]"]
  node_interview_ui["Live interview chat<br/>interview screen"]
  node_feedback_ui["Assessment scorecard<br/>feedback screen<br/>[FeedbackScreen.jsx]"]
  node_local_storage[("Refresh persistence<br/>browser localStorage")]
end

subgraph group_service["Interview service"]
  node_api_server["Express interview API<br/>Node service entry<br/>[server.js]"]
  node_sessions[("Active interview sessions<br/>in-memory session store<br/>[server.js]")]
  node_planner["Curriculum planner<br/>deterministic planner<br/>[planner.js]"]
  node_groq_adapter["Groq model adapter<br/>LLM integration<br/>[groq.js]"]
  node_prompt_contract["Prompt contract<br/>prompt specification<br/>[PROMPTS.md]"]
end

subgraph group_data["Personalization data"]
  node_candidates[("Candidate learning history<br/>candidate records<br/>[candidates.json]")]
  node_curriculum[("31-day curriculum<br/>curriculum data<br/>[curriculum.json]")]
end

node_groq{{"Groq-hosted Llama<br/>external model service"}}
node_vercel{{"Vercel<br/>frontend hosting"}}
node_railway{{"Railway<br/>backend hosting"}}

node_client_entry -->|"mounts"| node_app
node_app -->|"shows"| node_landing
node_app -->|"runs session"| node_interview_ui
node_app -->|"shows completion"| node_feedback_ui
node_app -->|"restores and persists"| node_local_storage
node_landing -->|"starts assessment"| node_api_server
node_interview_ui -->|"submits answers"| node_api_server
node_api_server -->|"creates and updates"| node_sessions
node_api_server -->|"requests plan"| node_planner
node_planner -->|"prioritizes history"| node_candidates
node_planner -->|"selects modules"| node_curriculum
node_api_server -->|"evaluates turns"| node_groq_adapter
node_groq_adapter -->|"uses plan and transcript"| node_sessions
node_groq_adapter -.->|"follows prompts"| node_prompt_contract
node_groq_adapter -->|"model invocation"| node_groq
node_vercel -.->|"serves"| node_client_entry
node_railway -.->|"hosts"| node_api_server

click node_client_entry "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/App.jsx"
click node_landing "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/components/LandingScreen.jsx"
click node_interview_ui "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/components/InterviewScreen.jsx"
click node_feedback_ui "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/components/FeedbackScreen.jsx"
click node_api_server "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/server.js"
click node_sessions "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/server.js"
click node_planner "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/planner.js"
click node_groq_adapter "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/groq.js"
click node_prompt_contract "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/PROMPTS.md"
click node_candidates "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/data/candidates.json"
click node_curriculum "https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/data/curriculum.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_entry,node_app,node_landing,node_interview_ui,node_feedback_ui,node_local_storage toneBlue
class node_api_server,node_sessions,node_planner,node_groq_adapter,node_prompt_contract toneAmber
class node_candidates,node_curriculum toneMint
class node_groq,node_vercel,node_railway toneNeutral
```

## Components

### React client

- [Vite client entry](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/main.jsx): React bootstrap · `frontend/src/main.jsx`
- [App state and routing](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/App.jsx): client orchestrator · Coordinates screens, API calls, and refresh restoration. · `frontend/src/App.jsx`
- [Candidate selection](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/components/LandingScreen.jsx): landing screen · `frontend/src/components/LandingScreen.jsx`
- [Live interview chat](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/components/InterviewScreen.jsx): interview screen · Submits answers and manages chat focus behavior. · `frontend/src/components/InterviewScreen.jsx`
- [Assessment scorecard](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/frontend/src/components/FeedbackScreen.jsx): feedback screen · Shows strengths, gaps, and study guidance. · `frontend/src/components/FeedbackScreen.jsx`
- **Refresh persistence**: browser localStorage · Retains client state across refreshes.

### Interview service

- [Express interview API](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/server.js): Node service entry · Owns endpoints, CORS integration, and session lifecycle. · `backend/server.js`
- [Active interview sessions](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/server.js): in-memory session store · Stores plan, transcript, and turn state; evicts idle sessions after 30 minutes. · `backend/server.js`
- [Curriculum planner](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/planner.js): deterministic planner · Builds an 8–14 question, multi-module prioritized plan. · `backend/planner.js`
- [Groq model adapter](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/groq.js): LLM integration · Invokes Groq-hosted Llama with plan and conversation history. · `backend/groq.js`
- [Prompt contract](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/PROMPTS.md): prompt specification · `PROMPTS.md`

### Personalization data

- [Candidate learning history](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/data/candidates.json): candidate records · Provides skipped, failed, passed-first-try, and capstone status. · `backend/data/candidates.json`
- [31-day curriculum](https://github.com/thirumoorthy369/vicodathon-the-interview-agent/blob/main/backend/data/curriculum.json): curriculum data · `backend/data/curriculum.json`

### Other components

- **Groq-hosted Llama**: external model service
- **Vercel**: frontend hosting
- **Railway**: backend hosting

## Connections

- Vite client entry → App state and routing: mounts
- App state and routing → Candidate selection: shows
- App state and routing → Live interview chat: runs session
- App state and routing → Assessment scorecard: shows completion
- App state and routing → Refresh persistence: restores and persists
- Candidate selection → Express interview API: starts assessment
- Live interview chat → Express interview API: submits answers
- Express interview API → Active interview sessions: creates and updates
- Express interview API → Curriculum planner: requests plan
- Curriculum planner → Candidate learning history: prioritizes history
- Curriculum planner → 31-day curriculum: selects modules
- Express interview API → Groq model adapter: evaluates turns
- Groq model adapter → Active interview sessions: uses plan and transcript
- Groq model adapter → Prompt contract: follows prompts
- Groq model adapter → Groq-hosted Llama: model invocation
- Vercel → Vite client entry: serves
- Railway → Express interview API: hosts