# njydsz/ydsz-cloud architecture

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

- Interactive diagram: https://gitdiagram.com/njydsz/ydsz-cloud
- Repository: https://github.com/njydsz/ydsz-cloud

## Overview

Ydsz Cloud is an enterprise microservice platform; the supplied source excerpts concentrate on its AI-agent service, with additional evidence for workflow, document preview, and shared audit querying. The agent workflow is request entry, agent execution, and optional retrieval/tool use, alongside document ingestion and other documented capabilities. Connections to unsampled subsystems are omitted or marked unverified; documented platform capabilities are retained without implying their internal wiring was inspected.

Main entry points: [`ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent`](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent) (Agent execution), [`ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java`](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java) (Knowledge documents), [`ydsz-agent/ydsz-agent-web/src/main/java/com/njydsz/agent/web/controller`](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-web/src/main/java/com/njydsz/agent/web/controller) (Agent API), [`ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/RagService.java`](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/RagService.java) (RAG querying)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["AI agent"]
  node_agent_api["Agent API"]
  node_agent_runtime["Agent execution"]
  node_agent_models["Chat models<br/>[ChatMessage.java]"]
  node_dag["DAG orchestration<br/>[AgentDag.java]"]
  node_tool_search["Semantic tool search"]
  node_guardrails["Agent guardrails"]
  node_llm["LLM provider<br/>[LlmClient.java]"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_knowledge_docs["Knowledge documents"]
  node_ocr["OCR service<br/>[OcrService.java]"]
  node_embedding["Embedding client"]
  node_vector_store[("Vector store")]
  node_rag_service["RAG querying<br/>[RagService.java]"]
  node_hybrid_search["Hybrid search"]
  node_knowledge_graph[("Knowledge graph")]
end

subgraph group_workflow["Workflow engine"]
  node_workflow_definitions["Flow definitions"]
  node_workflow_instances["Flow instances"]
end

subgraph group_platform["Shared platform"]
  node_preview["Office preview"]
  node_audit_query["Audit queries"]
  node_audit_db[("Audit tables")]
  node_message_engine["Message engine"]
  node_gateway{{"API gateway"}}
end

node_caller(("API caller"))

node_caller -.->|"sends request"| node_agent_api
node_agent_api -.->|"dispatches"| node_agent_runtime
node_agent_runtime -.->|"calls provider"| node_llm
node_agent_runtime -.->|"applies checks"| node_guardrails
node_agent_runtime -.->|"runs workflow"| node_dag
node_agent_runtime -.->|"uses retrieval"| node_rag_service
node_agent_runtime -.->|"finds tools"| node_tool_search
node_agent_runtime -.->|"uses chat data"| node_agent_models
node_knowledge_docs -->|"embeds chunks"| node_embedding
node_knowledge_docs -->|"writes vectors"| node_vector_store
node_knowledge_docs -->|"ingests optionally"| node_knowledge_graph
node_knowledge_docs -->|"uses OCR"| node_ocr
node_rag_service -.->|"retrieves"| node_vector_store
node_hybrid_search -.->|"combines search"| node_rag_service
node_tool_search -->|"embeds query"| node_llm
node_workflow_instances -.->|"reads definition"| node_workflow_definitions
node_audit_query -->|"queries tables"| node_audit_db
node_gateway -.->|"routes requests"| node_agent_api
node_gateway -.->|"routes requests"| node_message_engine
node_preview -.->|"serves preview"| node_caller

click node_agent_api "https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-web/src/main/java/com/njydsz/agent/web/controller"
click node_agent_runtime "https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent"
click node_agent_models "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/model/ChatMessage.java"
click node_dag "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent/AgentDag.java"
click node_tool_search "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-infra/src/main/java/com/njydsz/agent/infra/tool/EmbeddingSemanticToolSearchService.java"
click node_guardrails "https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/guardrail"
click node_llm "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/gateway/LlmClient.java"
click node_knowledge_docs "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java"
click node_ocr "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/ocr/OcrService.java"
click node_embedding "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/rag/EmbeddingClient.java"
click node_vector_store "https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/rag"
click node_rag_service "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/RagService.java"
click node_hybrid_search "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/search/HybridSearchService.java"
click node_knowledge_graph "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/knowledge/KnowledgeGraphStore.java"
click node_workflow_definitions "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-workflow/ydsz-workflow-server/src/main/java/com/njydsz/workflow/server/service/impl/definition/FlowDefinitionQueryService.java"
click node_workflow_instances "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-workflow/ydsz-workflow-server/src/main/java/com/njydsz/workflow/server/service/impl/instance/FlowInstanceQueryService.java"
click node_preview "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-nextwiki/ydsz-nextwiki-server/src/main/java/com/njydsz/nextwiki/server/service/PreviewApplicationService.java"
click node_audit_query "https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-common/ydsz-common-audit/src/main/java/com/njydsz/common/audit/core/DefaultAuditQueryService.java"
click node_audit_db "https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-common/ydsz-common-audit/src/main/java/com/njydsz/common/audit"
click node_message_engine "https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-message"

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_agent_runtime,node_agent_models,node_dag,node_tool_search,node_guardrails,node_llm toneBlue
class node_knowledge_docs,node_ocr,node_embedding,node_vector_store,node_rag_service,node_hybrid_search,node_knowledge_graph toneAmber
class node_workflow_definitions,node_workflow_instances,node_caller toneMint
class node_preview,node_audit_query,node_audit_db,node_message_engine,node_gateway toneRose
```

## Components

### AI agent

- [Agent API](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-web/src/main/java/com/njydsz/agent/web/controller): `ydsz-agent/ydsz-agent-web/src/main/java/com/njydsz/agent/web/controller`
- [Agent execution](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent`
- [Chat models](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/model/ChatMessage.java): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/model/ChatMessage.java`
- [DAG orchestration](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent/AgentDag.java): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/agent/AgentDag.java`
- [Semantic tool search](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-infra/src/main/java/com/njydsz/agent/infra/tool/EmbeddingSemanticToolSearchService.java): `ydsz-agent/ydsz-agent-infra/src/main/java/com/njydsz/agent/infra/tool/EmbeddingSemanticToolSearchService.java`
- [Agent guardrails](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/guardrail): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/guardrail`
- [LLM provider](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/gateway/LlmClient.java): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/gateway/LlmClient.java`

### Knowledge and retrieval

- [Knowledge documents](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java): `ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java`
- [OCR service](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/ocr/OcrService.java): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/ocr/OcrService.java`
- [Embedding client](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/rag/EmbeddingClient.java): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/rag/EmbeddingClient.java`
- [Vector store](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/rag): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/rag`
- [RAG querying](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/RagService.java): `ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/RagService.java`
- [Hybrid search](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/search/HybridSearchService.java): `ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/search/HybridSearchService.java`
- [Knowledge graph](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/knowledge/KnowledgeGraphStore.java): `ydsz-agent/ydsz-agent-domain/src/main/java/com/njydsz/agent/domain/knowledge/KnowledgeGraphStore.java`

### Workflow engine

- [Flow definitions](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-workflow/ydsz-workflow-server/src/main/java/com/njydsz/workflow/server/service/impl/definition/FlowDefinitionQueryService.java): `ydsz-workflow/ydsz-workflow-server/src/main/java/com/njydsz/workflow/server/service/impl/definition/FlowDefinitionQueryService.java`
- [Flow instances](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-workflow/ydsz-workflow-server/src/main/java/com/njydsz/workflow/server/service/impl/instance/FlowInstanceQueryService.java): `ydsz-workflow/ydsz-workflow-server/src/main/java/com/njydsz/workflow/server/service/impl/instance/FlowInstanceQueryService.java`

### Shared platform

- [Office preview](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-nextwiki/ydsz-nextwiki-server/src/main/java/com/njydsz/nextwiki/server/service/PreviewApplicationService.java): `ydsz-nextwiki/ydsz-nextwiki-server/src/main/java/com/njydsz/nextwiki/server/service/PreviewApplicationService.java`
- [Audit queries](https://github.com/njydsz/ydsz-cloud/blob/main/ydsz-common/ydsz-common-audit/src/main/java/com/njydsz/common/audit/core/DefaultAuditQueryService.java): `ydsz-common/ydsz-common-audit/src/main/java/com/njydsz/common/audit/core/DefaultAuditQueryService.java`
- [Audit tables](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-common/ydsz-common-audit/src/main/java/com/njydsz/common/audit): `ydsz-common/ydsz-common-audit/src/main/java/com/njydsz/common/audit`
- [Message engine](https://github.com/njydsz/ydsz-cloud/tree/main/ydsz-message): `ydsz-message`
- **API gateway**

### Other components

- **API caller**

## Connections

- API caller → Agent API: sends request
- Agent API → Agent execution: dispatches
- Agent execution → LLM provider: calls provider
- Agent execution → Agent guardrails: applies checks
- Agent execution → DAG orchestration: runs workflow
- Agent execution → RAG querying: uses retrieval
- Agent execution → Semantic tool search: finds tools
- Agent execution → Chat models: uses chat data
- Knowledge documents → Embedding client: embeds chunks (evidence: `ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java`)
- Knowledge documents → Vector store: writes vectors (evidence: `ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java`)
- Knowledge documents → Knowledge graph: ingests optionally (evidence: `ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java`)
- Knowledge documents → OCR service: uses OCR (evidence: `ydsz-agent/ydsz-agent-server/src/main/java/com/njydsz/agent/server/rag/DocumentIngestionService.java`)
- RAG querying → Vector store: retrieves
- Hybrid search → RAG querying: combines search
- Semantic tool search → LLM provider: embeds query (evidence: `ydsz-agent/ydsz-agent-infra/src/main/java/com/njydsz/agent/infra/tool/EmbeddingSemanticToolSearchService.java`)
- Flow instances → Flow definitions: reads definition
- Audit queries → Audit tables: queries tables (evidence: `ydsz-common/ydsz-common-audit/src/main/java/com/njydsz/common/audit/core/DefaultAuditQueryService.java`)
- API gateway → Agent API: routes requests
- API gateway → Message engine: routes requests
- Office preview → API caller: serves preview