# jd-opensource/joyagent-jdgenie architecture

> Architecture diagram of the GitHub repository jd-opensource/joyagent-jdgenie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jd-opensource/joyagent-jdgenie
- Repository: https://github.com/jd-opensource/joyagent-jdgenie

## Overview

##### Project type and purpose
- This is a full-stack, end-to-end “product”-class multi-agent framework (JoyAgent-JDGenie) that includes:
- A web UI (React/TypeScript)
- A Java Spring-Boot backend hosting a multi-agent orchestration engine
- A Python microservice (genie-tool) implementing MCP tool APIs and a file-based DB
- A Python CLI client (genie-client) for testing/automation
- Purpose: take an incoming user query/task, orchestrate multiple intelligent agents (planning, execution, react modes), invoke tools (code interpreter, search, report generator, MCP calls), manage context/memory, and stream a rich response (HTML/PPT/markdown) back to UI or CLI.

##### High-level file-structure breakdown
- Top-level scripts & Dockerfile: one‐click builds and orchestrates all components
- genie-backend:
- Spring Boot app (GenieApplication, GenieController)
- Agent framework packages (agent, handler, service, tool, llm, prompt, printer, model)
- Multi-agent engine with patterns: ‘plan-and-executor’, ‘react’
- ToolCollection registering BaseTool implementations (CodeInterpreterTool, DeepSearchTool, FileTool, etc.)
- SSEPrinter for streaming responses, SpringContextHolder, OkHttpUtil for HTTP/LLM calls
- genie-tool:
- Python FastAPI (server.py) exposing MCP endpoints for file management & custom tools
- Local SQLite or file-table DB engine under genie_tool/db
- Prompt YAMLs, LLM util wrappers
- genie-client: Python CLI to invoke backend APIs, manage headers, config, SSE client
- ui: React/Vite SPA, components for ChatView, ActionPanel, Plans, SSE streaming, services/agent.ts to hit backend

##### Key insights from README
- Multi-agent protocol supporting multi-level (work vs. task) and multi-pattern (planning vs. react) thinking
- Plug-and-play sub-agents and tools, cross-task memory, high-concurrency DAG execution engine
- Outbound LLM calls to OpenAI/GPT or custom LLM via REST (configured in application.yml)
- External MCP servers (genie-tool) configured via mcp_server_url for specialized tool invocation

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend
    UI["Web UI (React SPA)"]:::micro
    CLI["CLI Client"]:::micro

    %% Backend
    subgraph "Backend (Spring Boot)" 
        direction TB
        Controller["GenieController"]:::internal
        Orchestrator["Agent Orchestrator"]:::internal
        Context["AgentContext & Memory DTO"]:::internal
        SSE["SSE/Event Bus"]:::internal
        LLMClient["LLM Client & Config"]:::internal

        subgraph "Agents" 
            direction TB
            Planning["PlanningAgent"]:::internal
            Executor["ExecutorAgent"]:::internal
            ReAct["ReActAgent"]:::internal
            Summary["SummaryAgent"]:::internal
        end

        subgraph "Tools" 
            direction TB
            CommonTools["Common Tools"]:::internal
            McpTool["MCP Tool"]:::internal
        end
    end

    %% Python Microservice
    PythonMS["Python Tool Microservice (FastAPI)"]:::micro
    subgraph "Python DB Engine"
        direction TB
        DBEngine["DB Engine"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMExt["LLM Provider(s)"]:::external
        MCPServer["MCP Servers"]:::external
    end

    %% Flows
    UI -->|"POST /api/genie"| Controller
    CLI -->|"POST /api/genie"| Controller
    Controller -->|"invoke"| Orchestrator
    Orchestrator -->|"manage context"| Context
    Orchestrator -->|"spawn agents"| Planning
    Orchestrator --> Executor
    Orchestrator --> ReAct
    Orchestrator --> Summary
    Planning -->|"calls tools"| CommonTools
    Executor --> CommonTools
    ReAct --> CommonTools
    Summary --> CommonTools
    CommonTools -->|"in-process"| LLMClient
    CommonTools -->|"HTTP MCP"| McpTool
    McpTool -->|"HTTP"| PythonMS
    PythonMS -->|"reads/writes"| DBEngine
    CommonTools -->|"calls external LLM"| LLMExt
    McpTool --> MCPServer
    LLMClient -->|"HTTP"| LLMExt
    Orchestrator --> SSE
    SSE --> UI
    SSE --> CLI

    %% Click Events
    click UI "https://github.com/jd-opensource/joyagent-jdgenie/tree/main/ui/src"
    click Controller "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/controller/GenieController.java"
    click Orchestrator "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/service/impl/MultiAgentServiceImpl.java"
    click Orchestrator "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/service/AgentHandlerService.java"
    click Planning "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/agent/PlanningAgent.java"
    click Executor "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/agent/ExecutorAgent.java"
    click ReAct "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/agent/ReActAgent.java"
    click Summary "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/agent/SummaryAgent.java"
    click Context "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/agent/AgentContext.java"
    click Context "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/dto/Memory.java"
    click CommonTools "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/tool/ToolCollection.java"
    click CommonTools "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/tool/BaseTool.java"
    click CommonTools "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/tool/common/CodeInterpreterTool.java"
    click CommonTools "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/tool/common/DeepSearchTool.java"
    click CommonTools "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/tool/common/FileTool.java"
    click CommonTools "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/tool/common/ReportTool.java"
    click McpTool "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/tool/mcp/McpTool.java"
    click LLMClient "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/llm/LLM.java"
    click LLMClient "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/llm/Config.java"
    click LLMClient "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/util/OkHttpUtil.java"
    click SSE "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/agent/printer/SSEPrinter.java"
    click SSE "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-backend/src/main/java/com/jd/genie/util/SseEmitterUTF8.java"
    click PythonMS "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-tool/server.py"
    click PythonMS "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-tool/genie_tool/api/file_manage.py"
    click PythonMS "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-tool/genie_tool/api/tool.py"
    click DBEngine "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-tool/genie_tool/db/db_engine.py"
    click DBEngine "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-tool/genie_tool/db/file_table.py"
    click DBEngine "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-tool/genie_tool/db/file_table_op.py"
    click PythonMS "https://github.com/jd-opensource/joyagent-jdgenie/tree/main/genie-tool/genie_tool/prompt"
    click PythonMS "https://github.com/jd-opensource/joyagent-jdgenie/tree/main/genie-tool/genie_tool/tool"
    click PythonMS "https://github.com/jd-opensource/joyagent-jdgenie/tree/main/genie-tool/genie_tool/util"
    click CLI "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-client/app/client.py"
    click CLI "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-client/app/config.py"
    click CLI "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/genie-client/main.py"
    click UI "https://github.com/jd-opensource/joyagent-jdgenie/blob/main/ui/src/services/agent.ts"

    %% Styles
    classDef internal fill:#D6E4FF,stroke:#4C6EF5,color:#000
    classDef external fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef micro fill:#FFE0B2,stroke:#EF6C00,color:#000
    classDef persistence fill:#FFF59D,stroke:#F9A825,color:#000
```
