# kesoner/idol_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/kesoner/idol_mcp
- Repository: https://github.com/kesoner/idol_mcp

## Overview

##### Major Components
- Frontend Client:
- React-based user interface
- Live2D model display for emotion-rich visual representation
- Components for chat input, login, and real-time message updates
- Backend Server (MCP Server):
- FastAPI application acting as the central hub for interactions
- Core modules: Persona, Emotion Engine, Memory System, and LLM Service for generating responses
- Database:
- Manages conversation history, user profiles, and memory storage (the README mentions SQLite/MySQL/PostgreSQL)
- External APIs/LLM Service:
- Integration with external language model providers (e.g., Google 2 FLASH or OpenAI GPT)

##### Out the Relationships and Data Flow
- User Interactions:
- User sends a message via the frontend chat UI.
- Frontend transmits the message to the MCP Server over the API.
- Backend Processing:
- The MCP Server first routes the message to the Persona module (to determine tone and character-specific style).
- The Emotion Engine then calculates any required emotional adjustments.
- The Memory System handles context and stores conversation history.
- The LLM Service is invoked for natural language generation, customized to the avatar’s persona.
- Database Operations:
- Response Flow:
- Once a response is generated, it travels back through the server to the frontend, where it is rendered along with updated Live2D expressions and animations.

##### Architectural Patterns and Technologies
- Frontend-Backend Separation:
- RESTful API endpoints handling client-server communication.
- Modular and Layered Design:
- Integration Points:
- How the FastAPI server connects to external LLM providers and the database.
- Use of External Packages:
- Mentions of libraries used (e.g., React, FastAPI, SQLite/MySQL/PostgreSQL).
- Testing Layers:
- You might also indicate testing layers on both frontend (Vitest) and backend (pytest) as separate but related components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User"):::user

    subgraph "Frontend (React & Live2D)"
        ChatUI["Chat UI"]:::frontend
        Live2D["Live2D Model"]:::frontend
    end

    subgraph "Backend (MCP Server)"
        mcpServer["MCP Server (FastAPI)"]:::backend
        persona["Persona Module"]:::backend
        emotion["Emotion Engine"]:::backend
        memory["Memory System"]:::backend
        llm["LLM Service"]:::backend
    end

    database["Database"]:::database
    extLLM["External LLM Provider"]:::external

    User -->|"sendsMessage"| ChatUI
    ChatUI -->|"APIRequest"| mcpServer
    mcpServer -->|"process"| persona
    persona -->|"nextStep"| emotion
    emotion -->|"nextStep"| memory
    memory -->|"nextStep"| llm
    llm -->|"callExternal"| extLLM
    extLLM -->|"sendResponse"| llm
    mcpServer -->|"dbAccess"| database
    database -->|"dbUpdate"| mcpServer
    mcpServer -->|"response"| ChatUI
    mcpServer -->|"updateExpression"| Live2D

    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef user fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;

    click ChatUI "https://github.com/kesoner/idol_mcp/blob/master/frontend/src/components/Chat.jsx"
    click Live2D "https://github.com/kesoner/idol_mcp/blob/master/frontend/src/components/Live2DModel.jsx"
    click mcpServer "https://github.com/kesoner/idol_mcp/blob/master/src/idolmcp/main.py"
    click persona "https://github.com/kesoner/idol_mcp/tree/master/src/idolmcp/core/persona/"
    click emotion "https://github.com/kesoner/idol_mcp/blob/master/src/idolmcp/core/emotion/fsm.py"
    click memory "https://github.com/kesoner/idol_mcp/tree/master/src/idolmcp/core/memory/"
    click llm "https://github.com/kesoner/idol_mcp/tree/master/src/idolmcp/core/llm/"
    click database "https://github.com/kesoner/idol_mcp/blob/master/init_db.py"
```
