# xs-h/chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/xs-h/chatbot
- Repository: https://github.com/xs-h/chatbot

## Overview

##### Project Type and Purpose
- This is a full-stack, microservice-based chatbot system (“心语智友”) that integrates three core AI capabilities:
a. ASR (Automatic Speech Recognition) via a Django service in Docker
b. Chat/LLM inference via a Python-based “chat_backend” using Ollama or llama.cpp models
c. TTS (Text-to-Speech) via CosyVoice in the “tts_backend”
- A simple static frontend delivers a web UI for voice input/output and text chat.

##### High-Level File/Directory Analysis
- Top‐level “frontend”: static HTML/CSS/JS UI
- “backend”: three subfolders:
- asr_backend: Django REST API for speech-to-text, deployable via Docker Compose
- chat_backend: Python modules (chat.py, rag.py) calling an LLM via HuggingFaceEmbeddings & Ollama
- tts_backend: Python scripts wrapping CosyVoice for speech synthesis
- “resource”: local knowledge bases, vector indices, reference audios
- “logs”: service logs for chat and TTS
- Root “start.py”: orchestration script launching Chat and TTS services
- Conda & requirements files, Docker files, and project documentation

##### Key README Insights
- start.py boots LLM + TTS services; ASR runs separately in Docker
- Frontend JS (chatbot_dynamic.js) calls three HTTP endpoints: /asr, /chat, /tts
- External dependencies: PyTorch, FAISS, ONNX Runtime, Ollama, CosyVoice models
- Resource folder drives RAG (retrieval-augmented generation) and TTS reference audio

a. Main Components
1. User Browser (Web UI)
2. Static Frontend (index.html, chatbot_dynamic.js, styles.css)
3. ASR Service (Django app in Docker)
4. Chat Service (chat_backend Python APIs + Ollama/llama.cpp LLM engine)
5. TTS Service (tts_backend invoking CosyVoice)
6. Model Engines & Data Stores
‑ Ollama/llama.cpp LLM runtime
‑ CosyVoice TTS models
‑ Resource Store (JSON knowledge files, FAISS index)
7. Logs & Monitoring (chat_api.log, tts_api.log)

b. Relationships & Interactions
- Browser → HTTP POST /asr → ASR Service → TranscribeTask → returns text
- Browser → HTTP POST /chat → Chat Service →
- optional RAG lookup against resource/vector DB
- call local Ollama/llama.cpp model → returns reply text
- Browser → HTTP POST /tts → TTS Service → CosyVoice pipeline → returns audio stream
- start.py orchestrates Chat and TTS service processes
- ASR Service deployed independently via Docker Compose

c. Architectural Patterns & Principles
- Microservices: separate containers/services for ASR, Chat, TTS
- RAG: retrieval-augmented generation using FAISS vector store + JSON KB
- Modular Python: Django for ASR, FastAPI or Flask-like for Chat/TTS
- Orchestration script (start.py) to spin up in-process services

d. Technologies & Frameworks
- Django + Docker for ASR
- Python 3.10, FastAPI/Flask style for Chat & TTS
- Ollama or llama.cpp for LLM inference
- CosyVoice (ONNX + PyTorch) for TTS
- FAISS for vector search, HuggingFaceEmbeddings for RAG
- Conda environments, Docker Compose, Git LFS

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        Browser["User Browser"]:::ui
        index["index.html"]:::ui
        js["chatbot_dynamic.js"]:::ui
        css["styles.css"]:::ui
    end

    Browser --> index
    Browser --> js
    Browser --> css

    subgraph "API Layer"
        ASR["ASR Service (Django)"]:::service
        Chat["Chat Service (Python + Ollama)"]:::service
        TTS["TTS Service (CosyVoice)"]:::service
    end

    Browser -->|"POST /asr"| ASR
    ASR -->|"transcript"| Browser
    Browser -->|"POST /chat"| Chat
    Chat -->|"reply text"| Browser
    Browser -->|"POST /tts"| TTS
    TTS -->|"audio stream"| Browser

    start["start.py"]:::service
    start --> Chat
    start --> TTS

    subgraph "AI Engines"
        RAG["RAG & FAISS"]:::engine
        LLM["Ollama/llama.cpp"]:::engine
        TV["CosyVoice Models"]:::engine
        Whisper["WhisperTranscriber"]:::engine
    end

    Chat --> RAG
    RAG --> LLM
    TTS --> TV
    ASR --> Whisper

    subgraph "Data/Models"
        KB["NeZha.json"]:::data
        FAISS["index.faiss"]:::data
        PKL["index.pkl"]:::data
    end

    Chat --> KB
    Chat --> FAISS
    Chat --> PKL
    TTS --> KB

    subgraph "Logs"
        log1["chat_api.log"]:::data
        log2["tts_api.log"]:::data
    end

    Chat --> log1
    TTS --> log2

    classDef ui fill:#a3d5ff,stroke:#0366d6,color:#0366d6;
    classDef service fill:#c3f0c1,stroke:#2d7f34,color:#2d7f34;
    classDef engine fill:#ffd591,stroke:#cc7a00,color:#cc5500;
    classDef data fill:#ffe0b3,stroke:#cc9900,color:#cc9900;

    click index "https://github.com/xs-h/chatbot/blob/main/frontend/index.html"
    click js "https://github.com/xs-h/chatbot/blob/main/frontend/chatbot_dynamic.js"
    click css "https://github.com/xs-h/chatbot/blob/main/frontend/styles.css"
    click ASR "https://github.com/xs-h/chatbot/tree/main/backend/asr_backend/"
    click Chat "https://github.com/xs-h/chatbot/blob/main/backend/chat_backend/chat_api.py"
    click TTS "https://github.com/xs-h/chatbot/blob/main/backend/tts_backend/tts_api.py"
    click start "https://github.com/xs-h/chatbot/blob/main/start.py"
    click KB "https://github.com/xs-h/chatbot/blob/main/resource/database/NeZha.json"
    click FAISS "https://github.com/xs-h/chatbot/blob/main/resource/database/index.faiss"
    click PKL "https://github.com/xs-h/chatbot/blob/main/resource/database/index.pkl"
    click log1 "https://github.com/xs-h/chatbot/blob/main/logs/chat_api.log"
    click log2 "https://github.com/xs-h/chatbot/blob/main/logs/tts_api.log"
```
