# sapthamikotian/athena architecture

> Architecture diagram of the GitHub repository sapthamikotian/athena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sapthamikotian/athena
- Repository: https://github.com/sapthamikotian/athena

## Overview

Athena is a personalized technical-interview web app. A candidate is selected in the frontend and sent to the interview endpoint to start a session; subsequent answers go through the same endpoint, where retrieval and interview control shape the next question until coverage guardrails allow final feedback. The graph separates the web/API, interview orchestration, topic/session logic, and grounding/LLM services. The README documents the NVIDIA NIM integration and the 8-question/4-day floor; sampled code shows the routing and core calls. The frontend excerpt is partial, so UI details beyond its candidate loading and interview requests are omitted.

Main entry points: [`src/index.ts`](https://github.com/sapthamikotian/athena/blob/main/src/index.ts) (Interview API), [`src/handlers.ts`](https://github.com/sapthamikotian/athena/blob/main/src/handlers.ts) (Interview handlers), [`frontend/app.js`](https://github.com/sapthamikotian/athena/blob/main/frontend/app.js) (Interview UI), [`src/vectorStore.ts`](https://github.com/sapthamikotian/athena/blob/main/src/vectorStore.ts) (Curriculum vector store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and API"]
  node_frontend["Interview UI<br/>[app.js]"]
  node_candidate_data["Candidate profiles<br/>[candidates.json]"]
  node_api["Interview API<br/>[index.ts]"]
  node_validation["Request validation<br/>[utils.ts]"]
end

subgraph group_interview["Interview orchestration"]
  node_handlers["Interview handlers<br/>[handlers.ts]"]
end

subgraph group_planning["Topic and session"]
  node_session[("Session state<br/>[session.ts]")]
  node_topics["Topic planning<br/>[topics.ts]"]
  node_curriculum_data["Curriculum lookup<br/>[data.ts]"]
  node_curriculum["Curriculum content<br/>[curriculum.json]"]
end

subgraph group_grounding["Grounding and generation"]
  node_rag["Grounding and memory<br/>[rag.ts]"]
  node_vector_store[("Curriculum vector store<br/>[vectorStore.ts]")]
  node_llm["Interview and feedback generation<br/>[llm.ts]"]
end

node_candidate(("Interviewer user"))
node_nim{{"NVIDIA NIM"}}

node_candidate -->|"uses"| node_frontend
node_frontend -->|"loads profiles"| node_candidate_data
node_frontend -->|"starts and sends turns"| node_api
node_api -->|"returns replies"| node_frontend
node_api -->|"validates requests"| node_validation
node_api -->|"routes requests"| node_handlers
node_api -->|"initializes store"| node_vector_store
node_api -->|"initializes client"| node_llm
node_handlers -->|"creates and advances"| node_session
node_handlers -->|"retrieves and updates memory"| node_rag
node_handlers -->|"requests turns and feedback"| node_llm
node_session -->|"builds topic queue"| node_topics
node_topics -->|"looks up day details"| node_curriculum_data
node_curriculum_data -->|"loads curriculum"| node_curriculum
node_vector_store -->|"embeds curriculum days"| node_curriculum_data
node_rag -->|"embeds and queries"| node_vector_store
node_vector_store -->|"requests embeddings"| node_nim
node_llm -.->|"requests interview generation"| node_nim

click node_frontend "https://github.com/sapthamikotian/athena/blob/main/frontend/app.js"
click node_candidate_data "https://github.com/sapthamikotian/athena/blob/main/candidates.json"
click node_api "https://github.com/sapthamikotian/athena/blob/main/src/index.ts"
click node_validation "https://github.com/sapthamikotian/athena/blob/main/src/utils.ts"
click node_handlers "https://github.com/sapthamikotian/athena/blob/main/src/handlers.ts"
click node_session "https://github.com/sapthamikotian/athena/blob/main/src/session.ts"
click node_topics "https://github.com/sapthamikotian/athena/blob/main/src/topics.ts"
click node_curriculum_data "https://github.com/sapthamikotian/athena/blob/main/src/data.ts"
click node_curriculum "https://github.com/sapthamikotian/athena/blob/main/curriculum.json"
click node_rag "https://github.com/sapthamikotian/athena/blob/main/src/rag.ts"
click node_vector_store "https://github.com/sapthamikotian/athena/blob/main/src/vectorStore.ts"
click node_llm "https://github.com/sapthamikotian/athena/blob/main/src/llm.ts"

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_frontend,node_candidate_data,node_api,node_validation,node_candidate toneBlue
class node_handlers toneAmber
class node_session,node_topics,node_curriculum_data,node_curriculum toneMint
class node_rag,node_vector_store,node_llm toneRose
class node_nim toneIndigo
```

## Components

### Web and API

- [Interview UI](https://github.com/sapthamikotian/athena/blob/main/frontend/app.js): `frontend/app.js`
- [Candidate profiles](https://github.com/sapthamikotian/athena/blob/main/candidates.json): `candidates.json`
- [Interview API](https://github.com/sapthamikotian/athena/blob/main/src/index.ts): `src/index.ts`
- [Request validation](https://github.com/sapthamikotian/athena/blob/main/src/utils.ts): `src/utils.ts`

### Interview orchestration

- [Interview handlers](https://github.com/sapthamikotian/athena/blob/main/src/handlers.ts): `src/handlers.ts`

### Topic and session

- [Session state](https://github.com/sapthamikotian/athena/blob/main/src/session.ts): `src/session.ts`
- [Topic planning](https://github.com/sapthamikotian/athena/blob/main/src/topics.ts): `src/topics.ts`
- [Curriculum lookup](https://github.com/sapthamikotian/athena/blob/main/src/data.ts): `src/data.ts`
- [Curriculum content](https://github.com/sapthamikotian/athena/blob/main/curriculum.json): `curriculum.json`

### Grounding and generation

- [Grounding and memory](https://github.com/sapthamikotian/athena/blob/main/src/rag.ts): `src/rag.ts`
- [Curriculum vector store](https://github.com/sapthamikotian/athena/blob/main/src/vectorStore.ts): `src/vectorStore.ts`
- [Interview and feedback generation](https://github.com/sapthamikotian/athena/blob/main/src/llm.ts): `src/llm.ts`

### Other components

- **Interviewer user**
- **NVIDIA NIM**

## Connections

- Interviewer user → Interview UI: uses (evidence: `frontend/app.js`)
- Interview UI → Candidate profiles: loads profiles (evidence: `frontend/app.js`)
- Interview UI → Interview API: starts and sends turns (evidence: `frontend/app.js`)
- Interview API → Interview UI: returns replies (evidence: `src/index.ts`)
- Interview API → Request validation: validates requests (evidence: `src/index.ts`)
- Interview API → Interview handlers: routes requests (evidence: `src/index.ts`)
- Interview API → Curriculum vector store: initializes store (evidence: `src/index.ts`)
- Interview API → Interview and feedback generation: initializes client (evidence: `src/index.ts`)
- Interview handlers → Session state: creates and advances (evidence: `src/handlers.ts`)
- Interview handlers → Grounding and memory: retrieves and updates memory (evidence: `src/handlers.ts`)
- Interview handlers → Interview and feedback generation: requests turns and feedback (evidence: `src/handlers.ts`)
- Session state → Topic planning: builds topic queue (evidence: `src/session.ts`)
- Topic planning → Curriculum lookup: looks up day details (evidence: `src/topics.ts`)
- Curriculum lookup → Curriculum content: loads curriculum (evidence: `src/data.ts`)
- Curriculum vector store → Curriculum lookup: embeds curriculum days (evidence: `src/vectorStore.ts`)
- Grounding and memory → Curriculum vector store: embeds and queries (evidence: `src/rag.ts`)
- Curriculum vector store → NVIDIA NIM: requests embeddings (evidence: `src/vectorStore.ts`)
- Interview and feedback generation → NVIDIA NIM: requests interview generation
