pigx/CLAUDE.md

CLAUDE.md

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

Project Overview

PigX is a proprietary enterprise-grade microservices platform built on Spring Cloud Alibaba, focusing on AI knowledge management, document processing, and intelligent Q&A capabilities. The current version is 5.10.2-SNAPSHOT.

Important: This is NOT an open-source project. All rights reserved by the author. Commercial use requires proper licensing.

Technology Stack

• Java Version: Java 17
• Spring Boot: 3.5.6
• Spring Cloud: 2025.0.0
• Spring Cloud Alibaba: 2023.0.3.3
• AI/ML Libraries:
  • LangChain4j: 1.6.0
  • Spring AI: 1.0.2
• Database:
  • MySQL (for business data)
  • PostgreSQL with pgvector extension (for vector storage)
  • Support for Qdrant, Milvus, Chroma, Neo4j
• ORM: MyBatis-Plus
• Container: Undertow
• Service Discovery: Nacos
• Build Tool: Maven

Project Structure

Module Organization

pigx/
├── pigx-boot/              # Monolithic deployment starter (combines all modules)
├── pigx-knowledge/         # AI knowledge base module (core AI capabilities)
├── pigx-auth/              # Authentication module (dependency)
├── pigx-upms-biz/          # User management module (dependency)
├── pigx-gateway/           # API gateway (microservices mode)
├── pigx-register/          # Nacos registry (microservices mode)
├── pigx-visual/            # Visual management modules (monitoring, codegen, etc.)
├── db/                     # Database initialization scripts
└── docker-compose.yml      # Docker compose configuration

Key Module: pigx-knowledge

The knowledge module follows a standard layered architecture:

pigx-knowledge/src/main/java/com/pig4cloud/pigx/knowledge/
├── controller/           # REST API endpoints
├── service/             # Business logic layer
│   └── impl/           # Service implementations
├── mapper/             # MyBatis mapper interfaces
├── entity/             # JPA/MyBatis entities
├── dto/                # Data transfer objects
├── config/             # Spring configuration classes
└── support/            # Support utilities and handlers
    ├── constant/       # Enums and constants
    ├── handler/        # Specialized handlers
    │   ├── rag/       # RAG (Retrieval Augmented Generation) handlers
    │   ├── parse/     # Document parsing handlers
    │   ├── model/     # AI model handlers
    │   └── websearch/ # Web search handlers
    ├── provider/       # External service providers
    ├── rule/          # LiteFlow rule definitions
    ├── function/      # LangChain4j functions
    └── util/          # Utility classes

Vector Storage Architecture

The system uses a factory pattern for vector store implementations:

• Interface: EmbeddingStoreFactory (pigx-knowledge/support/handler/rag/)
• Supported Stores: Qdrant, Milvus, Chroma, PGVector, Neo4j
• Factory Method: createEmbeddingStore(embedStoreEntity, datasetEntity)
• Each store type has its own factory implementation that checks support(storeType)

Build and Run Commands

Maven Profiles

The project has two main profiles:

• cloud (default): Microservices mode with Spring Cloud
• boot: Monolithic mode using pigx-boot

Build Commands

# Build entire project (microservices mode)
mvn clean install

# Build monolithic version
mvn clean install -P boot

# Build specific module
mvn clean install -pl pigx-knowledge

# Skip tests
mvn clean install -DskipTests

# Build Docker image for a module
mvn clean install docker:build -pl pigx-knowledge

# Format code according to Spring Java Format
mvn spring-javaformat:apply

Run Commands

Monolithic Mode (Recommended for Development)

# Run pigx-boot module
cd pigx-boot
mvn spring-boot:run

# Or run with specific profile
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Default port: 8080 (configured in pigx-boot)

Microservices Mode

# Start all services using Docker Compose
docker-compose up

# Or start infrastructure first, then individual services
# 1. Start Nacos (service discovery)
cd pigx-register && mvn spring-boot:run

# 2. Start gateway
cd pigx-gateway && mvn spring-boot:run

# 3. Start knowledge service
cd pigx-knowledge && mvn spring-boot:run

Knowledge service port: 9010

Test Commands

# Run all tests
mvn test

# Run tests for specific module
mvn test -pl pigx-knowledge

# Run specific test class
mvn test -pl pigx-knowledge -Dtest=YourTestClass

# Run tests with coverage
mvn clean test jacoco:report

Development Configuration

Database Setup

The project uses PostgreSQL with pgvector for the boot module:

• Host: localhost (or pgvector in Docker)
• Port: 5432
• Database: pigxx_boot
• Username: postgres
• Password: postgres

Database initialization scripts are in db/ directory:

• 0pigxx_boot.sql - Boot module schema
• 9pigxx_ai.sql - AI knowledge base schema

Redis Configuration

• Host: 127.0.0.1
• Database: 5

Nacos Configuration

For microservices mode:

• Server: pigx-register:8848
• Username: nacos
• Password: nacos
• Configuration files are loaded from Nacos dynamically

File Storage

Local file storage (configurable):

• Path: /Users/lengleng/Downloads/img (development)
• Can be configured in application-dev.yml

Code Style and Conventions

Code Formatting

The project uses Spring Java Format. Run before committing:

mvn spring-javaformat:apply

Package Naming Conventions

• Controllers: Suffix with Controller (e.g., AiDatasetController)
• Services: Interface without suffix, impl with Impl (e.g., EmbeddingStoreService, EmbeddingStoreServiceImpl)
• Mappers: Suffix with Mapper for both interface and XML (e.g., AiDatasetMapper.java, AiDatasetMapper.xml)
• Entities: Suffix with Entity (e.g., AiDatasetEntity)
• DTOs: Suffix with DTO (e.g., AiMultimodalEmbeddingArkDTO)
• Enums: Suffix with Enums (e.g., EmbedBizTypeEnums, ModelSupportEnums)

MyBatis Mapper XML Location

All MyBatis mapper XMLs are in: src/main/resources/mapper/*.xml

Constants and Enums

Located in support/constant/ package. Key enums:

• EmbedBizTypeEnums - Embedding business types
• ModelSupportEnums - Supported AI models
• EmbedStoreSupportEnums - Supported vector stores
• FileTypeEnums - Supported file types
• ChatTypeEnums - Chat interaction types

AI/RAG Implementation Details

Embedding Store Factory Pattern

When working with vector stores:

1. Create a factory class implementing EmbeddingStoreFactory
2. Implement support(String storeType) to declare supported types
3. Implement createEmbeddingStore(...) to instantiate the store
4. Register as a Spring @Component

LangChain4j Integration

• Document parsers: Apache PDFBox, Apache POI
• Embedding models: Support for OpenAI, custom models via factory
• Vector stores: Qdrant, Milvus, Chroma, PGVector
• Document splitters and transformers in handler/rag package

LiteFlow Rule Engine

Business rules are defined in the support/rule/ package using LiteFlow DSL.

API Documentation

API documentation is available via Swagger/Knife4j:

• Swagger UI: http://localhost:9010/doc.html (knowledge service)
• OpenAPI: Enabled via @EnableOpenApi annotation
• Token URL for auth: Configured in swagger.token-url property

Git Workflow

Current branch: ai-leng-dev Main branch: dev (use this for PRs)

Important Notes

Security

• Configuration encryption: Uses Jasypt with password "pigx"
• Login encryption: Uses AES with key "pigxpigxpigxpigx" (16 chars)
• OAuth2 resource server protection enabled

Docker

Docker Maven plugin is configured but disabled by default (docker.skip=false in pom). Registry: registry.cn-hangzhou.aliyuncs.com/pigcloudx

Magic API

Low-code API platform is integrated for dynamic API creation:

• Configuration: src/main/resources/lowcode/magic-api.yml
• Requires additional setup for production use

File Parsing

Supports multiple formats via Tika, Torchv, and custom parsers:

• PDF, Word, Excel, PowerPoint (Apache POI)
• HTML to DOCX conversion (Aspose Words)
• Unstructured data (Torchv)

Common Development Tasks

Adding a New Vector Store

1. Create factory class in pigx-knowledge/support/handler/rag/
2. Implement EmbeddingStoreFactory interface
3. Add store type to EmbedStoreSupportEnums
4. Add dependencies in pigx-knowledge/pom.xml

Adding a New AI Model

1. Add model configuration to ModelSupportEnums
2. Create model provider in support/provider/ if needed
3. Update embedding service implementation

Adding a New Document Parser

1. Create parser handler in support/handler/parse/
2. Register file type in FileTypeEnums
3. Integrate with document processing pipeline

Modifying Database Schema

1. Update SQL in db/ directory
2. Update corresponding entity classes
3. Update MyBatis mapper interfaces and XMLs
4. Run database migration scripts