# jazzblues2024/gua-ai-interview architecture

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

- Interactive diagram: https://gitdiagram.com/jazzblues2024/gua-ai-interview
- Repository: https://github.com/jazzblues2024/gua-ai-interview

## Overview

瓜分Offer is an AI interview platform: recruiters configure positions, questions, resumes, and interview sessions; candidates then join a live interview, answer streamed questions, and receive an evaluated report. The documented backend flow runs through a gateway workflow engine and agent graph, with checkpoint recovery, asynchronous evaluation/reporting, and supporting RAG, proctoring, and TTS capabilities. Paths and links reflect the tree and supplied excerpts plus explicit README architecture; several feature branches are documented but their internal wiring was not sampled.

Main entry points: [`interview-gateway/src/main/java/com/aims/gateway/orchestration/InterviewWorkflowEngine.java`](https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-gateway/src/main/java/com/aims/gateway/orchestration/InterviewWorkflowEngine.java) (Workflow engine), [`interview-infra/src/main/java/com/aims/infra/persistence/service`](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-infra/src/main/java/com/aims/infra/persistence/service) (RAG retrieval), [`interview-gateway/src/main/java/com/aims/gateway/controller`](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/controller) (REST controllers), [`interview-agent/src/main/java/com/aims/agent/orchestration/node`](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-agent/src/main/java/com/aims/agent/orchestration/node) (Agent graph nodes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Web application"]
  node_liveui["Live interview UI"]
  node_proctorui["Proctoring UI"]
end

subgraph group_gateway["Gateway and workflow"]
  node_controllers["REST controllers"]
  node_security["JWT security"]
  node_websocket["Interview WebSocket"]
  node_workflow["Workflow engine"]
  node_statepersist["State persistence"]
end

subgraph group_agents["Agent intelligence"]
  node_graph["Interview graph"]
  node_agentnodes["Agent graph nodes"]
  node_agentroles["Interview agents"]
  node_aichat["AI chat facade"]
  node_modelrouter["Model routing"]
end

subgraph group_domain["Interview data"]
  node_sessions["Interview sessions"]
  node_businessdata["Position, question, resume"]
  node_rag["RAG retrieval"]
  node_reporting["Evaluation and reports"]
end

subgraph group_platform["Platform services"]
  node_postgres[("PostgreSQL / pgvector")]
  node_redis[("Redis")]
  node_kafka["Kafka"]
  node_tts["TTS and audio storage"]
  node_modelprovider(("AI model provider"))
end

node_recruiter(("Recruiter"))
node_candidate(("Candidate"))

node_recruiter -->|"configures interviews"| node_frontend
node_candidate -->|"uses platform"| node_frontend
node_candidate -->|"joins interview"| node_liveui
node_frontend -->|"REST requests"| node_controllers
node_frontend -->|"authenticates"| node_security
node_liveui -->|"WebSocket messages"| node_websocket
node_proctorui -->|"reports focus signals"| node_liveui
node_controllers -->|"manages sessions"| node_sessions
node_controllers -->|"manages records"| node_businessdata
node_controllers -.->|"requests search"| node_rag
node_websocket -->|"submits answers"| node_workflow
node_workflow -->|"invokes graph"| node_graph
node_workflow -->|"syncs state"| node_statepersist
node_workflow -->|"checkpoints"| node_redis
node_statepersist -->|"loads session"| node_sessions
node_statepersist -->|"loads and syncs"| node_businessdata
node_graph -->|"dispatches nodes"| node_agentnodes
node_agentnodes -->|"runs agent tasks"| node_agentroles
node_agentroles -->|"requests completions"| node_aichat
node_aichat -->|"selects model"| node_modelrouter
node_modelrouter -->|"calls model"| node_modelprovider
node_agentnodes -.->|"retrieves references"| node_rag
node_rag -->|"embeds queries"| node_modelrouter
node_rag -->|"searches vectors"| node_postgres
node_rag -->|"caches searches"| node_redis
node_workflow -->|"publishes evaluation"| node_kafka
node_kafka -->|"dispatches evaluation"| node_reporting
node_reporting -->|"updates progress"| node_sessions
node_reporting -->|"stores results"| node_postgres
node_agentnodes -.->|"synthesizes questions"| node_tts
node_tts -.->|"requests speech"| node_modelprovider
node_tts -.->|"stores audio"| node_redis

click node_frontend "https://github.com/jazzblues2024/gua-ai-interview/tree/main/frontend/src/routes"
click node_liveui "https://github.com/jazzblues2024/gua-ai-interview/tree/main/frontend/src/routes/interview"
click node_proctorui "https://github.com/jazzblues2024/gua-ai-interview/tree/main/frontend/src/components/candidate"
click node_controllers "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/controller"
click node_security "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/security"
click node_websocket "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/ws"
click node_workflow "https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-gateway/src/main/java/com/aims/gateway/orchestration/InterviewWorkflowEngine.java"
click node_statepersist "https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-gateway/src/main/java/com/aims/gateway/orchestration/StatePersistenceService.java"
click node_graph "https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-agent/src/main/java/com/aims/agent/orchestration/graph/InterviewGraphFactory.java"
click node_agentnodes "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-agent/src/main/java/com/aims/agent/orchestration/node"
click node_agentroles "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-agent/src/main/java/com/aims/agent"
click node_aichat "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-ai/src/main/java/com/aims/ai/facade"
click node_modelrouter "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-ai/src/main/java/com/aims/ai/router"
click node_sessions "https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-infra/src/main/java/com/aims/infra/persistence/service/InterviewSessionService.java"
click node_businessdata "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-infra/src/main/java/com/aims/infra/persistence"
click node_rag "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-infra/src/main/java/com/aims/infra/persistence/service"
click node_reporting "https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/ws"
click node_tts "https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-infra/src/main/java/com/aims/infra/service/impl/VolcanoTtsService.java"

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_liveui,node_proctorui toneBlue
class node_controllers,node_security,node_websocket,node_workflow,node_statepersist toneAmber
class node_graph,node_agentnodes,node_agentroles,node_aichat,node_modelrouter toneMint
class node_sessions,node_businessdata,node_rag,node_reporting toneRose
class node_postgres,node_redis,node_kafka,node_tts,node_modelprovider,node_recruiter,node_candidate toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/jazzblues2024/gua-ai-interview/tree/main/frontend/src/routes): `frontend/src/routes`
- [Live interview UI](https://github.com/jazzblues2024/gua-ai-interview/tree/main/frontend/src/routes/interview): `frontend/src/routes/interview`
- [Proctoring UI](https://github.com/jazzblues2024/gua-ai-interview/tree/main/frontend/src/components/candidate): `frontend/src/components/candidate`

### Gateway and workflow

- [REST controllers](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/controller): `interview-gateway/src/main/java/com/aims/gateway/controller`
- [JWT security](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/security): `interview-gateway/src/main/java/com/aims/gateway/security`
- [Interview WebSocket](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/ws): `interview-gateway/src/main/java/com/aims/gateway/ws`
- [Workflow engine](https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-gateway/src/main/java/com/aims/gateway/orchestration/InterviewWorkflowEngine.java): `interview-gateway/src/main/java/com/aims/gateway/orchestration/InterviewWorkflowEngine.java`
- [State persistence](https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-gateway/src/main/java/com/aims/gateway/orchestration/StatePersistenceService.java): `interview-gateway/src/main/java/com/aims/gateway/orchestration/StatePersistenceService.java`

### Agent intelligence

- [Interview graph](https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-agent/src/main/java/com/aims/agent/orchestration/graph/InterviewGraphFactory.java): `interview-agent/src/main/java/com/aims/agent/orchestration/graph/InterviewGraphFactory.java`
- [Agent graph nodes](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-agent/src/main/java/com/aims/agent/orchestration/node): `interview-agent/src/main/java/com/aims/agent/orchestration/node`
- [Interview agents](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-agent/src/main/java/com/aims/agent): `interview-agent/src/main/java/com/aims/agent`
- [AI chat facade](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-ai/src/main/java/com/aims/ai/facade): `interview-ai/src/main/java/com/aims/ai/facade`
- [Model routing](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-ai/src/main/java/com/aims/ai/router): `interview-ai/src/main/java/com/aims/ai/router`

### Interview data

- [Interview sessions](https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-infra/src/main/java/com/aims/infra/persistence/service/InterviewSessionService.java): `interview-infra/src/main/java/com/aims/infra/persistence/service/InterviewSessionService.java`
- [Position, question, resume](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-infra/src/main/java/com/aims/infra/persistence): `interview-infra/src/main/java/com/aims/infra/persistence`
- [RAG retrieval](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-infra/src/main/java/com/aims/infra/persistence/service): `interview-infra/src/main/java/com/aims/infra/persistence/service`
- [Evaluation and reports](https://github.com/jazzblues2024/gua-ai-interview/tree/main/interview-gateway/src/main/java/com/aims/gateway/ws): `interview-gateway/src/main/java/com/aims/gateway/ws`

### Platform services

- **PostgreSQL / pgvector**
- **Redis**
- **Kafka**
- [TTS and audio storage](https://github.com/jazzblues2024/gua-ai-interview/blob/main/interview-infra/src/main/java/com/aims/infra/service/impl/VolcanoTtsService.java): `interview-infra/src/main/java/com/aims/infra/service/impl/VolcanoTtsService.java`
- **AI model provider**

### Other components

- **Recruiter**
- **Candidate**

## Connections

- Recruiter → Web application: configures interviews
- Candidate → Web application: uses platform
- Candidate → Live interview UI: joins interview
- Web application → REST controllers: REST requests
- Web application → JWT security: authenticates
- Live interview UI → Interview WebSocket: WebSocket messages
- Proctoring UI → Live interview UI: reports focus signals
- REST controllers → Interview sessions: manages sessions
- REST controllers → Position, question, resume: manages records
- REST controllers → RAG retrieval: requests search
- Interview WebSocket → Workflow engine: submits answers
- Workflow engine → Interview graph: invokes graph
- Workflow engine → State persistence: syncs state
- Workflow engine → Redis: checkpoints
- State persistence → Interview sessions: loads session
- State persistence → Position, question, resume: loads and syncs
- Interview graph → Agent graph nodes: dispatches nodes
- Agent graph nodes → Interview agents: runs agent tasks
- Interview agents → AI chat facade: requests completions
- AI chat facade → Model routing: selects model
- Model routing → AI model provider: calls model
- Agent graph nodes → RAG retrieval: retrieves references
- RAG retrieval → Model routing: embeds queries
- RAG retrieval → PostgreSQL / pgvector: searches vectors
- RAG retrieval → Redis: caches searches
- Workflow engine → Kafka: publishes evaluation
- Kafka → Evaluation and reports: dispatches evaluation
- Evaluation and reports → Interview sessions: updates progress
- Evaluation and reports → PostgreSQL / pgvector: stores results
- Agent graph nodes → TTS and audio storage: synthesizes questions
- TTS and audio storage → AI model provider: requests speech
- TTS and audio storage → Redis: stores audio