# shangxinxiaolin/user-help architecture

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

- Interactive diagram: https://gitdiagram.com/shangxinxiaolin/user-help
- Repository: https://github.com/shangxinxiaolin/user-help

## Overview

Lingxi is a planned AI customer-support system split between a Python conversational agent and Java mock business services. The current chat path is HTTP client → FastAPI chat handler → conversation runtime → LangGraph answer workflow, with conversation persistence and checkpointing; the Java side exposes business operations through a debug HTTP controller and gRPC endpoints. The README also defines planned retrieval, routing, tools, and unified gateway capabilities, but says these are not yet implemented or integrated. Edges reflect shown calls or README-described architecture; unverified/planned links are omitted.

Main entry points: [`agent-service/app/main.py`](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/main.py) (Chat API), [`business-service/src/main/java/com/shangui/userhelp/rpc`](https://github.com/shangxinxiaolin/user-help/tree/main/business-service/src/main/java/com/shangui/userhelp/rpc) (Business gRPC), [`business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java`](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java) (Business Debug API), [`agent-service/app/graph/runtime.py`](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/runtime.py) (Turn Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Python Agent"]
  node_chat_api["Chat API<br/>[main.py]"]
  node_agent_api["Agent Router<br/>[agent.py]"]
  node_runtime["Turn Runtime<br/>[runtime.py]"]
  node_graph["Answer Graph<br/>[answer.py]"]
  node_graph_build["Graph Builder<br/>[build.py]"]
  node_chat_node["Chat Node<br/>[chat.py]"]
  node_llm["Chat Model<br/>[llm.py]"]
  node_prompts["Prompt Templates<br/>[prompts.py]"]
  node_answer["Answer Resolver<br/>[answer.py]"]
  node_conversation_repo["Conversation Repository<br/>[conversation.py]"]
  node_conversation_data[("Conversation Records<br/>[conversation.py]")]
  node_message_data[("Message Records<br/>[message.py]")]
  node_checkpoint[("Graph Checkpoint<br/>[checkpointer.py]")]
  node_retrieval["Knowledge Retrieval"]
  node_tools["Business Tools"]
end

subgraph group_business["Java Business"]
  node_java_http["Business Debug API"]
  node_orders["Order Service"]
  node_logistics["Logistics Service"]
  node_aftersales["Aftersales Service"]
  node_refund["Refund Service"]
  node_tickets["Ticket Service"]
  node_grpc["Business gRPC"]
  node_proto["Protobuf Contract"]
  node_gateway["Gateway / BFF"]
end

subgraph group_contracts["Agent State"]
  node_state["Conversation State<br/>[state.py]"]
end

node_client(("User"))

node_client -->|"sends chat"| node_chat_api
node_chat_api -->|"runs turn"| node_runtime
node_chat_api -->|"resolves answer"| node_answer
node_chat_api -->|"injects repository"| node_conversation_repo
node_chat_api -->|"builds graph"| node_graph_build
node_chat_api -->|"registers router"| node_agent_api
node_runtime -->|"persists messages"| node_conversation_repo
node_runtime -->|"invokes graph"| node_graph
node_graph_build -.->|"registers node"| node_chat_node
node_chat_node -->|"calls model"| node_llm
node_chat_node -->|"uses prompts"| node_prompts
node_runtime -->|"creates state"| node_state
node_conversation_repo -.->|"stores conversations"| node_conversation_data
node_conversation_repo -.->|"stores messages"| node_message_data
node_chat_api -->|"opens checkpoint"| node_checkpoint
node_java_http -->|"calls order service"| node_orders
node_java_http -->|"calls logistics service"| node_logistics
node_java_http -->|"calls aftersales"| node_aftersales
node_java_http -->|"calls refund service"| node_refund
node_java_http -->|"calls ticket service"| node_tickets
node_grpc -.->|"dispatches RPC"| node_orders
node_grpc -.->|"dispatches RPC"| node_logistics
node_grpc -.->|"dispatches RPC"| node_aftersales
node_grpc -.->|"dispatches RPC"| node_refund
node_grpc -.->|"dispatches RPC"| node_tickets
node_proto -->|"defines contract"| node_grpc
node_gateway -.->|"planned HTTP/SSE"| node_chat_api
node_tools -.->|"planned gRPC calls"| node_grpc
node_graph -.->|"planned retrieval"| node_retrieval

click node_chat_api "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/main.py"
click node_agent_api "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/api/agent.py"
click node_runtime "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/runtime.py"
click node_graph "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/answer.py"
click node_graph_build "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/build.py"
click node_chat_node "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/nodes/chat.py"
click node_llm "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/core/llm.py"
click node_prompts "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/core/prompts.py"
click node_state "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/state.py"
click node_answer "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/answer.py"
click node_conversation_repo "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/repositories/conversation.py"
click node_conversation_data "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/models/conversation.py"
click node_message_data "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/models/message.py"
click node_checkpoint "https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/checkpointer.py"
click node_java_http "https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java"
click node_orders "https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/order/service/impl/OrderServiceImpl.java"
click node_logistics "https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/logistics/service/impl/LogisticsServiceImpl.java"
click node_aftersales "https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/aftersales/service/impl/AftersalesServiceImpl.java"
click node_refund "https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/refund/service/impl/RefundServiceImpl.java"
click node_tickets "https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/ticket/service/impl/TicketServiceImpl.java"
click node_grpc "https://github.com/shangxinxiaolin/user-help/tree/main/business-service/src/main/java/com/shangui/userhelp/rpc"
click node_proto "https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/proto/business_service.proto"
click node_retrieval "https://github.com/shangxinxiaolin/user-help/tree/main/agent-service/app/graph"
click node_tools "https://github.com/shangxinxiaolin/user-help/tree/main/agent-service/app/graph"
click node_gateway "https://github.com/shangxinxiaolin/user-help/tree/main/business-service/src/main/java/com/shangui/userhelp"

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_agent_api,node_runtime,node_graph,node_graph_build,node_chat_node,node_llm,node_prompts,node_answer,node_conversation_repo,node_conversation_data,node_message_data,node_checkpoint,node_retrieval,node_tools,node_client toneBlue
class node_java_http,node_orders,node_logistics,node_aftersales,node_refund,node_tickets,node_grpc,node_proto,node_gateway toneAmber
class node_state toneMint
```

## Components

### Python Agent

- [Chat API](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/main.py): `agent-service/app/main.py`
- [Agent Router](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/api/agent.py): `agent-service/app/api/agent.py`
- [Turn Runtime](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/runtime.py): `agent-service/app/graph/runtime.py`
- [Answer Graph](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/answer.py): `agent-service/app/graph/answer.py`
- [Graph Builder](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/build.py): `agent-service/app/graph/build.py`
- [Chat Node](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/nodes/chat.py): `agent-service/app/graph/nodes/chat.py`
- [Chat Model](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/core/llm.py): `agent-service/app/core/llm.py`
- [Prompt Templates](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/core/prompts.py): `agent-service/app/core/prompts.py`
- [Answer Resolver](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/answer.py): `agent-service/app/graph/answer.py`
- [Conversation Repository](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/repositories/conversation.py): `agent-service/app/db/repositories/conversation.py`
- [Conversation Records](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/models/conversation.py): `agent-service/app/db/models/conversation.py`
- [Message Records](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/models/message.py): `agent-service/app/db/models/message.py`
- [Graph Checkpoint](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/db/checkpointer.py): `agent-service/app/db/checkpointer.py`
- [Knowledge Retrieval](https://github.com/shangxinxiaolin/user-help/tree/main/agent-service/app/graph): `agent-service/app/graph`
- [Business Tools](https://github.com/shangxinxiaolin/user-help/tree/main/agent-service/app/graph): `agent-service/app/graph`

### Java Business

- [Business Debug API](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java): `business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java`
- [Order Service](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/order/service/impl/OrderServiceImpl.java): `business-service/src/main/java/com/shangui/userhelp/order/service/impl/OrderServiceImpl.java`
- [Logistics Service](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/logistics/service/impl/LogisticsServiceImpl.java): `business-service/src/main/java/com/shangui/userhelp/logistics/service/impl/LogisticsServiceImpl.java`
- [Aftersales Service](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/aftersales/service/impl/AftersalesServiceImpl.java): `business-service/src/main/java/com/shangui/userhelp/aftersales/service/impl/AftersalesServiceImpl.java`
- [Refund Service](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/refund/service/impl/RefundServiceImpl.java): `business-service/src/main/java/com/shangui/userhelp/refund/service/impl/RefundServiceImpl.java`
- [Ticket Service](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/java/com/shangui/userhelp/ticket/service/impl/TicketServiceImpl.java): `business-service/src/main/java/com/shangui/userhelp/ticket/service/impl/TicketServiceImpl.java`
- [Business gRPC](https://github.com/shangxinxiaolin/user-help/tree/main/business-service/src/main/java/com/shangui/userhelp/rpc): `business-service/src/main/java/com/shangui/userhelp/rpc`
- [Protobuf Contract](https://github.com/shangxinxiaolin/user-help/blob/main/business-service/src/main/proto/business_service.proto): `business-service/src/main/proto/business_service.proto`
- [Gateway / BFF](https://github.com/shangxinxiaolin/user-help/tree/main/business-service/src/main/java/com/shangui/userhelp): `business-service/src/main/java/com/shangui/userhelp`

### Agent State

- [Conversation State](https://github.com/shangxinxiaolin/user-help/blob/main/agent-service/app/graph/state.py): `agent-service/app/graph/state.py`

### Other components

- **User**

## Connections

- User → Chat API: sends chat (evidence: `agent-service/app/main.py`)
- Chat API → Turn Runtime: runs turn (evidence: `agent-service/app/main.py`)
- Chat API → Answer Resolver: resolves answer (evidence: `agent-service/app/main.py`)
- Chat API → Conversation Repository: injects repository (evidence: `agent-service/app/main.py`)
- Chat API → Graph Builder: builds graph (evidence: `agent-service/app/main.py`)
- Chat API → Agent Router: registers router (evidence: `agent-service/app/main.py`)
- Turn Runtime → Conversation Repository: persists messages (evidence: `agent-service/app/graph/runtime.py`)
- Turn Runtime → Answer Graph: invokes graph (evidence: `agent-service/app/graph/runtime.py`)
- Graph Builder → Chat Node: registers node
- Chat Node → Chat Model: calls model (evidence: `agent-service/app/graph/nodes/chat.py`)
- Chat Node → Prompt Templates: uses prompts (evidence: `agent-service/app/graph/nodes/chat.py`)
- Turn Runtime → Conversation State: creates state (evidence: `agent-service/app/graph/runtime.py`)
- Conversation Repository → Conversation Records: stores conversations
- Conversation Repository → Message Records: stores messages
- Chat API → Graph Checkpoint: opens checkpoint (evidence: `agent-service/app/main.py`)
- Business Debug API → Order Service: calls order service (evidence: `business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java`)
- Business Debug API → Logistics Service: calls logistics service (evidence: `business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java`)
- Business Debug API → Aftersales Service: calls aftersales (evidence: `business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java`)
- Business Debug API → Refund Service: calls refund service (evidence: `business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java`)
- Business Debug API → Ticket Service: calls ticket service (evidence: `business-service/src/main/java/com/shangui/userhelp/business/api/BusinessController.java`)
- Business gRPC → Order Service: dispatches RPC (evidence: `README.md`)
- Business gRPC → Logistics Service: dispatches RPC (evidence: `README.md`)
- Business gRPC → Aftersales Service: dispatches RPC (evidence: `README.md`)
- Business gRPC → Refund Service: dispatches RPC (evidence: `README.md`)
- Business gRPC → Ticket Service: dispatches RPC (evidence: `README.md`)
- Protobuf Contract → Business gRPC: defines contract (evidence: `README.md`)
- Gateway / BFF → Chat API: planned HTTP/SSE (evidence: `README.md`)
- Business Tools → Business gRPC: planned gRPC calls (evidence: `README.md`)
- Answer Graph → Knowledge Retrieval: planned retrieval (evidence: `README.md`)
