JManus Architecture Analysis: A Spring Boot Multi-Agent Plan-Execute Platform

Project Overview

• Positioning: JManus is a Spring Boot-driven multi-agent plan-execute platform aiming to provide strongly deterministic, auditable AI workflow orchestration in enterprise environments. The frontend uses Vue 3 + Ant Design Vue, offering a graphical interface for plan authoring, execution, and monitoring.
• Overall shape: A monolithic Spring Boot application carries all business APIs, the plan execution kernel, the tool system, and persistence, and also serves the Vue frontend as static resources. It supports both Docker and Native Image (GraalVM) deployments.
• Core capabilities: Plan-Act style plan generation and scheduling, tool invocation (database, browser, Bash, OCR, etc.), execution trace recording, conversational memory, MCP (Model Context Protocol) extensions, open HTTP APIs, and Cron scheduling.
• Runtime requirements: Java 17+, default embedded H2 database (switchable to MySQL/PostgreSQL), external LLM services (e.g., DashScope), and optionally Playwright/ChromeDriver.

Overall Architecture Blueprint

• UI layer: the ui-vue3 sub-project handles all interactive UI; after build, it is copied into src/main/resources/static and served by Spring Boot static resource endpoints.
• Service layer: Spring Boot exposes /api/* REST APIs; high-level APIs focus on plan execution (ManusController), plan templates, configuration, and tool orchestration.
• Execution kernel: packages such as planning, runtime, agent, tool, and recorder form the execution chain from plan parsing, agent dispatch, and tool invocation to execution recording.
• Data & configuration layer: built on Spring Data JPA with entities like Config/Recorder; the config package provides dynamic configuration, startup loading, and property mapping.
• External integration layer: llm handles LLM interaction, mcp brings in MCP services and tools, adapter offers an OpenAI-protocol compatibility layer, and the deploy directory packages containerized deployment scripts.
• Events & scheduling: the event package provides a domain event bus; cron wraps Spring Scheduling for scheduled plan execution and monitoring.

Backend Architecture

Core layering and entry point

• Startup: OpenManusSpringBootApplication enables Scheduling, JPA, and component scanning, with a Playwright initialization switch.
• Layering:
• controller: REST APIs for task submission, plan templates, configuration, and tool operations.
• service: business flows (plan generation, tool registration, execution coordination, config sync).
• entity/vo: database tables and frontend view models (plan trees, execution records, config items).
• repository: Spring Data JPA repositories.
• runtime and planning: the execution kernel for plan parsing, agent allocation, tool scheduling, and recording.
• tool: tool plugins standardized via ToolCallBiFunctionDef (metadata, input schema, execution logic).

Plan execution chain

• Plan assembly & tool registration: PlanningFactory registers callbacks for browser, database, Cron, and other tools, and dynamically extends the tool list from MCP services. MCP tools are wrapped as McpTool instances per service group.
• Execution coordination: PlanningCoordinator converts plans into an ExecutionContext, lets PlanExecutorFactory pick an executor, and after completion routes results to PlanFinalizer (asynchronously via CompletableFuture).
• Executor design: AbstractPlanExecutor controls step loops, agent execution, uploaded-file sync, step result recording, and interruption handling; LevelBasedExecutorPool provides level-based thread pool scheduling by plan depth.
• Post-processing: PlanFinalizer decides between generating an execution summary, a direct response, or interruption notices, writing execution records and updating LLM conversational memory.

Tool system

• Abstraction: all tools implement ToolCallBiFunctionDef, uniformly exposing name, description, input schema, and execution callback — aligned with model function calling.
• Built-in tools:
• Browser automation: BrowserUseTool via ChromeDriverService and Playwright.
• Database tools: DatabaseReadTool/DatabaseWriteTool/DatabaseMetadataTool, with connections managed by DataSourceService.
• Files & storage: TextFileService, UnifiedDirectoryManager, OCR-to-Markdown (MarkdownConverterTool).
• Cron tool: CronTool registers plans with CronService as scheduled tasks.
• Parallel execution: ParallelExecutionTool triggers concurrent sub-plans.
• Extension: tool/howToCreateNewTool.md documents custom tool development; MCP tools are dynamically loaded via McpService.

Configuration & startup

• The config package includes property mapping (ManusProperties, CoordinatorProperties, MemoryConfig), dynamic config management (ConfigController + ConfigService + ConfigEntity), startup listeners (AppStartupListener, ConfigAppStartupListener), and CORS/JSON/Playwright configs.
• Multiple environments via application-{profile}.yml; Makefile and deploy/Dockerfile support local and containerized builds.

Events & scheduling

• The event package defines JmanusEvent, PlanExceptionEvent, and JmanusListenerRegister; plan exceptions are cached by ManusController and surfaced to API callers.
• The cron package provides plan entities, enums, a scheduler, and REST APIs for periodic execution.
• TaskInterruptionManager works with the RootTaskManagerEntity table to implement execution interruption and status queries.

Persistence & auditability

• Execution traces live in the recorder package; NewRepoPlanExecutionRecorder persists execution records (Plan → Agent → Think-Act hierarchy).
• runtime/entity and recorder/entity structure execution logs, tool calls, and embedded contexts to power the UI execution tree.
• Configuration is managed by ConfigRepository; the tool catalog by CoordinatorToolRepository; namespace and user entities are separate.
• Logging uses logback-spring.xml, with debug switches in ManusProperties.

Frontend Architecture

Stack & engineering

• Vue 3 (Composition API) + TypeScript + Vite + Pinia + Vue Router + Ant Design Vue, plus vue3-colorpicker, nprogress, etc.
• Dev via pnpm run dev; production pnpm run build copies ui-vue3/dist into the backend's static/ui. vite.config.ts configures static asset paths and proxying.
• Internationalization under base/i18n; Ant Design's reset.css provides a unified UI baseline.

State management & interaction

• Pinia stores under stores: task (submission flow, running state, stop action, form prefill), sidebar, memory, namespace.
• Stores coordinate through browser events (window.dispatchEvent), localStorage, and API calls to keep tasks synchronized across views.

API protocol & data flow

• The src/api layer wraps REST calls with fetch, targeting paths like /api/executor with unified error handling and JSON parsing.
• CommonApiService handles plan-detail polling, form submissions, and prompt-list fetching, suppressing errors to avoid breaking polling loops.
• Execution flow: submit task → get planId → track state in a Pinia store → poll /api/executor/details/{planId} for the execution tree → if user input is required, submit a form via /submit-input/{planId}.
• Interruption: stopCurrentTask calls /api/executor/stopTask/{planId} and updates the store.

Key Service Interactions

Plan creation to execution

• ManusController.executeByToolNameAsync accepts a tool name or template ID, writes conversational memory, syncs uploads, and triggers PlanningCoordinator.
• PlanTemplateService reads the latest JSON template version and performs parameter substitution via IPlanParameterMappingService (supporting <<param>> placeholders).
• PlanExecutionRecorder records the full chain — plan → steps → Think-Act → tool calls — with detail queries exposed at the API layer.
• PlanFinalizer decides whether to generate an LLM summary or respond directly; Vue requests get a summary by default.

User input & interruption

• When a tool requests user input, UserInputService marks a waiting state in RootTaskManagerEntity; ManusController merges UserInputWaitState into the details API response.
• /api/executor/submit-input/{planId} receives the JSON form and wakes the executor.
• TaskInterruptionManager controls execution threads via database state; AbstractPlanExecutor and PlanFinalizer detect and return interruption messages.

Extensibility & Customization

• Tool extension: implement ToolCallBiFunctionDef and register in Spring or as an MCP service; PlanningFactory can register all tools at startup based on agent.init configuration.
• MCP & external services: McpService caches, authenticates, and dynamically generates McpTool wrappers; LLM integration through LlmService adapts Spring AI with multi-vendor models, streaming responses, and memory strategies.
• Dynamic agents & sub-plans: DynamicAgent, ConfigurableDynaAgent, and @DynamicAgentDefinition allow runtime agent assembly; the subplan module dynamically generates child plans via SubplanToolService, forming tree-shaped execution; PlanExecutorFactory selects executors by plan type.

Deployment & Operations

• Build chain: Makefile and tools/make wrap Maven, frontend builds, Docker images, and CI checks (codespell, markdownlint, yamllint).
• Containerization: deploy/Dockerfile based on JDK 17, copying the backend JAR and built frontend assets; deploy/start.sh provides the start script.
• Config management: dynamic config over /api/config; ConfigAppStartupListener loads default templates at startup.
• Logging & debugging: logback-spring.xml controls levels; ManusProperties.debugDetail enables LLM debug info; persisted recorder data aids troubleshooting.
• Playwright/Chrome driver: the playwright-init startup argument pre-downloads browser kernels to avoid first-run delays.

Appendix: Key Class Index

• HTTP API: runtime/controller/ManusController, planning/controller, config/ConfigController, coordinator/controller/CoordinatorToolController.
• Execution core: planning/PlanningFactory, runtime/service/PlanningCoordinator, runtime/executor/*, agent/BaseAgent.
• Tools: tool/*, tool/browse, tool/database, tool/convertToMarkdown, tool/mapreduce.
• Persistence: recorder/service/PlanExecutionRecorder, runtime/entity, config/entity/ConfigEntity, coordinator/entity/po/CoordinatorToolEntity.
• Frontend entry: ui-vue3/src/main.ts, ui-vue3/src/router, ui-vue3/src/stores, ui-vue3/src/views.
• Deployment scripts: Makefile, deploy/Dockerfile, tools/make/*.mk, tools/scripts/*.

Through this architecture, JManus forms a closed loop of "frontend orchestration → backend plan execution kernel → tools and external services → execution recording and visual feedback." Developers can extend tool capabilities, customize plan templates, or swap LLM services as needed while keeping the core execution chain stable.