# hfutcoder/cloud-cold-backend architecture

> Architecture diagram of the GitHub repository hfutcoder/cloud-cold-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hfutcoder/cloud-cold-backend
- Repository: https://github.com/hfutcoder/cloud-cold-backend

## Overview

Cloud-Code is a Spring Boot AI assistant backend. A user request enters the agent API, where the agent service preprocesses skills, retrieves conversation-bound knowledge and long-term memories, then selects a fast, plan-execute, or coordinator/worker agent and streams results over SSE. Separate product branches provide skill discovery and script execution, PDF ingestion and hybrid retrieval, human approval/resume, chat history, and user/pet memory. The README documents the principal flows; the excerpts additionally confirm document ingestion’s MinIO, document-record, knowledge-preparation, and chunk-storage calls. Other unsampled subsystem links are based on README documentation.

Main entry points: [`src/main/java/com/shenchen/cloudcoldagent/service/agent/impl/AgentServiceImpl.java`](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/agent/impl/AgentServiceImpl.java) (Agent service), [`src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeServiceImpl.java`](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeServiceImpl.java) (Knowledge service), [`src/main/java/com/shenchen/cloudcoldagent/agent/SimpleReactAgent.java`](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/SimpleReactAgent.java) (Agent modes), [`src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeDocumentIngestionServiceImpl.java`](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeDocumentIngestionServiceImpl.java) (PDF ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and accounts"]
  node_agent_api["Agent API"]
  node_hitl_api["Approval API"]
  node_knowledge_api["Knowledge API"]
  node_document_api["Document API"]
  node_account_api["Account API"]
  node_user_service["User service"]
end

subgraph group_agent["Agent runtime"]
  node_agent_service["Agent service"]
  node_agent_modes["Agent modes"]
  node_plan_agent["Plan-execute"]
  node_coordinator["Coordinator"]
  node_worker_pool["Worker pool<br/>[WorkerPool.java]"]
  node_worker_agent["Worker agent<br/>[WorkerAgent.java]"]
  node_stream_events["SSE events"]
  node_hitl["HITL approval"]
end

subgraph group_skills["Skill workflow"]
  node_skill_workflow["Skill workflow"]
  node_skill_service["Skill service"]
  node_skill_registry["Skill registry"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_ingestion["PDF ingestion"]
  node_knowledge_service["Knowledge service"]
  node_document_processing["PDF processing"]
  node_chunk_store["Chunk storage<br/>[StoreService.java]"]
  node_search_index[("Search indexes")]
  node_object_store[("Object storage<br/>[MinioService.java]")]
end

subgraph group_memory["Conversation and memory"]
  node_chat_history[("Chat history")]
  node_long_memory["Long-term memory"]
  node_memory_scheduler["Memory scheduler"]
end

node_user(("User"))

node_user -->|"sends request"| node_agent_api
node_agent_api -->|"calls"| node_agent_service
node_agent_service -->|"preprocesses skills"| node_skill_workflow
node_agent_service -->|"pre-retrieves knowledge"| node_knowledge_service
node_agent_service -->|"recalls memories"| node_long_memory
node_agent_service -->|"dispatches"| node_agent_modes
node_agent_modes -->|"uses thinking mode"| node_plan_agent
node_agent_modes -->|"uses expert mode"| node_coordinator
node_coordinator -->|"dispatches tasks"| node_worker_pool
node_worker_pool -->|"runs workers"| node_worker_agent
node_agent_service -->|"streams events"| node_stream_events
node_hitl_api -->|"resumes agent"| node_agent_service
node_agent_service -->|"intercepts tools"| node_hitl
node_skill_workflow -->|"loads skills"| node_skill_service
node_skill_service -->|"uses registry"| node_skill_registry
node_document_api -->|"uploads document"| node_ingestion
node_ingestion -->|"uploads file"| node_object_store
node_ingestion -->|"prepares and stores"| node_knowledge_service
node_knowledge_service -->|"parses PDF"| node_document_processing
node_knowledge_service -->|"stores chunks"| node_chunk_store
node_chunk_store -->|"indexes chunks"| node_search_index
node_knowledge_service -->|"searches indexes"| node_search_index
node_knowledge_api -->|"manages knowledge"| node_knowledge_service
node_agent_service -->|"uses chat memory"| node_chat_history
node_long_memory -->|"scans pending sessions"| node_memory_scheduler
node_account_api -->|"manages accounts"| node_user_service

click node_agent_api "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/agent/AgentController.java"
click node_agent_service "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/agent/impl/AgentServiceImpl.java"
click node_skill_workflow "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/workflow/skill/service/impl/SkillWorkflowServiceImpl.java"
click node_agent_modes "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/SimpleReactAgent.java"
click node_plan_agent "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/PlanExecuteAgent.java"
click node_coordinator "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/CoordinatorAgent.java"
click node_worker_pool "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/worker/WorkerPool.java"
click node_worker_agent "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/worker/WorkerAgent.java"
click node_stream_events "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/common/AgentStreamEventFactory.java"
click node_hitl "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/hitl/impl/HitlExecutionServiceImpl.java"
click node_hitl_api "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/hitl/HitlCheckpointController.java"
click node_knowledge_api "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/knowledge/KnowledgeController.java"
click node_document_api "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/knowledge/DocumentController.java"
click node_ingestion "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeDocumentIngestionServiceImpl.java"
click node_knowledge_service "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeServiceImpl.java"
click node_document_processing "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/document/extract/reader/PdfMultimodalProcessor.java"
click node_chunk_store "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/document/load/store/StoreService.java"
click node_search_index "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/storage/ElasticSearchService.java"
click node_object_store "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/storage/MinioService.java"
click node_chat_history "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/memory/store/MysqlChatMemoryRepository.java"
click node_long_memory "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/usermemory/impl/UserLongTermMemoryServiceImpl.java"
click node_memory_scheduler "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/job/UserLongTermMemoryScheduler.java"
click node_skill_service "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/skill/impl/SkillServiceImpl.java"
click node_skill_registry "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/registry/CachingSkillRegistry.java"
click node_account_api "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/user/UserController.java"
click node_user_service "https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/user/impl/UserServiceImpl.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_api,node_hitl_api,node_knowledge_api,node_document_api,node_account_api,node_user_service,node_user toneBlue
class node_agent_service,node_agent_modes,node_plan_agent,node_coordinator,node_worker_pool,node_worker_agent,node_stream_events,node_hitl toneAmber
class node_skill_workflow,node_skill_service,node_skill_registry toneMint
class node_ingestion,node_knowledge_service,node_document_processing,node_chunk_store,node_search_index,node_object_store toneRose
class node_chat_history,node_long_memory,node_memory_scheduler toneIndigo
```

## Components

### API and accounts

- [Agent API](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/agent/AgentController.java): `src/main/java/com/shenchen/cloudcoldagent/controller/agent/AgentController.java`
- [Approval API](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/hitl/HitlCheckpointController.java): `src/main/java/com/shenchen/cloudcoldagent/controller/hitl/HitlCheckpointController.java`
- [Knowledge API](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/knowledge/KnowledgeController.java): `src/main/java/com/shenchen/cloudcoldagent/controller/knowledge/KnowledgeController.java`
- [Document API](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/knowledge/DocumentController.java): `src/main/java/com/shenchen/cloudcoldagent/controller/knowledge/DocumentController.java`
- [Account API](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/controller/user/UserController.java): `src/main/java/com/shenchen/cloudcoldagent/controller/user/UserController.java`
- [User service](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/user/impl/UserServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/service/user/impl/UserServiceImpl.java`

### Agent runtime

- [Agent service](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/agent/impl/AgentServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/service/agent/impl/AgentServiceImpl.java`
- [Agent modes](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/SimpleReactAgent.java): `src/main/java/com/shenchen/cloudcoldagent/agent/SimpleReactAgent.java`
- [Plan-execute](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/PlanExecuteAgent.java): `src/main/java/com/shenchen/cloudcoldagent/agent/PlanExecuteAgent.java`
- [Coordinator](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/CoordinatorAgent.java): `src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/CoordinatorAgent.java`
- [Worker pool](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/worker/WorkerPool.java): `src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/worker/WorkerPool.java`
- [Worker agent](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/worker/WorkerAgent.java): `src/main/java/com/shenchen/cloudcoldagent/agent/multiagent/worker/WorkerAgent.java`
- [SSE events](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/common/AgentStreamEventFactory.java): `src/main/java/com/shenchen/cloudcoldagent/common/AgentStreamEventFactory.java`
- [HITL approval](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/hitl/impl/HitlExecutionServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/service/hitl/impl/HitlExecutionServiceImpl.java`

### Skill workflow

- [Skill workflow](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/workflow/skill/service/impl/SkillWorkflowServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/workflow/skill/service/impl/SkillWorkflowServiceImpl.java`
- [Skill service](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/skill/impl/SkillServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/service/skill/impl/SkillServiceImpl.java`
- [Skill registry](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/registry/CachingSkillRegistry.java): `src/main/java/com/shenchen/cloudcoldagent/registry/CachingSkillRegistry.java`

### Knowledge retrieval

- [PDF ingestion](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeDocumentIngestionServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeDocumentIngestionServiceImpl.java`
- [Knowledge service](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeServiceImpl.java`
- [PDF processing](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/document/extract/reader/PdfMultimodalProcessor.java): `src/main/java/com/shenchen/cloudcoldagent/document/extract/reader/PdfMultimodalProcessor.java`
- [Chunk storage](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/document/load/store/StoreService.java): `src/main/java/com/shenchen/cloudcoldagent/document/load/store/StoreService.java`
- [Search indexes](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/storage/ElasticSearchService.java): `src/main/java/com/shenchen/cloudcoldagent/service/storage/ElasticSearchService.java`
- [Object storage](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/storage/MinioService.java): `src/main/java/com/shenchen/cloudcoldagent/service/storage/MinioService.java`

### Conversation and memory

- [Chat history](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/memory/store/MysqlChatMemoryRepository.java): `src/main/java/com/shenchen/cloudcoldagent/memory/store/MysqlChatMemoryRepository.java`
- [Long-term memory](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/service/usermemory/impl/UserLongTermMemoryServiceImpl.java): `src/main/java/com/shenchen/cloudcoldagent/service/usermemory/impl/UserLongTermMemoryServiceImpl.java`
- [Memory scheduler](https://github.com/hfutcoder/cloud-cold-backend/blob/main/src/main/java/com/shenchen/cloudcoldagent/job/UserLongTermMemoryScheduler.java): `src/main/java/com/shenchen/cloudcoldagent/job/UserLongTermMemoryScheduler.java`

### Other components

- **User**

## Connections

- User → Agent API: sends request
- Agent API → Agent service: calls
- Agent service → Skill workflow: preprocesses skills
- Agent service → Knowledge service: pre-retrieves knowledge
- Agent service → Long-term memory: recalls memories
- Agent service → Agent modes: dispatches
- Agent modes → Plan-execute: uses thinking mode
- Agent modes → Coordinator: uses expert mode
- Coordinator → Worker pool: dispatches tasks
- Worker pool → Worker agent: runs workers
- Agent service → SSE events: streams events
- Approval API → Agent service: resumes agent
- Agent service → HITL approval: intercepts tools
- Skill workflow → Skill service: loads skills
- Skill service → Skill registry: uses registry
- Document API → PDF ingestion: uploads document
- PDF ingestion → Object storage: uploads file (evidence: `src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeDocumentIngestionServiceImpl.java`)
- PDF ingestion → Knowledge service: prepares and stores (evidence: `src/main/java/com/shenchen/cloudcoldagent/service/knowledge/impl/KnowledgeDocumentIngestionServiceImpl.java`)
- Knowledge service → PDF processing: parses PDF
- Knowledge service → Chunk storage: stores chunks
- Chunk storage → Search indexes: indexes chunks (evidence: `src/main/java/com/shenchen/cloudcoldagent/document/load/store/StoreService.java`)
- Knowledge service → Search indexes: searches indexes
- Knowledge API → Knowledge service: manages knowledge
- Agent service → Chat history: uses chat memory
- Long-term memory → Memory scheduler: scans pending sessions
- Account API → User service: manages accounts
