# bcefghj/ai-agent-interview-guide architecture

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

- Interactive diagram: https://gitdiagram.com/bcefghj/ai-agent-interview-guide
- Repository: https://github.com/bcefghj/ai-agent-interview-guide

## Overview

This repository combines AI Agent interview-preparation materials with three implementations of an enterprise customer-support and knowledge-assistant platform (Python, Java, and Go). The runtime workflow is user request → API → intent and agent orchestration → optional RAG and tool use → model response, supported by document ingestion, memory, model routing, and tracing. The graph uses Java for the best-evidenced request and ingestion flows, while retaining Python’s documented API and memory components; the README describes the three versions as parallel implementations. Unsampled subsystem links are documented at README level.

Main entry points: [`project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java) (Agent orchestrator), [`project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java`](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java) (Document ETL), [`project-java/src/main/java/com/agent/platform/controller/ChatController.java`](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/controller/ChatController.java) (Chat API), [`project-java/src/main/java/com/agent/platform/controller/DocumentController.java`](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/controller/DocumentController.java) (Document API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Request API"]
  node_chat_api["Chat API"]
  node_document_api["Document API"]
  node_python_api["Python API routes<br/>[chat.py]"]
end

subgraph group_agents["Agent execution"]
  node_intent["Intent recognition"]
  node_orchestrator["Agent orchestrator"]
  node_react["ReAct agent<br/>[ReActAgent.java]"]
  node_planner["Planner agent<br/>[PlannerAgent.java]"]
  node_reflection["Reflection agent"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_rag_retrieve["Multi-retrieval"]
  node_reranker["Result reranking<br/>[Reranker.java]"]
  node_rag_generate["RAG generation<br/>[RAGGenerator.java]"]
  node_etl["Document ETL<br/>[ETLPipeline.java]"]
  node_parser["Document parser"]
  node_chunker["Document chunker"]
  node_tools["Tool system<br/>[ToolRouter.java]"]
end

subgraph group_support["Runtime support"]
  node_milvus[("Vector database<br/>[MilvusService.java]")]
  node_memory["Memory manager<br/>[MemoryManager.java]"]
  node_py_memory["Python memory manager<br/>[manager.py]"]
  node_redis[("Redis cache")]
  node_model_router["Model routing<br/>[ModelRouter.java]"]
  node_trace["Request tracing<br/>[TraceService.java]"]
end

node_user(("User"))
node_llm{{"LLM provider"}}
node_search{{"Search tools"}}

node_user -->|"sends chat"| node_chat_api
node_chat_api -->|"calls chat"| node_orchestrator
node_user -->|"uploads document"| node_document_api
node_document_api -->|"processes upload"| node_etl
node_etl -->|"parses text"| node_parser
node_etl -->|"chunks text"| node_chunker
node_etl -->|"writes vectors"| node_milvus
node_orchestrator -->|"recognizes intent"| node_intent
node_orchestrator -->|"dispatches mode"| node_react
node_orchestrator -->|"dispatches mode"| node_planner
node_orchestrator -.->|"dispatches mode"| node_reflection
node_orchestrator -->|"retrieves context"| node_rag_retrieve
node_orchestrator -->|"reranks results"| node_reranker
node_orchestrator -.->|"generates answer"| node_rag_generate
node_rag_retrieve -.->|"searches vectors"| node_milvus
node_orchestrator -.->|"routes tools"| node_tools
node_tools -.->|"invokes search"| node_search
node_orchestrator -->|"loads context"| node_memory
node_memory -.->|"stores history"| node_redis
node_py_memory -.->|"uses short memory"| node_redis
node_orchestrator -->|"calls model"| node_model_router
node_model_router -.->|"routes request"| node_llm
node_orchestrator -->|"records spans"| node_trace
node_python_api -.->|"serves chat"| node_user

click node_chat_api "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/controller/ChatController.java"
click node_document_api "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/controller/DocumentController.java"
click node_python_api "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-python/app/api/routes/chat.py"
click node_intent "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/intent/IntentRecognizer.java"
click node_orchestrator "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java"
click node_react "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/ReActAgent.java"
click node_planner "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/PlannerAgent.java"
click node_reflection "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/ReflectionAgent.java"
click node_rag_retrieve "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/rag/MultiRetriever.java"
click node_reranker "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/rag/Reranker.java"
click node_rag_generate "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/rag/RAGGenerator.java"
click node_etl "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java"
click node_parser "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/etl/DocumentParser.java"
click node_chunker "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/etl/DocumentChunker.java"
click node_milvus "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/vectordb/MilvusService.java"
click node_tools "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/tool/ToolRouter.java"
click node_memory "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/memory/MemoryManager.java"
click node_py_memory "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-python/app/core/memory/manager.py"
click node_redis "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/cache/RedisCacheService.java"
click node_model_router "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/llm/ModelRouter.java"
click node_trace "https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/trace/TraceService.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_chat_api,node_document_api,node_python_api,node_user toneBlue
class node_intent,node_orchestrator,node_react,node_planner,node_reflection toneAmber
class node_rag_retrieve,node_reranker,node_rag_generate,node_etl,node_parser,node_chunker,node_tools toneMint
class node_milvus,node_memory,node_py_memory,node_redis,node_model_router,node_trace toneRose
class node_llm,node_search toneIndigo
```

## Components

### Request API

- [Chat API](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/controller/ChatController.java): `project-java/src/main/java/com/agent/platform/controller/ChatController.java`
- [Document API](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/controller/DocumentController.java): `project-java/src/main/java/com/agent/platform/controller/DocumentController.java`
- [Python API routes](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-python/app/api/routes/chat.py): `project-python/app/api/routes/chat.py`

### Agent execution

- [Intent recognition](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/intent/IntentRecognizer.java): `project-java/src/main/java/com/agent/platform/service/intent/IntentRecognizer.java`
- [Agent orchestrator](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java): `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`
- [ReAct agent](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/ReActAgent.java): `project-java/src/main/java/com/agent/platform/service/agent/ReActAgent.java`
- [Planner agent](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/PlannerAgent.java): `project-java/src/main/java/com/agent/platform/service/agent/PlannerAgent.java`
- [Reflection agent](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/agent/ReflectionAgent.java): `project-java/src/main/java/com/agent/platform/service/agent/ReflectionAgent.java`

### Knowledge and tools

- [Multi-retrieval](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/rag/MultiRetriever.java): `project-java/src/main/java/com/agent/platform/service/rag/MultiRetriever.java`
- [Result reranking](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/rag/Reranker.java): `project-java/src/main/java/com/agent/platform/service/rag/Reranker.java`
- [RAG generation](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/rag/RAGGenerator.java): `project-java/src/main/java/com/agent/platform/service/rag/RAGGenerator.java`
- [Document ETL](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java): `project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java`
- [Document parser](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/etl/DocumentParser.java): `project-java/src/main/java/com/agent/platform/etl/DocumentParser.java`
- [Document chunker](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/etl/DocumentChunker.java): `project-java/src/main/java/com/agent/platform/etl/DocumentChunker.java`
- [Tool system](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/tool/ToolRouter.java): `project-java/src/main/java/com/agent/platform/service/tool/ToolRouter.java`

### Runtime support

- [Vector database](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/vectordb/MilvusService.java): `project-java/src/main/java/com/agent/platform/infrastructure/vectordb/MilvusService.java`
- [Memory manager](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/service/memory/MemoryManager.java): `project-java/src/main/java/com/agent/platform/service/memory/MemoryManager.java`
- [Python memory manager](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-python/app/core/memory/manager.py): `project-python/app/core/memory/manager.py`
- [Redis cache](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/cache/RedisCacheService.java): `project-java/src/main/java/com/agent/platform/infrastructure/cache/RedisCacheService.java`
- [Model routing](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/llm/ModelRouter.java): `project-java/src/main/java/com/agent/platform/infrastructure/llm/ModelRouter.java`
- [Request tracing](https://github.com/bcefghj/ai-agent-interview-guide/blob/main/project-java/src/main/java/com/agent/platform/infrastructure/trace/TraceService.java): `project-java/src/main/java/com/agent/platform/infrastructure/trace/TraceService.java`

### Other components

- **User**
- **LLM provider**
- **Search tools**

## Connections

- User → Chat API: sends chat (evidence: `README.md`)
- Chat API → Agent orchestrator: calls chat (evidence: `project-java/src/main/java/com/agent/platform/controller/ChatController.java`)
- User → Document API: uploads document (evidence: `README.md`)
- Document API → Document ETL: processes upload (evidence: `project-java/src/main/java/com/agent/platform/controller/DocumentController.java`)
- Document ETL → Document parser: parses text (evidence: `project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java`)
- Document ETL → Document chunker: chunks text (evidence: `project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java`)
- Document ETL → Vector database: writes vectors (evidence: `project-java/src/main/java/com/agent/platform/etl/ETLPipeline.java`)
- Agent orchestrator → Intent recognition: recognizes intent (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Agent orchestrator → ReAct agent: dispatches mode (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Agent orchestrator → Planner agent: dispatches mode (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Agent orchestrator → Reflection agent: dispatches mode (evidence: `README.md`)
- Agent orchestrator → Multi-retrieval: retrieves context (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Agent orchestrator → Result reranking: reranks results (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Agent orchestrator → RAG generation: generates answer (evidence: `README.md`)
- Multi-retrieval → Vector database: searches vectors (evidence: `README.md`)
- Agent orchestrator → Tool system: routes tools (evidence: `README.md`)
- Tool system → Search tools: invokes search (evidence: `README.md`)
- Agent orchestrator → Memory manager: loads context (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Memory manager → Redis cache: stores history (evidence: `README.md`)
- Python memory manager → Redis cache: uses short memory (evidence: `README.md`)
- Agent orchestrator → Model routing: calls model (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Model routing → LLM provider: routes request (evidence: `README.md`)
- Agent orchestrator → Request tracing: records spans (evidence: `project-java/src/main/java/com/agent/platform/service/agent/AgentOrchestrator.java`)
- Python API routes → User: serves chat (evidence: `README.md`)
