# tuniucorp/aigc-agents architecture

> Architecture diagram of the GitHub repository tuniucorp/aigc-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tuniucorp/aigc-agents
- Repository: https://github.com/tuniucorp/aigc-agents

## Overview

##### Project Type and Purpose
- This is a full-stack, modular Java 17 application built on Spring Boot and Spring AI.
- It implements an intelligent agent framework (“Niu Travel Agent”) that allows you to register, configure and invoke “agents” (e.g., flight search, hotel booking, trip planning) which are powered by large language models (LLMs) such as OpenAI.
- Four Maven modules:
- agents-opensource-core – the agent engine (factory, lifecycle, prompts, memory, command pattern)
- agents-opensource-app – concrete domain agent implementations (flight, hotel, train, trip, evaluators)
- agents-opensource-tools – tool integration layers (Spring auto-configuration for flight/ hotel/train/ trip APIs, widgets)
- agents-opensource-web – REST/web UI, persistent storage services (MySQL for chat records, Redis for memory), configuration

##### File Structure Analysis
- Top-level pom.xml aggregates the four submodules.
- agents-opensource-web hosts:
- Application.java, Spring Boot configs (RedisConfig, I18nConfig, SpringAiConfig, FilterConfig)
- Controllers/Services for chat record persistence, antispam, trace logs
- Static UI (index.html, index.js, CSS) served under /static
- agents-opensource-core provides packages:
- agent (AgentManager, factory, base classes)
- command (Command, actions, lifecycle, storage)
- prompt (PromptManager + template directory under /resources/prompt)
- memory/advisor (in-memory or Redis chat memory)
- chat client (OpenAIHttpClient)
- util, common, message, evaluator interfaces
- agents-opensource-app builds on core:
- impl/base (Coordinator, Dispatcher, Analyst) for orchestration of agent chains
- impl/flight, hotel, train, trip, evaluators – domain-specific Agent subclasses, prompt templates, stream handlers
- controllers: AssistantController, SuggestionController, ToolController – generic endpoints for agent calls
- services: chat record, trace log, antispam, file/process, i18n, freemarker, rewrite, transfer
- agents-opensource-tools provides Spring Boot auto-configuration of external APIs:
- FlightAutoConfiguration, HotelAutoConfiguration, TrainAutoConfiguration, TripAutoConfiguration, WidgetsAutoConfiguration
- Tools implement FlightInformationQueryTool, HotelDetail, SearchTrainDetailTool, TripExtractorTool, RestaurantListTool, WeatherListTool

##### README Insights
- Confirms four-module architecture: core engine, app implementations, tools integration, web service.
- Highlights key components: AgentManager, PromptManager, conversation flow (history, stream), multi-model support, i18n, domain applications.
- Mentions Redis (for memory) and MySQL (optional) for persistent storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Static UI"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        WebCtrl["Web Controllers"]:::web
        AppEntry["Application.java"]:::web
        RedisCfg["RedisConfig"]:::web
        I18nCfg["I18nConfig"]:::web
        SpringAiCfg["SpringAiConfig"]:::web
        Antispam["Antispam Service"]:::web
        ChatRecordSvcWeb["ChatRecord Service"]:::web
    end

    %% Application Layer
    subgraph "Application Layer"
        AssistantCtrl["AssistantController"]:::app
        FlightAgent["FlightTicketAgent"]:::app
        HotelAgent["HotelAgent"]:::app
        TrainAgent["TrainTicketAgent"]:::app
        TripPlanner["Planner"]:::app
        TripChain["TripChainHandler"]:::app
        ChatRecordSvcApp["ChatRecordService"]:::app
        TraceLogSvc["ChatTraceLogService"]:::app
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        AgentMgr["AgentManager"]:::core
        AgentFactory["AgentFactory"]:::core
        BaseAgent["BaseAgent"]:::core
        PromptMgr["PromptManager"]:::core
        InMemMem["InMemoryChatEnvironmentMemory"]:::core
        RedisMem["RedisChatMemory"]:::core
        Command["Command"]:::core
        CallAgentAct["CallAgentAction"]:::core
    end

    %% Tools Layer
    subgraph "Tools Integration Layer"
        FlightAutoCfg["FlightAutoConfiguration"]:::tools
        FlightTool["FlightInformationQueryTool"]:::tools
        HotelAutoCfg["HotelAutoConfiguration"]:::tools
        HotelTool["HotelDetail"]:::tools
        TrainAutoCfg["TrainAutoConfiguration"]:::tools
        TrainTool["SearchTrainDetailTool"]:::tools
        TripTool["TripExtractorTool"]:::tools
        WidgetsAutoCfg["WidgetsAutoConfiguration"]:::tools
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        RedisDS["Redis (Chat Memory)"]:::infra
        MySQL["MySQL (chat_records, trace_log)"]:::infra
        OpenAI["OpenAI API"]:::external
        DomainAPIs["Domain Services (Flight, Hotel, Train, Trip)"]:::external
    end

    %% Connections
    UI -->|"HTTP Request"| WebCtrl
    WebCtrl -->|"invoke Antispam"| Antispam
    WebCtrl -->|"persist chat"| ChatRecordSvcWeb
    WebCtrl -->|"dispatch"| AgentMgr
    WebCtrl -->|"use configs"| AppEntry
    WebCtrl -->|"use configs"| RedisCfg
    WebCtrl -->|"use configs"| I18nCfg
    WebCtrl -->|"use configs"| SpringAiCfg

    AgentMgr -->|"create via"| AgentFactory
    AgentMgr -->|"uses base"| BaseAgent
    AgentMgr -->|"dispatch to"| FlightAgent
    AgentMgr -->|"dispatch to"| HotelAgent
    AgentMgr -->|"dispatch to"| TrainAgent
    AgentMgr -->|"dispatch to"| TripPlanner

    TripPlanner -->|"/chain"| TripChain
    FlightAgent -->|"prompt"| PromptMgr
    HotelAgent -->|"prompt"| PromptMgr
    TrainAgent -->|"prompt"| PromptMgr
    TripPlanner -->|"prompt"| PromptMgr

    PromptMgr -->|"templates"| PromptTemplates
    PromptMgr -->|"templates"| DomainPromptTemplates

    FlightAgent -->|"LLM call"| OpenAI
    HotelAgent -->|"LLM call"| OpenAI
    TrainAgent -->|"LLM call"| OpenAI
    TripPlanner -->|"LLM call"| OpenAI

    FlightAgent -->|"tool call"| FlightTool
    HotelAgent -->|"tool call"| HotelTool
    TrainAgent -->|"tool call"| TrainTool
    TripPlanner -->|"tool call"| TripTool

    FlightTool -->|"provided by"| FlightAutoCfg
    HotelTool -->|"provided by"| HotelAutoCfg
    TrainTool -->|"provided by"| TrainAutoCfg
    TripTool -->|"provided by"| WidgetsAutoCfg

    AgentMgr -->|"memory advisor"| InMemMem
    AgentMgr -->|"memory advisor"| RedisMem
    InMemMem --> RedisDS
    RedisMem --> RedisDS

    WebCtrl -->|"trace log"| TraceLogSvc
    TraceLogSvc --> MySQL
    ChatRecordSvcWeb --> MySQL
    ChatRecordSvcApp --> MySQL

    %% Templates nodes
    PromptTemplates["Freemarker Prompt Templates"]:::core
    DomainPromptTemplates["Domain Prompt Templates"]:::app

    %% Click Events
    click UI "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-web/src/main/resources/static/index.html"
    click AppEntry "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-web/src/main/java/com/tuniu/agents/Application.java"
    click RedisCfg "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-web/src/main/java/com/tuniu/agents/config/RedisConfig.java"
    click I18nCfg "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-web/src/main/java/com/tuniu/agents/config/I18nConfig.java"
    click SpringAiCfg "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-web/src/main/java/com/tuniu/agents/config/SpringAiConfig.java"
    click Antispam "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-web/src/main/java/com/tuniu/agents/service/DefaultAntispamService.java"
    click ChatRecordSvcWeb "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-web/src/main/java/com/tuniu/agents/service/DefaultChatRecordService.java"
    click AgentMgr "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/agent/AgentManager.java"
    click AgentFactory "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/agent/AgentFactory.java"
    click BaseAgent "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/agent/BaseAgent.java"
    click PromptMgr "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/prompt/PromptManager.java"
    click InMemMem "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/advisor/InMemoryChatEnvironmentMemory.java"
    click RedisMem "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/advisor/RedisChatMemory.java"
    click Command "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/command/Command.java"
    click CallAgentAct "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-core/src/main/java/com/tuniu/agents/command/action/CallAgentAction.java"
    click FlightAgent "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/impl/flight/FlightTicketAgent.java"
    click HotelAgent "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/impl/hotel/HotelAgent.java"
    click TrainAgent "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/impl/train/TrainTicketAgent.java"
    click TripPlanner "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/impl/trip/Planner.java"
    click TripChain "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/impl/trip/chain/TripChainHandler.java"
    click AssistantCtrl "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/common/controller/AssistantController.java"
    click ChatRecordSvcApp "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/common/service/ChatRecordService.java"
    click TraceLogSvc "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-app/src/main/java/com/tuniu/agents/common/service/ChatTraceLogService.java"
    click FlightAutoCfg "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/flights/FlightAutoConfiguration.java"
    click FlightTool "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/flights/domestic/oneway/FlightInformationQueryTool.java"
    click HotelAutoCfg "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/hotel/HotelAutoConfiguration.java"
    click HotelTool "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/hotel/tool/HotelDetail.java"
    click TrainAutoCfg "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/train/TrainAutoConfiguration.java"
    click TrainTool "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/train/tool/SearchTrainDetailTool.java"
    click TripTool "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/trip/TripExtractorTool.java"
    click WidgetsAutoCfg "https://github.com/tuniucorp/aigc-agents/blob/main/agents-opensource-tools/src/main/java/com/tuniu/agents/tools/widgets/WidgetsAutoConfiguration.java"

    %% Styles
    classDef frontend fill:#f9c,stroke:#333,stroke-width:1px
    classDef web fill:#88f,stroke:#333,stroke-width:1px
    classDef app fill:#8f8,stroke:#333,stroke-width:1px
    classDef core fill:#f96,stroke:#333,stroke-width:1px
    classDef tools fill:#c9f,stroke:#333,stroke-width:1px
    classDef infra fill:#9cf,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5
```
