# yphyphyph/hagent architecture

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

- Interactive diagram: https://gitdiagram.com/yphyphyph/hagent
- Repository: https://github.com/yphyphyph/hagent

## Overview

HAgent is a web-based enterprise AI assistant combining streamed chat, grounded knowledge-base answers, agent tools, conversation memory, and administrative controls. The primary workflow runs from a user message through the chat service, optional retrieval/tool work, and model-generated SSE events displayed in the portal. Separate branches cover knowledge ingestion and administration. Edges are based on README statements or the shown source/index references; several runtime modules were not sampled, so their internal links are omitted.

Main entry points: [`hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/ChatServiceImpl.java`](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/ChatServiceImpl.java) (Chat orchestration), [`hagent-front/src/views/admin/SettingsView.vue`](https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/views/admin/SettingsView.vue) (Admin console), [`hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AgentToolLoopService.java`](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AgentToolLoopService.java) (Agent tool loop), [`hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/RagService.java`](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/RagService.java) (RAG service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat experience"]
  node_portal["Chat portal<br/>[PortalChatView.vue]"]
  node_chatstate["Chat stream state<br/>[useChat.ts]"]
  node_chatapi["Chat API"]
  node_chatservice["Chat orchestration"]
  node_memory["Conversation memory"]
end

subgraph group_reasoning["AI reasoning"]
  node_rewrite["Query rewriting"]
  node_rag["RAG service<br/>[RagService.java]"]
  node_hybrid["Hybrid search"]
  node_rerank["Reranking and evidence gate"]
  node_agent["Agent tool loop"]
  node_tools["AI tools"]
  node_models["Model provider"]
end

subgraph group_knowledge["Knowledge base"]
  node_knowledgeadmin["Knowledge management"]
  node_vectorize["Document vectorization"]
  node_vectorstore[("Vector store")]
end

subgraph group_admin["Administration"]
  node_adminui["Admin console<br/>[SettingsView.vue]"]
  node_settings["System settings"]
  node_sqlpolicy["SQL table policies"]
  node_mcpadmin["MCP management"]
end

subgraph group_identity["Identity"]
  node_authui["Login and profile<br/>[LoginView.vue]"]
  node_authapi["Authentication API"]
  node_authservice["Authentication service"]
end

node_user(("User"))
node_adminuser(("Administrator"))

node_user -->|"asks"| node_portal
node_portal -->|"streams through"| node_chatstate
node_chatstate -.->|"calls"| node_chatapi
node_chatapi -.->|"dispatches"| node_chatservice
node_chatservice -.->|"uses"| node_memory
node_chatservice -.->|"rewrites query"| node_rewrite
node_rewrite -.->|"supplies query"| node_rag
node_rag -->|"searches through"| node_hybrid
node_hybrid -->|"reranks results"| node_rerank
node_chatservice -.->|"runs tools"| node_agent
node_agent -.->|"dispatches"| node_tools
node_agent -.->|"retrieves knowledge"| node_rag
node_chatservice -.->|"generates with"| node_models
node_chatservice -->|"pushes SSE events"| node_portal
node_adminuser -->|"configures"| node_adminui
node_adminui -.->|"updates models"| node_settings
node_settings -->|"refreshes configuration"| node_models
node_adminui -->|"manages documents"| node_knowledgeadmin
node_knowledgeadmin -->|"queues processing"| node_vectorize
node_vectorize -.->|"writes embeddings"| node_vectorstore
node_rag -.->|"searches vectors"| node_vectorstore
node_adminui -->|"sets table rules"| node_sqlpolicy
node_agent -.->|"validates SQL policy"| node_sqlpolicy
node_adminui -->|"manages tools"| node_mcpadmin
node_adminuser -->|"signs in"| node_authui
node_authui -.->|"submits credentials"| node_authapi
node_authapi -->|"delegates"| node_authservice

click node_portal "https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/views/portal/PortalChatView.vue"
click node_chatstate "https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/composables/useChat.ts"
click node_chatapi "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/controller/ChatController.java"
click node_chatservice "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/ChatServiceImpl.java"
click node_memory "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/memory/ConversationMemoryService.java"
click node_rewrite "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/QueryRewriteServiceImpl.java"
click node_rag "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/RagService.java"
click node_hybrid "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/retrieval/HybridSearchService.java"
click node_rerank "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/retrieval/RerankingService.java"
click node_agent "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AgentToolLoopService.java"
click node_tools "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/mcp/McpToolService.java"
click node_models "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AiModelProvider.java"
click node_knowledgeadmin "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-module-knowledge/src/main/java/com/hagent/knowledge/service/impl/KnowledgeServiceImpl.java"
click node_vectorize "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-module-knowledge/src/main/java/com/hagent/knowledge/service/KnowledgeVectorizeRunner.java"
click node_vectorstore "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-common/src/main/java/com/hagent/common/service/VectorStoreService.java"
click node_adminui "https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/views/admin/SettingsView.vue"
click node_settings "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-server/src/main/java/com/hagent/server/system/controller/SystemSettingsController.java"
click node_sqlpolicy "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/SqlTablePolicyServiceImpl.java"
click node_mcpadmin "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/controller/McpToolController.java"
click node_authui "https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/views/LoginView.vue"
click node_authapi "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-server/src/main/java/com/hagent/server/auth/controller/AuthController.java"
click node_authservice "https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-server/src/main/java/com/hagent/server/auth/service/impl/AuthServiceImpl.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_portal,node_chatstate,node_chatapi,node_chatservice,node_memory,node_user toneBlue
class node_rewrite,node_rag,node_hybrid,node_rerank,node_agent,node_tools,node_models toneAmber
class node_knowledgeadmin,node_vectorize,node_vectorstore toneMint
class node_adminui,node_settings,node_sqlpolicy,node_mcpadmin toneRose
class node_authui,node_authapi,node_authservice,node_adminuser toneIndigo
```

## Components

### Chat experience

- [Chat portal](https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/views/portal/PortalChatView.vue): `hagent-front/src/views/portal/PortalChatView.vue`
- [Chat stream state](https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/composables/useChat.ts): `hagent-front/src/composables/useChat.ts`
- [Chat API](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/controller/ChatController.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/controller/ChatController.java`
- [Chat orchestration](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/ChatServiceImpl.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/ChatServiceImpl.java`
- [Conversation memory](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/memory/ConversationMemoryService.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/memory/ConversationMemoryService.java`

### AI reasoning

- [Query rewriting](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/QueryRewriteServiceImpl.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/QueryRewriteServiceImpl.java`
- [RAG service](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/RagService.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/RagService.java`
- [Hybrid search](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/retrieval/HybridSearchService.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/retrieval/HybridSearchService.java`
- [Reranking and evidence gate](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/retrieval/RerankingService.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/retrieval/RerankingService.java`
- [Agent tool loop](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AgentToolLoopService.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AgentToolLoopService.java`
- [AI tools](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/mcp/McpToolService.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/mcp/McpToolService.java`
- [Model provider](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AiModelProvider.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AiModelProvider.java`

### Knowledge base

- [Knowledge management](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-module-knowledge/src/main/java/com/hagent/knowledge/service/impl/KnowledgeServiceImpl.java): `hagent-back/hagent-module-knowledge/src/main/java/com/hagent/knowledge/service/impl/KnowledgeServiceImpl.java`
- [Document vectorization](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-module-knowledge/src/main/java/com/hagent/knowledge/service/KnowledgeVectorizeRunner.java): `hagent-back/hagent-module-knowledge/src/main/java/com/hagent/knowledge/service/KnowledgeVectorizeRunner.java`
- [Vector store](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-common/src/main/java/com/hagent/common/service/VectorStoreService.java): `hagent-back/hagent-common/src/main/java/com/hagent/common/service/VectorStoreService.java`

### Administration

- [Admin console](https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/views/admin/SettingsView.vue): `hagent-front/src/views/admin/SettingsView.vue`
- [System settings](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-server/src/main/java/com/hagent/server/system/controller/SystemSettingsController.java): `hagent-back/hagent-server/src/main/java/com/hagent/server/system/controller/SystemSettingsController.java`
- [SQL table policies](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/SqlTablePolicyServiceImpl.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/service/impl/SqlTablePolicyServiceImpl.java`
- [MCP management](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-ai/src/main/java/com/hagent/ai/controller/McpToolController.java): `hagent-back/hagent-ai/src/main/java/com/hagent/ai/controller/McpToolController.java`

### Identity

- [Login and profile](https://github.com/yphyphyph/hagent/blob/master/hagent-front/src/views/LoginView.vue): `hagent-front/src/views/LoginView.vue`
- [Authentication API](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-server/src/main/java/com/hagent/server/auth/controller/AuthController.java): `hagent-back/hagent-server/src/main/java/com/hagent/server/auth/controller/AuthController.java`
- [Authentication service](https://github.com/yphyphyph/hagent/blob/master/hagent-back/hagent-server/src/main/java/com/hagent/server/auth/service/impl/AuthServiceImpl.java): `hagent-back/hagent-server/src/main/java/com/hagent/server/auth/service/impl/AuthServiceImpl.java`

### Other components

- **User**
- **Administrator**

## Connections

- User → Chat portal: asks (evidence: `README.md`)
- Chat portal → Chat stream state: streams through (evidence: `hagent-front/src/composables/useChat.ts`)
- Chat stream state → Chat API: calls
- Chat API → Chat orchestration: dispatches
- Chat orchestration → Conversation memory: uses
- Chat orchestration → Query rewriting: rewrites query
- Query rewriting → RAG service: supplies query
- RAG service → Hybrid search: searches through (evidence: `hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/RagService.java`)
- Hybrid search → Reranking and evidence gate: reranks results (evidence: `hagent-back/hagent-ai/src/main/java/com/hagent/ai/retrieval/HybridSearchService.java`)
- Chat orchestration → Agent tool loop: runs tools
- Agent tool loop → AI tools: dispatches
- Agent tool loop → RAG service: retrieves knowledge (evidence: `hagent-back/hagent-ai/src/main/java/com/hagent/ai/core/AgentToolLoopService.java`)
- Chat orchestration → Model provider: generates with
- Chat orchestration → Chat portal: pushes SSE events (evidence: `README.md`)
- Administrator → Admin console: configures (evidence: `README.md`)
- Admin console → System settings: updates models
- System settings → Model provider: refreshes configuration (evidence: `hagent-back/hagent-server/src/main/java/com/hagent/server/system/controller/SystemSettingsController.java`)
- Admin console → Knowledge management: manages documents (evidence: `README.md`)
- Knowledge management → Document vectorization: queues processing (evidence: `README.md`)
- Document vectorization → Vector store: writes embeddings
- RAG service → Vector store: searches vectors
- Admin console → SQL table policies: sets table rules (evidence: `README.md`)
- Agent tool loop → SQL table policies: validates SQL policy
- Admin console → MCP management: manages tools (evidence: `README.md`)
- Administrator → Login and profile: signs in (evidence: `README.md`)
- Login and profile → Authentication API: submits credentials
- Authentication API → Authentication service: delegates (evidence: `hagent-back/hagent-server/src/main/java/com/hagent/server/auth/controller/AuthController.java`)
