# fantasybot-red/project_af architecture

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

- Interactive diagram: https://gitdiagram.com/fantasybot-red/project_af
- Repository: https://github.com/fantasybot-red/project_af

## Overview

##### Project type and purpose
- This is a Python-based Discord bot (“AI Fantasy”) that demonstrates how AI can orchestrate and extend bot functionality beyond simple chat.
- It uses a plugin-style architecture (dynamic modules) and integrates with external AI services (via Huggingface) and Discord’s API for real-time interaction.

##### File structure
Top-level files
- main.py           – Bot entry point
- Dockerfile/.env  – Deployment and configuration
- requirements.txt  – Python dependencies
Directories
- classs/           – Core classes:
– FClient.py    (Discord API wrapper)
– AIContext.py  (conversation state manager)
– MCPManager.py (SSE-based extension manager)
– Module.py     (module interface/loader)
– MusicPlayer.py (audio playback helper)
- modules/          – Pre-built “tools” or functional plugins, e.g.:
– HuggingfaceSupport.py  (AI inference calls)
– MusicControl.py        (music commands)
– ContextSupport.py      (context utilities)
– DiscordExtraHelper.py  (extra Discord utilities)
- objs/             – Typed schemas for module arguments (EmbedArgs, Utilitys)
- resources/        – Static prompt files (system_prompt.txt)

##### Extract insights from the README
- Emphasizes unlimited extension via “MCP SSE” (Server-Sent Events)
- Modules are loaded dynamically and can be managed easily
- Deployment targets: native Python or Docker container

##### Main components
A. Core application
– main.py
– FClient (Discord event listener/dispatcher)
– AIContext (stateful context manager)
– MCPManager (extension/event bus)
– Module loader (dynamically binds modules)
B. Modules (plugins)
– HuggingfaceSupport (external AI inference)
– MusicControl/MusicPlayer (audio control)
– ContextSupport, DiscordExtraHelper
C. Data models
– objs/ schemas (argument validation, JSON Schema generator)
D. Static resources
– resources/system_prompt.txt
E. External services
– Discord API (gateway + REST)
– Huggingface (or other AI APIs)
F. Deployment
– Docker container or native environment (.env config)

##### Relationships & data flow
1) Discord → FClient: receives message/event
2) FClient → AIContext: updates conversation state
3) AIContext/MCPManager → Module loader: identify the module to handle the event
4) Module → objs schemas: validate/parse arguments
5) Module (e.g. HuggingfaceSupport) → External AI API → results
6) Module → FClient: send embed/message back to Discord
7) Optional: MusicPlayer → Discord voice channel

##### Architectural patterns & design principles
- Plugin architecture: Module interface + dynamic discovery
- Event-driven: FClient emits events, MCPManager routes to modules via SSE
- Separation of concerns:
- Networking (FClient)
- Business logic (Modules)
- State management (AIContext)
- Data validation (objs)
- Dependency injection via .env and requirements

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bot Core
    subgraph "Bot Core"
        main["main.py"]:::internal
        fc["FClient"]:::internal
        ctx["AIContext"]:::internal
        mcp["MCPManager"]:::internal
        loader["Module Loader"]:::internal
    end

    %% Plugins
    subgraph "Plugins"
        subgraph "AI Plugins"
            hs["HuggingfaceSupport"]:::plugin
        end
        subgraph "Music Plugins"
            mc["MusicControl"]:::plugin
        end
        subgraph "Utility Plugins"
            cs["ContextSupport"]:::plugin
            deh["DiscordExtraHelper"]:::plugin
        end
    end

    %% Data Models
    subgraph "Data Models"
        ea["EmbedArgs"]:::data
        us["Utilitys"]:::data
    end

    %% Static Resources
    resource["system_prompt.txt"]:::resource

    %% Deployment
    subgraph "Deployment"
        docker["Dockerfile"]:::deploy
        env[".env.template"]:::deploy
    end

    %% External Services
    clouddiscord["Discord API"]:::external
    cloudai["Huggingface API"]:::external

    %% Connections
    clouddiscord --> fc
    fc --> ctx
    ctx --> loader
    loader --> hs
    loader --> mc
    loader --> cs
    loader --> deh

    hs --> cloudai
    hs --> ea
    hs --> us

    mc --> fc
    mc --> ea

    cs --> ea
    deh --> fc

    ea --> loader
    us --> loader

    resource --> ctx

    docker --> main
    env --> main

    %% Click Events
    click main "https://github.com/fantasybot-red/project_af/blob/master/main.py"
    click fc "https://github.com/fantasybot-red/project_af/blob/master/classs/FClient.py"
    click ctx "https://github.com/fantasybot-red/project_af/blob/master/classs/AIContext.py"
    click mcp "https://github.com/fantasybot-red/project_af/blob/master/classs/MCPManager.py"
    click loader "https://github.com/fantasybot-red/project_af/blob/master/classs/Module.py"
    click hs "https://github.com/fantasybot-red/project_af/blob/master/modules/HuggingfaceSupport.py"
    click mc "https://github.com/fantasybot-red/project_af/blob/master/modules/MusicControl.py"
    click cs "https://github.com/fantasybot-red/project_af/blob/master/modules/ContextSupport.py"
    click deh "https://github.com/fantasybot-red/project_af/blob/master/modules/DiscordExtraHelper.py"
    click ea "https://github.com/fantasybot-red/project_af/blob/master/objs/EmbedArgs.py"
    click us "https://github.com/fantasybot-red/project_af/blob/master/objs/Utilitys.py"
    click resource "https://github.com/fantasybot-red/project_af/blob/master/resources/system_prompt.txt"
    click docker "https://github.com/fantasybot-red/project_af/tree/master/Dockerfile"
    click env "https://github.com/fantasybot-red/project_af/blob/master/.env.template"

    %% Styles
    classDef internal fill:#f9f,stroke:#333,stroke-width:1px
    classDef plugin fill:#afa,stroke:#333,stroke-width:1px
    classDef data fill:#fcf,stroke:#333,stroke-width:1px
    classDef resource fill:#ffc,stroke:#333,stroke-width:1px
    classDef deploy fill:#cff,stroke:#333,stroke-width:1px
    classDef external fill:#ccf,stroke:#333,stroke-width:1px
```
