# xerrors/yuxi-know architecture

> Architecture diagram of the GitHub repository xerrors/yuxi-know, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xerrors/yuxi-know
- Repository: https://github.com/xerrors/yuxi-know

## Overview

##### Project Overview & Main Components

- Purpose & Domain:
– The system integrates large language model (LLM) techniques with both a knowledge base and a Neo4j‐based knowledge graph.
– It is designed as a multi-model question/answer platform that supports several conversational models (OpenAI, SiliconFlow, Deepseek, etc.) and various document types.

- Primary Components to Represent:
a. Frontend: The Vue.js web interface (found under the “web” directory) that provides the UI.
b. Backend/API Server: Built using FastAPI (located in “src”, with the main entry in “src/main.py”) which provides the core business logic, routing (in “src/routers”), and agent frameworks (in “src/agents”).
c. Agents & Models: The “src/agents” and “src/models” directories encapsulate components such as chatbots, reactive agents, and integration with multiple language models.
d. External Services & Databases:
– Neo4j for the knowledge graph (configured and deployed via Docker in docker-compose files).
– Vector database support (and potential Milvus integration) for handling embeddings and document retrieval.
– External LLM APIs (e.g., SiliconFlow, OpenAI, Deepseek, etc.) used via API_KEY configurations.
e. Containerization & Deployment: Docker configuration files (in the “docker” folder and docker-compose YAML files) indicate a container-driven deployment with separate services for API, web frontend, and graph services.
f. Auxiliary Scripts & Tools: Scripts for managing model downloads, running deployment, and testing (in “scripts”), plus documentation (in “docs”).

##### Analyzing the File Structure & Architectural Patterns

- Modular Structure:
– The “src” folder encapsulates the backend logic, broken into submodules:
- “agents” for different conversational and reactive components.
- “core” for fundamental functions such as history, indexing, and knowledge base management.
- “models” for interfacing with different LLM providers.
- “routers” for API endpoints (chat, data, tools) showing a separation of concerns using routing.
– The clear differentiation between “src” and “web” demonstrates the separation of backend and frontend responsibilities.

- Containerization:
– Docker-related files (Dockerfiles for “api” and “web”, docker-compose YAML files) imply that each major service (API, Frontend, perhaps even Neo4j) is containerized individually.
– The inclusion of nginx configuration (in docker/nginx) suggests there is a reverse proxy/load balancing layer.

- External Integration:
– Environment configuration (via “src/.env.template”) and dynamic model configuration (through “src/static/models.yaml”) highlights that the backend is designed to support multiple external language model services and local model deployments (vllm, ollama integrations in “scripts/vllm”).

##### Final Recommendations

– Start by sketching high-level blocks (frontend, backend, databases, external services).
– Break down each block into subcomponents (e.g., the backend’s agents, models, routers).
– Ensure each component’s responsibilities, interactions, and technologies (FastAPI, Vue.js, Neo4j, Docker) are clearly labeled.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    UB["User Browser"]:::frontend

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Vue.js UI)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BM["Backend API (FastAPI Main)"]:::backend
        BR["API Routers"]:::backend
        AG["Conversational Agents"]:::microservice
        MD["Model Integrations"]:::microservice
        GB["GraphBase"]:::backend
        KB["KnowledgeBase"]:::backend
        ET["Env Template"]:::tool
        MC["Models Config"]:::tool
    end

    %% Data Services
    subgraph "Data Services"
        NEO["Neo4j Knowledge Graph"]:::database
        VEC["Vector Database"]:::database
        EXT["External LLM Providers"]:::database
    end

    %% Containerization & Deployment
    subgraph "Containerization & Deployment"
        DF["Docker Files"]:::container
        NGINX_node["NGINX Reverse Proxy"]:::container
        DC["Docker Compose"]:::container
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        AS["Auxiliary Scripts & Tools"]:::tool
    end

    %% Connections
    UB -->|"HTTP_Request"| FE
    FE -->|"APICall"| BM
    BM -->|"UsesRouters"| BR
    BM -->|"InvokesAgents"| AG
    BM -->|"CallsModels"| MD
    BM -->|"QueriesGraph"| GB
    BM -->|"QueriesKB"| KB
    AG -->|"Integrates"| EXT
    MD -->|"Calls"| EXT
    GB -->|"ExchangesData"| NEO
    KB -->|"ExchangesData"| VEC
    ET -->|"Configures"| AG
    ET -->|"Configures"| MD
    MC -->|"Configures"| AG
    MC -->|"Configures"| MD
    DF -->|"Hosts"| FE
    DF -->|"Hosts"| BM
    DF -->|"Hosts"| NEO
    DF -->|"Hosts"| NGINX_node
    NGINX_node -->|"RoutesTraffic"| FE
    DC -->|"Orchestrates"| DF
    AS -->|"Manages"| AG

    %% Click Events
    click FE "https://github.com/xerrors/yuxi-know/tree/main/web/"
    click BM "https://github.com/xerrors/yuxi-know/blob/main/src/main.py"
    click BR "https://github.com/xerrors/yuxi-know/tree/main/src/routers/"
    click AG "https://github.com/xerrors/yuxi-know/tree/main/src/agents/"
    click MD "https://github.com/xerrors/yuxi-know/blob/main/src/models/chat_model.py"
    click GB "https://github.com/xerrors/yuxi-know/blob/main/src/core/graphbase.py"
    click KB "https://github.com/xerrors/yuxi-know/blob/main/src/core/knowledgebase.py"
    click ET "https://github.com/xerrors/yuxi-know/blob/main/src/.env.template"
    click MC "https://github.com/xerrors/yuxi-know/blob/main/src/static/models.yaml"
    click DF "https://github.com/xerrors/yuxi-know/tree/main/docker/"
    click NGINX_node "https://github.com/xerrors/yuxi-know/tree/main/docker/nginx"
    click DC "https://github.com/xerrors/yuxi-know/blob/main/docker/docker-compose.dev.yml"
    click AS "https://github.com/xerrors/yuxi-know/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#00529B,stroke-width:2px;
    classDef backend fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef microservice fill:#fcf3cf,stroke:#d4ac0d,stroke-width:2px;
    classDef database fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef container fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef tool fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
