# xianjianlf2/mindgeniusai architecture

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

- Interactive diagram: https://gitdiagram.com/xianjianlf2/mindgeniusai
- Repository: https://github.com/xianjianlf2/mindgeniusai

## Overview

MindGenius AI is a self-hosted document-to-mind-map workbench. A user chats with the Hermas agent, which can retrieve passages from attached PDFs, generate a new map, expand branches, or propose node-ID edits; streamed results and edits update the browser’s editable canvas. The web app also supports manual editing, saved maps, document management, import/export, and multi-provider model keys. Groupings reflect the web workbench, server agent, document retrieval, and shared protocol. Some subsystem links are based on README documentation because their implementation excerpts were not provided.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/App.tsx) (Workbench shell), [`apps/web/src/stores/chatStore.ts`](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/stores/chatStore.ts) (Chat state), [`apps/server/src/agent/tools.ts`](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/agent/tools.ts) (Agent tools), [`apps/server/src/routes/agent.ts`](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/routes/agent.ts) (Agent API route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workbench"]
  node_workbench["Workbench shell<br/>[App.tsx]"]
  node_conversation["Chat interface<br/>[Conversation.tsx]"]
  node_chatstate["Chat state<br/>[chatStore.ts]"]
  node_webapi["HTTP and SSE<br/>[requests.ts]"]
  node_canvas["Map canvas<br/>[MindMapCanvas.tsx]"]
  node_mapcontroller["Canvas renderer<br/>[controller.ts]"]
  node_nodestate["Map state and edits<br/>[nodeStore.ts]"]
  node_documentsui["Document drawer<br/>[SourcesDrawer.tsx]"]
  node_palette["Command palette<br/>[CommandPalette.tsx]"]
  node_exchange["Import and export<br/>[import.ts]"]
end

subgraph group_agent["Agent and models"]
  node_serverroutes["Agent API route<br/>[agent.ts]"]
  node_hermas["Hermas orchestration<br/>[hermas.ts]"]
  node_tools["Agent tools<br/>[tools.ts]"]
  node_prompts["Prompt templates<br/>[index.ts]"]
  node_provider["Model provider<br/>[provider.ts]"]
end

subgraph group_documents["Document retrieval"]
  node_docroutes["Document API<br/>[documents.ts]"]
  node_rag[("PDF indexing and retrieval<br/>[rag.ts]")]
end

subgraph group_shared["Shared contracts"]
  node_protocol["Agent and SSE protocol<br/>[protocol.ts]"]
end

node_user(("Knowledge worker"))
node_modelservice(("LLM provider service"))

node_user -->|"uses"| node_workbench
node_workbench -->|"shows"| node_conversation
node_workbench -->|"shows"| node_canvas
node_workbench -->|"shows"| node_documentsui
node_workbench -->|"shows"| node_palette
node_conversation -->|"submits messages"| node_chatstate
node_chatstate -->|"sends requests"| node_webapi
node_webapi -->|"streams agent request"| node_serverroutes
node_serverroutes -->|"invokes"| node_hermas
node_hermas -->|"runs tool loop"| node_tools
node_tools -->|"builds prompts"| node_prompts
node_tools -->|"requests models"| node_provider
node_provider -->|"calls"| node_modelservice
node_tools -->|"retrieves passages"| node_rag
node_user -->|"attaches PDFs"| node_documentsui
node_documentsui -->|"uploads and indexes"| node_docroutes
node_docroutes -->|"indexes and queries"| node_rag
node_hermas -->|"emits agent events"| node_protocol
node_serverroutes -->|"streams events"| node_protocol
node_chatstate -->|"handles events"| node_protocol
node_chatstate -->|"applies map results"| node_nodestate
node_canvas -->|"renders map"| node_mapcontroller
node_nodestate -->|"provides tree"| node_mapcontroller
node_user -->|"edits manually"| node_canvas
node_user -->|"imports or exports"| node_exchange
node_user -->|"searches maps and docs"| node_palette

click node_workbench "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/App.tsx"
click node_conversation "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/Conversation.tsx"
click node_chatstate "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/stores/chatStore.ts"
click node_webapi "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/api/requests.ts"
click node_canvas "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/MindMapCanvas.tsx"
click node_mapcontroller "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/mindmap/controller.ts"
click node_nodestate "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/stores/nodeStore.ts"
click node_documentsui "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/SourcesDrawer.tsx"
click node_palette "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/CommandPalette.tsx"
click node_exchange "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/utils/import.ts"
click node_serverroutes "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/routes/agent.ts"
click node_hermas "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/agent/hermas.ts"
click node_tools "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/agent/tools.ts"
click node_prompts "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/prompts/index.ts"
click node_provider "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/llm/provider.ts"
click node_docroutes "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/routes/documents.ts"
click node_rag "https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/services/rag.ts"
click node_protocol "https://github.com/xianjianlf2/mindgeniusai/blob/main/packages/shared/src/protocol.ts"

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_workbench,node_conversation,node_chatstate,node_webapi,node_canvas,node_mapcontroller,node_nodestate,node_documentsui,node_palette,node_exchange toneBlue
class node_serverroutes,node_hermas,node_tools,node_prompts,node_provider toneAmber
class node_docroutes,node_rag toneMint
class node_protocol,node_user toneRose
class node_modelservice toneIndigo
```

## Components

### Web workbench

- [Workbench shell](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Chat interface](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/Conversation.tsx): `apps/web/src/components/Conversation.tsx`
- [Chat state](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/stores/chatStore.ts): `apps/web/src/stores/chatStore.ts`
- [HTTP and SSE](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/api/requests.ts): `apps/web/src/api/requests.ts`
- [Map canvas](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/MindMapCanvas.tsx): `apps/web/src/components/MindMapCanvas.tsx`
- [Canvas renderer](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/mindmap/controller.ts): `apps/web/src/mindmap/controller.ts`
- [Map state and edits](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/stores/nodeStore.ts): `apps/web/src/stores/nodeStore.ts`
- [Document drawer](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/SourcesDrawer.tsx): `apps/web/src/components/SourcesDrawer.tsx`
- [Command palette](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/components/CommandPalette.tsx): `apps/web/src/components/CommandPalette.tsx`
- [Import and export](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/web/src/utils/import.ts): `apps/web/src/utils/import.ts`

### Agent and models

- [Agent API route](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/routes/agent.ts): `apps/server/src/routes/agent.ts`
- [Hermas orchestration](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/agent/hermas.ts): `apps/server/src/agent/hermas.ts`
- [Agent tools](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/agent/tools.ts): `apps/server/src/agent/tools.ts`
- [Prompt templates](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/prompts/index.ts): `apps/server/src/prompts/index.ts`
- [Model provider](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/llm/provider.ts): `apps/server/src/llm/provider.ts`

### Document retrieval

- [Document API](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/routes/documents.ts): `apps/server/src/routes/documents.ts`
- [PDF indexing and retrieval](https://github.com/xianjianlf2/mindgeniusai/blob/main/apps/server/src/services/rag.ts): `apps/server/src/services/rag.ts`

### Shared contracts

- [Agent and SSE protocol](https://github.com/xianjianlf2/mindgeniusai/blob/main/packages/shared/src/protocol.ts): `packages/shared/src/protocol.ts`

### Other components

- **Knowledge worker**
- **LLM provider service**

## Connections

- Knowledge worker → Workbench shell: uses (evidence: `README.md`)
- Workbench shell → Chat interface: shows (evidence: `apps/web/src/App.tsx`)
- Workbench shell → Map canvas: shows (evidence: `apps/web/src/App.tsx`)
- Workbench shell → Document drawer: shows (evidence: `apps/web/src/App.tsx`)
- Workbench shell → Command palette: shows (evidence: `apps/web/src/App.tsx`)
- Chat interface → Chat state: submits messages
- Chat state → HTTP and SSE: sends requests (evidence: `apps/web/src/stores/chatStore.ts`)
- HTTP and SSE → Agent API route: streams agent request (evidence: `README.md`)
- Agent API route → Hermas orchestration: invokes (evidence: `apps/server/src/routes/agent.ts`)
- Hermas orchestration → Agent tools: runs tool loop (evidence: `apps/server/src/agent/hermas.ts`)
- Agent tools → Prompt templates: builds prompts (evidence: `apps/server/src/agent/tools.ts`)
- Agent tools → Model provider: requests models (evidence: `apps/server/src/agent/tools.ts`)
- Model provider → LLM provider service: calls (evidence: `README.md`)
- Agent tools → PDF indexing and retrieval: retrieves passages (evidence: `apps/server/src/agent/tools.ts`)
- Knowledge worker → Document drawer: attaches PDFs (evidence: `README.md`)
- Document drawer → Document API: uploads and indexes (evidence: `README.md`)
- Document API → PDF indexing and retrieval: indexes and queries (evidence: `apps/server/src/routes/documents.ts`)
- Hermas orchestration → Agent and SSE protocol: emits agent events (evidence: `apps/server/src/agent/hermas.ts`)
- Agent API route → Agent and SSE protocol: streams events (evidence: `apps/server/src/routes/agent.ts`)
- Chat state → Agent and SSE protocol: handles events (evidence: `apps/web/src/stores/chatStore.ts`)
- Chat state → Map state and edits: applies map results
- Map canvas → Canvas renderer: renders map (evidence: `apps/web/src/mindmap/controller.ts`)
- Map state and edits → Canvas renderer: provides tree (evidence: `apps/web/src/mindmap/controller.ts`)
- Knowledge worker → Map canvas: edits manually (evidence: `README.md`)
- Knowledge worker → Import and export: imports or exports (evidence: `README.md`)
- Knowledge worker → Command palette: searches maps and docs (evidence: `README.md`)
