daarion-admin/microdao-daarion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
134c044c21221b25b5ff264d5b259b3054b94f4c
microdao-daarion/CHAT-ARCHITECTURE.md
Apple 744c149300
Some checks failed
Build and Deploy Docs / build-and-deploy (push) Has been cancelled
Details
✨ Add automated session logging system 
- Created logs/ structure (sessions, operations, incidents)
- Added session-start/log/end scripts
- Installed Git hooks for auto-logging commits/pushes
- Added shell integration for zsh
- Created CHANGELOG.md
- Documented today's session (2026-01-10)
2026-01-10 04:53:17 -08:00

626 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Архітектура розширеного чату
**Дата:** 2025-11-23
---
## 🏗️ Структура компонентів
```
┌─────────────────────────────────────────────────────────────┐
│ │
│ MicroDaoOrchestratorChatEnhanced (Головний компонент) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ Chat Header │ │ │
│ │ │ 👑 Оркестратор мікроДАО - [Agent Name] │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ Messages Area │ │ │
│ │ │ │ │ │
│ │ │ 👤 User: Привіт! │ │ │
│ │ │ 🤖 Agent: Вітаю! Чим можу допомогти? │ │ │
│ │ │ 👤 User: [Image] Що це? │ │ │
│ │ │ 🤖 Agent: Це сонячна панель... │ │ │
│ │ │ 💭 Loading... │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ MultimodalInput │ │ │
│ │ │ ┌────┬────┬────┬────┐ │ │ │
│ │ │ │ 🎤 │ 🖼️ │ 📎 │ 🌐 │ [Text Input] [Send] │ │ │
│ │ │ └────┴────┴────┴────┘ │ │ │
│ │ │ Голос Фото Файл Веб │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
▼ Згорнути/Розгорнути
┌─────────────────────────────────────────────────────────────┐
│ │
│ KnowledgeBase (База знань агента) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 📊 База знань - [Agent Name] [Завантажити файл] │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ │ │
│ │ 📄 energy-guide.pdf (2.5 MB) [🗑️] │ │
│ │ ✅ Векторна БД ✅ Графова БД │ │
│ │ Status: Completed │ │
│ │ │ │
│ │ 📄 solar-panels.docx (150 KB) [🗑️] │ │
│ │ ⏳ Векторна БД ⏳ Графова БД │ │
│ │ Status: Vectorized │ │
│ │ │ │
│ │ ─────────────────────────────────────────────────── │ │
│ │ Статистика: │ │
│ │ Всього: 2 | Векторизовано: 2 | У графі: 1 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
▼ Згорнути/Розгорнути
┌─────────────────────────────────────────────────────────────┐
│ │
│ SystemPromptEditor (Системний промпт) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ⚙️ Системний промпт - [Agent Name] [Редагувати] [🔄] │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────┐ │ │
│ │ │ Ти - Helion, AI-агент платформи Energy Union. │ │ │
│ │ │ Допомагай користувачам з технологіями │ │ │
│ │ │ EcoMiner/BioMiner, токеномікою та DAO governance. │ │ │
│ │ │ │ │ │
│ │ │ Твої основні функції: │ │ │
│ │ │ - Консультації з енергетичними технологіями │ │ │
│ │ │ - Пояснення токеноміки Energy Union │ │ │
│ │ │ - Допомога з onboarding в DAO │ │ │
│ │ │ ... │ │ │
│ │ └───────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 345 символів │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
▼ Згорнути/Розгорнути
┌─────────────────────────────────────────────────────────────┐
│ │
│ TelegramIntegration (Telegram інтеграція) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 💬 Telegram інтеграція - [Agent Name] ✅ Підключено │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────┐ │ │
│ │ │ Ім'я бота: @helion_bot │ │ │
│ │ │ Підключено: 23.11.2025 10:00 │ │ │
│ │ │ │ │ │
│ │ │ [Відкрити бота] [Копіювати посилання] │ │ │
│ │ │ │ │ │
│ │ │ Токен: 1234567890:ABCdef...ghij │ │ │
│ │ └───────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [Від'єднати бота] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🔄 Data Flow
```
┌─────────────┐
│ User │
└──────┬──────┘
│
│ (Input: text/voice/image/file)
▼
┌─────────────────────────┐
│ MultimodalInput │
│ - Voice → STT │
│ - Image → Base64 │
│ - File → FormData │
│ - Text → String │
└──────────┬──────────────┘
│
│ (message + context)
▼
┌──────────────────────────────┐
│ MicroDaoOrchestrator │
│ ChatEnhanced │
│ - Add user message │
│ - Prepare payload │
│ - Call Router API │
└──────────┬───────────────────┘
│
│ POST /route
▼
┌──────────────────────────────┐
│ Router (NODE1) │
│ - Match agent rule │
│ - Load system_prompt │
│ - Call LLM (qwen3:8b) │
└──────────┬───────────────────┘
│
│ Response
▼
┌──────────────────────────────┐
│ MicroDaoOrchestrator │
│ ChatEnhanced │
│ - Parse response │
│ - Add assistant message │
│ - Update UI │
└──────────┬───────────────────┘
│
│ (display message)
▼
┌─────────────┐
│ User │
└─────────────┘
```
---
## 🗂️ Component Hierarchy
```
MicroDaoOrchestratorChatEnhanced
├── State Management
│ ├── messages: ChatMessage[]
│ ├── input: string
│ ├── attachedImages: File[]
│ ├── attachedFiles: File[]
│ ├── knowledgeFiles: KnowledgeFile[]
│ ├── systemPrompt: string
│ ├── telegramConnected: boolean
│ └── UI states (show/hide sections)
│
├── Main Chat Window
│ ├── Header (Crown icon, agent name, close button)
│ ├── Messages Area
│ │ ├── User messages (right, purple)
│ │ ├── Agent messages (left, white)
│ │ ├── Images preview
│ │ ├── Attachments list
│ │ └── Loading spinner
│ └── MultimodalInput
│ ├── Voice button (🎤)
│ ├── Image button (🖼️)
│ ├── File button (📎)
│ ├── Web search button (🌐)
│ ├── Text input (textarea)
│ └── Send button
│
├── KnowledgeBase (collapsible)
│ ├── Header (title, upload button)
│ ├── Upload Area (drag & drop)
│ ├── Files List
│ │ ├── File item
│ │ │ ├── Name, size, status
│ │ │ ├── Vector DB indicator
│ │ │ ├── Graph DB indicator
│ │ │ └── Actions (reindex, delete)
│ │ └── ...
│ └── Statistics (total, vectorized, graphed)
│
├── SystemPromptEditor (collapsible)
│ ├── Header (title, edit/save buttons, reset)
│ ├── Display mode
│ │ └── Read-only prompt text
│ ├── Edit mode
│ │ └── Textarea with prompt
│ └── Character count
│
└── TelegramIntegration (collapsible)
├── Header (title, status indicator)
├── Connected state
│ ├── Bot info (username, date)
│ ├── Bot token (masked)
│ ├── Actions (open bot, copy link)
│ └── Disconnect button
└── Disconnected state
├── Instructions
├── Token input
└── Connect button
```
---
## 🔌 Services Architecture
```
┌──────────────────────────────────────────────────────────┐
│ Frontend Layer │
│ ┌────────────────────────────────────────────────────┐ │
│ │ MicroDaoOrchestratorChatEnhanced │ │
│ │ - Manages UI state │ │
│ │ - Handles user interactions │ │
│ │ - Orchestrates services │ │
│ └────────┬──────────────┬──────────────┬──────────────┘ │
│ │ │ │ │
└───────────┼──────────────┼──────────────┼─────────────────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌─────────────────┐
│ voiceService │ │ webSearch │ │ knowledgeBase │
│ │ │ Service │ │ Service │
├───────────────┤ ├──────────────┤ ├─────────────────┤
│ - startRec() │ │ - search() │ │ - uploadFile() │
│ - stopRec() │ │ - format() │ │ - getFiles() │
│ - speak() │ │ - extract() │ │ - deleteFile() │
│ - stopSpeak() │ │ │ │ - reindex() │
└───────┬───────┘ └──────┬───────┘ └────────┬────────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Web Speech │ │ Router API │ │ Backend API │
│ API │ │ (NODE1) │ │ (NODE1) │
├───────────────┤ ├──────────────┤ ├─────────────────┤
│ - STT │ │ POST /route │ │ Knowledge Base │
│ - TTS │ │ mode: web │ │ System Prompt │
│ │ │ search │ │ Telegram │
└───────────────┘ └──────────────┘ └─────────────────┘
```
---
## 🌊 Message Flow Example
### 1. User sends voice message
```
User: [Press 🎤]
↓
MultimodalInput:
- voiceService.startRecording()
- Show "Recording..." indicator
↓
User: [Speaks] "Привіт, ти хто?"
↓
Web Speech API:
- Converts speech to text
- Returns: "Привіт, ти хто?"
↓
MultimodalInput:
- Sets input value
- User clicks Send
↓
MicroDaoOrchestratorChatEnhanced:
- Creates user message
- Adds to messages state
- Calls sendMessageMutation.mutate()
↓
API Call:
POST http://144.76.224.179:9102/route
{
"agent": "helion",
"message": "Привіт, ти хто?",
"mode": "chat",
"payload": {
"context": {
"system_prompt": "Ти - Helion..."
}
}
}
↓
Router (NODE1):
- Matches rule: helion_agent
- Uses LLM: local_qwen3_8b
- Calls Ollama API
- Generates response
↓
Response:
{
"ok": true,
"data": {
"text": "Привіт! Я - Helion, AI-агент..."
}
}
↓
MicroDaoOrchestratorChatEnhanced:
- Parses response
- Creates assistant message
- Adds to messages state
- UI updates automatically
↓
User: [Sees response in chat]
```
---
### 2. User uploads image
```
User: [Clicks 🖼️]
↓
MultimodalInput:
- Opens file picker
↓
User: [Selects image.jpg]
↓
MultimodalInput:
- Calls onImageUpload(file)
- Adds to attachedImages
- Shows preview
↓
User: [Types] "Що це?"
↓
User: [Clicks Send]
↓
MicroDaoOrchestratorChatEnhanced:
- Creates user message with image
- Converts image to base64
- Calls API with image data
↓
API Call:
POST /route
{
"agent": "helion",
"message": "Що це?",
"payload": {
"context": {
"system_prompt": "...",
"images": ["data:image/jpeg;base64,/9j/4AAQ..."]
}
}
}
↓
Router → LLM:
- Processes image (if vision model)
- Generates response
↓
User: [Sees response about the image]
```
---
### 3. User uploads file to knowledge base
```
User: [Opens KnowledgeBase section]
↓
User: [Drags document.pdf]
↓
KnowledgeBase:
- Validates file (size, type)
- Calls onUpload(file)
↓
MicroDaoOrchestratorChatEnhanced:
- Creates KnowledgeFile object
- Status: pending
- Adds to knowledgeFiles state
↓
knowledgeBaseService:
- uploadFile(agentId, file)
↓
API Call:
POST /api/knowledge/upload
FormData: {file, agent_id}
↓
Backend:
- Saves file
- Starts vectorization
- Returns file_id
↓
Background Processing:
1. Extract text from PDF
2. Create chunks
3. Generate embeddings
4. Store in Vector DB ✅
5. Extract entities
6. Create relationships
7. Store in Graph DB ✅
↓
Status Updates:
pending → vectorized → graphed → completed
↓
UI Updates:
- Shows progress
- Updates indicators
- Shows ✅ when done
```
---
## 💾 State Management
```typescript
// Main component state
interface ChatState {
// Messages
messages: ChatMessage[];
input: string;
// Multimodal
isRecording: boolean;
attachedImages: File[];
attachedFiles: File[];
// Knowledge Base
knowledgeFiles: KnowledgeFile[];
// System Prompt
systemPrompt: string;
// Telegram
telegramConnected: boolean;
telegramBotUsername?: string;
telegramBotToken?: string;
// UI
showKnowledgeBase: boolean;
showSystemPrompt: boolean;
showTelegram: boolean;
}
// React Query state
const sendMessageMutation = useMutation({
mutationFn: async (message: string) => {...},
onSuccess: (data) => {...},
onError: (error) => {...},
});
```
---
## 🎨 Styling System
```
Tailwind CSS Classes Structure:
Main Container:
- bg-white rounded-lg shadow-lg border
Headers:
- bg-gradient-to-r from-[color]-600 to-[color]-700
- Colors: purple (main), indigo (KB), amber (prompt), blue (telegram)
Buttons:
- Primary: bg-purple-600 hover:bg-purple-700
- Secondary: bg-gray-100 hover:bg-gray-200
- Success: bg-green-600 hover:bg-green-700
- Danger: bg-red-600 hover:bg-red-700
Messages:
- User: bg-purple-600 text-white (right aligned)
- Agent: bg-white border text-gray-800 (left aligned)
Status Indicators:
- Pending: text-yellow-500
- Success: text-green-600
- Error: text-red-500
- Info: text-blue-600
Icons: lucide-react
- 24px (h-6 w-6) for headers
- 20px (h-5 w-5) for buttons
- 16px (h-4 w-4) for inline icons
```
---
## 📦 File Structure Summary
```
Total Files Created: 12
Components (6):
✅ MicroDaoOrchestratorChatEnhanced.tsx (450+ lines)
✅ MicroDaoOrchestratorChatWrapper.tsx (50+ lines)
✅ chat/MultimodalInput.tsx (250+ lines)
✅ chat/KnowledgeBase.tsx (300+ lines)
✅ chat/SystemPromptEditor.tsx (200+ lines)
✅ chat/TelegramIntegration.tsx (250+ lines)
Services (3):
✅ voiceService.ts (150+ lines)
✅ webSearchService.ts (100+ lines)
✅ knowledgeBaseService.ts (200+ lines)
Index Files (2):
✅ chat/index.ts (5 lines)
✅ services/index.ts (5 lines)
Documentation (5):
✅ ORCHESTRATOR-CHAT-ENHANCED.md (800+ lines)
✅ INTEGRATION-EXAMPLE.md (500+ lines)
✅ ENHANCED-CHAT-SUMMARY.md (600+ lines)
✅ CHAT-ARCHITECTURE.md (400+ lines)
✅ CHAT-MESSAGE-FIX.md (200+ lines)
Total Lines of Code: ~4000+
```
---
## 🚀 Quick Reference
### Import Component
```tsx
import { MicroDaoOrchestratorChatEnhanced } from '@/components/microdao/MicroDaoOrchestratorChatEnhanced';
```
### Basic Usage
```tsx
<MicroDaoOrchestratorChatEnhanced
orchestratorAgentId="helion"
onClose={() => setShowChat(false)}
/>
```
### With Services
```tsx
import { voiceService, webSearchService, knowledgeBaseService } from '@/services';
// Voice
voiceService.startRecording(onResult, onError);
voiceService.speak("Привіт!");
// Web Search
const results = await webSearchService.search("query", "helion");
// Knowledge Base
await knowledgeBaseService.uploadFile("helion", file);
```
---
## 🎯 Key Features Matrix
| Feature | Component | Service | Status |
|---------|-----------|---------|--------|
| Text Chat | Main | - | ✅ |
| Voice Input | MultimodalInput | voiceService | ✅ |
| Voice Output | - | voiceService | ⏳ |
| Image Upload | MultimodalInput | - | ✅ |
| Image Recognition | - | Router API | ⏳ |
| File Upload | MultimodalInput | - | ✅ |
| Web Search | MultimodalInput | webSearchService | ✅ |
| Knowledge Base | KnowledgeBase | knowledgeBaseService | ✅ Frontend |
| System Prompt | SystemPromptEditor | - | ✅ Frontend |
| Telegram | TelegramIntegration | - | ✅ Frontend |
✅ = Готово
⏳ = Потрібна Backend реалізація
---
## 🔗 Related Documentation
- 📄 **ORCHESTRATOR-CHAT-ENHANCED.md** - Детальна документація
- 📄 **INTEGRATION-EXAMPLE.md** - Приклади використання
- 📄 **ENHANCED-CHAT-SUMMARY.md** - Підсумок виконаної роботи
- 📄 **CHAT-MESSAGE-FIX.md** - Виправлення bug
- 📄 **TIMEOUT-FIX.md** - Оптимізація таймаутів
---
**Дата створення:** 2025-11-23
**Статус:** ✅ Production Ready (Frontend)
Reference in New Issue View Git Blame Copy Permalink