CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

# Build entire project (skip tests)
mvn clean install -DskipTests

# Build and run tests
mvn clean install

# Package the runnable IM server JAR
mvn clean package -pl aq-chat-im -DskipTests

# Run a single test class
mvn test -pl <module> -Dtest=ClassName

# Docker build (from aq-chat-im/docker/)
docker build -t aq-chat-im:latest .

The main executable module is aq-chat-im. It produces a Spring Boot fat JAR via spring-boot-maven-plugin.

Architecture Overview

This is a real-time IM (instant messaging) server built on Netty WebSocket + Spring Boot 3.2.5 + Java 17.

Module Layout

Netty Pipeline

aq-chat-im starts a Netty server (default port 9090). The channel pipeline is:

HttpServerCodec → ChunkedWriteHandler → HttpObjectAggregator
  → WebSocketServerProtocolHandler → IdleStateHandler
  → MessageDecoder → MessageEncoder → HearBeatHandler → AQChatCommandHandler

Binary WebSocket frame format: [msgLength: 4 bytes][command: 2 bytes][msgBody: variable (Protobuf)]

Command Handler Pattern

AQChatHandlerFactory scans the Spring context for all ICmdHandler<T> beans and builds a command→handler map. AQChatCommandHandler (Netty inbound handler) decodes the command code and delegates to the matching handler. To add a new command: define a Protobuf message, add a command code to the proto, register a builder in MessageRecognizer, and implement ICmdHandler.

State Holders

• GlobalChannelHolder — active Netty channels keyed by userId
• IUserHolder — online/offline user state (Redis-backed)
• IRoomHolder — room membership (Redis-backed)

Async Messaging (RocketMQ)

Handlers publish to RocketMQ topics via MqSendingAgent; consumers in aq-chat-service persist to MySQL or fan out to room members. Key topics: STORE_MESSAGE, SEND_MESSAGE, OFFLINE_MESSAGE, RECALL_MESSAGE, JOIN_ROOM, LEAVE_ROOM, AI_HELPER, USER_LOGOUT.

AI Assistants

Four AI assistants triggered by @mention in messages: 小Q (QA), 小T (text-to-image), 小V (text-to-voice), 小M (multi-model). Implemented as a Chain of Responsibility in aq-chat-ai. Supports two providers: Alibaba DashScope and Gitee AI (configured in application.yml).

Protocol Buffers

Proto files live in aq-chat-im/src/main/proto/. Regenerate Java sources with the protobuf Maven plugin during mvn generate-sources.

Key Configuration (aq-chat-im/src/main/resources/application.yml)

• aq-chat.websocketPort — Netty listen port (default 9090)
• aq-chat.aiConfig.baiLianConfig — DashScope API key & model
• aq-chat.aiConfig.giteeConfig — Gitee AI bearer token & models
• aq-chat.aliOssConfig / aliOssStsConfig — Aliyun OSS for file uploads
• spring.datasource — MySQL (default host 192.168.137.21:3306/aqchat)
• spring.data.redis — Redis (default host 192.168.137.21:6379)
• RocketMQ NameServer addresses under aq-chat.rocketmq