# han-dreamer/ai-mock-interview architecture

> Architecture diagram of the GitHub repository han-dreamer/ai-mock-interview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/han-dreamer/ai-mock-interview
- Repository: https://github.com/han-dreamer/ai-mock-interview

## Overview

AI Mock Interview is a JD- and resume-driven interview practice product. A candidate uses the web client to authenticate and create or resume a practice or professional session; the API delegates session execution to a LangGraph workflow, which analyzes inputs, plans questions, retrieves relevant material, conducts answer-and-follow-up loops, and produces a report. The README documents persistence, long-term personalization, and Redis runtime enhancements. Edges reflect that documentation and sampled source; unsampled subsystem wiring is omitted where uncertain.

Main entry points: [`app/agents/graph.py`](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/graph.py) (Interview StateGraph), [`app/services/session_manager.py`](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/session_manager.py) (Session Manager), [`app/memory/service.py`](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/memory/service.py) (Long-Term Memory Service), [`app/main.py`](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/main.py) (FastAPI Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_web["React Web Client<br/>[App.tsx]"]
end

subgraph group_api["API and Sessions"]
  node_api_entry["FastAPI Application<br/>[main.py]"]
  node_auth["Auth API<br/>[auth.py]"]
  node_rest["Interview REST API<br/>[interview_rest.py]"]
  node_ws["Interview WebSocket<br/>[interview_ws.py]"]
  node_session["Session Manager<br/>[session_manager.py]"]
end

subgraph group_interview["Interview Workflow"]
  node_resume["Resume Analysis<br/>[resume_analyst.py]"]
  node_jd["JD Analysis<br/>[jd_analyst.py]"]
  node_parallel["Parallel Preparation<br/>[parallel_prep.py]"]
  node_workflow["Interview StateGraph<br/>[graph.py]"]
  node_planner["Question Planner"]
  node_interviewer["Question and Assessment<br/>[interviewer.py]"]
  node_evaluator["Round Evaluator<br/>[evaluator.py]"]
  node_report["Report Generation"]
end

subgraph group_knowledge["Knowledge and Memory"]
  node_resume_tools["Resume Parsing and Matching<br/>[parser.py]"]
  node_query["Retrieval Query Builder<br/>[query_builder.py]"]
  node_retriever["Hybrid RAG Retriever<br/>[retriever.py]"]
  node_vector_index[("Question Vector Index<br/>[vector_store.py]")]
  node_memory["Long-Term Memory Service<br/>[service.py]"]
  node_memory_store[("Memory Stores<br/>[store.py]")]
  node_memory_vector[("Memory Vector Store<br/>[vector_store.py]")]
end

subgraph group_runtime["Persistence and Services"]
  node_session_repo[("Session Repository")]
  node_checkpoint[("Graph Checkpoint<br/>[checkpoint.py]")]
  node_redis[("Redis Runtime Features<br/>[redis_client.py]")]
end

node_candidate(("Candidate"))
node_llm{{"LLM and Embedding Provider"}}
node_postgres[("PostgreSQL")]
node_chroma[("ChromaDB")]

node_candidate -->|"uses"| node_web
node_web -->|"requests"| node_api_entry
node_api_entry -->|"routes auth"| node_auth
node_api_entry -->|"routes REST"| node_rest
node_api_entry -->|"routes WebSocket"| node_ws
node_rest -->|"manages sessions"| node_session
node_ws -->|"manages sessions"| node_session
node_session -->|"starts or resumes"| node_workflow
node_workflow -->|"prepares professional mode"| node_parallel
node_parallel -->|"analyzes JD"| node_jd
node_parallel -->|"analyzes resume"| node_resume
node_resume -->|"parses and matches"| node_resume_tools
node_workflow -->|"analyzes practice JD"| node_jd
node_workflow -->|"plans questions"| node_planner
node_workflow -->|"asks and assesses"| node_interviewer
node_workflow -->|"summarizes and evaluates"| node_evaluator
node_planner -->|"builds retrieval queries"| node_query
node_planner -->|"retrieves questions"| node_retriever
node_retriever -->|"searches"| node_vector_index
node_vector_index -->|"stores vectors"| node_chroma
node_retriever -->|"requests embeddings"| node_llm
node_planner -->|"recalls personalization"| node_memory
node_interviewer -->|"records answer episodes"| node_memory
node_evaluator -->|"saves reflections"| node_memory
node_memory -->|"reads and writes"| node_memory_store
node_memory -->|"indexes and recalls"| node_memory_vector
node_memory_store -->|"persists production memory"| node_postgres
node_memory_vector -->|"pgvector production index"| node_postgres
node_workflow -->|"generates interview content"| node_llm
node_session -->|"persists session state"| node_session_repo
node_session_repo -->|"reads and writes"| node_postgres
node_workflow -->|"saves graph state"| node_checkpoint
node_checkpoint -->|"checkpoints"| node_postgres
node_session -.->|"uses runtime enhancements"| node_redis
node_workflow -->|"generates final report"| node_report
node_report -->|"returns report"| node_session

click node_web "https://github.com/han-dreamer/ai-mock-interview/blob/main/web/src/App.tsx"
click node_api_entry "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/main.py"
click node_auth "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/api/auth.py"
click node_rest "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/api/interview_rest.py"
click node_ws "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/api/interview_ws.py"
click node_session "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/session_manager.py"
click node_resume "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/resume_analyst.py"
click node_jd "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/jd_analyst.py"
click node_parallel "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/parallel_prep.py"
click node_workflow "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/graph.py"
click node_planner "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/question_planner.py"
click node_interviewer "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/interviewer.py"
click node_evaluator "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/evaluator.py"
click node_report "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/report_generator.py"
click node_resume_tools "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/resume/parser.py"
click node_query "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/rag/query_builder.py"
click node_retriever "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/rag/retriever.py"
click node_vector_index "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/rag/vector_store.py"
click node_memory "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/memory/service.py"
click node_memory_store "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/memory/store.py"
click node_memory_vector "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/memory/vector_store.py"
click node_session_repo "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/session_repository.py"
click node_checkpoint "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/checkpoint.py"
click node_redis "https://github.com/han-dreamer/ai-mock-interview/blob/main/app/cache/redis_client.py"

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_web toneBlue
class node_api_entry,node_auth,node_rest,node_ws,node_session,node_postgres,node_chroma toneAmber
class node_resume,node_jd,node_parallel,node_workflow,node_planner,node_interviewer,node_evaluator,node_report toneMint
class node_resume_tools,node_query,node_retriever,node_vector_index,node_memory,node_memory_store,node_memory_vector toneRose
class node_session_repo,node_checkpoint,node_redis,node_candidate,node_llm toneIndigo
```

## Components

### Client

- [React Web Client](https://github.com/han-dreamer/ai-mock-interview/blob/main/web/src/App.tsx): `web/src/App.tsx`

### API and Sessions

- [FastAPI Application](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/main.py): `app/main.py`
- [Auth API](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/api/auth.py): `app/api/auth.py`
- [Interview REST API](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/api/interview_rest.py): `app/api/interview_rest.py`
- [Interview WebSocket](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/api/interview_ws.py): `app/api/interview_ws.py`
- [Session Manager](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/session_manager.py): `app/services/session_manager.py`

### Interview Workflow

- [Resume Analysis](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/resume_analyst.py): `app/agents/resume_analyst.py`
- [JD Analysis](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/jd_analyst.py): `app/agents/jd_analyst.py`
- [Parallel Preparation](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/parallel_prep.py): `app/agents/parallel_prep.py`
- [Interview StateGraph](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/graph.py): `app/agents/graph.py`
- [Question Planner](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/question_planner.py): `app/agents/question_planner.py`
- [Question and Assessment](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/interviewer.py): `app/agents/interviewer.py`
- [Round Evaluator](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/agents/evaluator.py): `app/agents/evaluator.py`
- [Report Generation](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/report_generator.py): `app/services/report_generator.py`

### Knowledge and Memory

- [Resume Parsing and Matching](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/resume/parser.py): `app/resume/parser.py`
- [Retrieval Query Builder](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/rag/query_builder.py): `app/rag/query_builder.py`
- [Hybrid RAG Retriever](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/rag/retriever.py): `app/rag/retriever.py`
- [Question Vector Index](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/rag/vector_store.py): `app/rag/vector_store.py`
- [Long-Term Memory Service](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/memory/service.py): `app/memory/service.py`
- [Memory Stores](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/memory/store.py): `app/memory/store.py`
- [Memory Vector Store](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/memory/vector_store.py): `app/memory/vector_store.py`

### Persistence and Services

- [Session Repository](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/session_repository.py): `app/services/session_repository.py`
- [Graph Checkpoint](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/services/checkpoint.py): `app/services/checkpoint.py`
- [Redis Runtime Features](https://github.com/han-dreamer/ai-mock-interview/blob/main/app/cache/redis_client.py): `app/cache/redis_client.py`

### Other components

- **Candidate**
- **LLM and Embedding Provider**
- **PostgreSQL**
- **ChromaDB**

## Connections

- Candidate → React Web Client: uses
- React Web Client → FastAPI Application: requests
- FastAPI Application → Auth API: routes auth
- FastAPI Application → Interview REST API: routes REST
- FastAPI Application → Interview WebSocket: routes WebSocket
- Interview REST API → Session Manager: manages sessions
- Interview WebSocket → Session Manager: manages sessions
- Session Manager → Interview StateGraph: starts or resumes
- Interview StateGraph → Parallel Preparation: prepares professional mode
- Parallel Preparation → JD Analysis: analyzes JD
- Parallel Preparation → Resume Analysis: analyzes resume
- Resume Analysis → Resume Parsing and Matching: parses and matches
- Interview StateGraph → JD Analysis: analyzes practice JD
- Interview StateGraph → Question Planner: plans questions
- Interview StateGraph → Question and Assessment: asks and assesses
- Interview StateGraph → Round Evaluator: summarizes and evaluates
- Question Planner → Retrieval Query Builder: builds retrieval queries
- Question Planner → Hybrid RAG Retriever: retrieves questions
- Hybrid RAG Retriever → Question Vector Index: searches
- Question Vector Index → ChromaDB: stores vectors
- Hybrid RAG Retriever → LLM and Embedding Provider: requests embeddings
- Question Planner → Long-Term Memory Service: recalls personalization
- Question and Assessment → Long-Term Memory Service: records answer episodes
- Round Evaluator → Long-Term Memory Service: saves reflections
- Long-Term Memory Service → Memory Stores: reads and writes
- Long-Term Memory Service → Memory Vector Store: indexes and recalls
- Memory Stores → PostgreSQL: persists production memory
- Memory Vector Store → PostgreSQL: pgvector production index
- Interview StateGraph → LLM and Embedding Provider: generates interview content
- Session Manager → Session Repository: persists session state
- Session Repository → PostgreSQL: reads and writes
- Interview StateGraph → Graph Checkpoint: saves graph state
- Graph Checkpoint → PostgreSQL: checkpoints
- Session Manager → Redis Runtime Features: uses runtime enhancements
- Interview StateGraph → Report Generation: generates final report
- Report Generation → Session Manager: returns report