# rodrigo-barraza/lupos architecture

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

- Interactive diagram: https://gitdiagram.com/rodrigo-barraza/lupos
- Repository: https://github.com/rodrigo-barraza/lupos

## Overview

##### Main components of the system
- Discord Integration Layer: This includes the various wrappers and the Discord service. Look for the files in “wrappers/DiscordWrapper.js” and “wrappers/DiscordWrapperNew.js” as well as “services/DiscordService.js.” These components will manage the communication with Discord’s API.
- Command Handling: The project divides “commands” into separate directories (one active “commands” folder with the “utility” subfolder and one “commands-unused”). Each file in these directories represents a specific bot command (e.g., alcohol.js, darkmoonfaire.js, etc.). This area is responsible for parsing, validating, and executing commands.
- Core Classes: “classes/RequestClass.js” and “classes/ResponseClass.js” likely encapsulate the incoming request data and outgoing response data used throughout the system. They represent an abstraction layer for communication between components.
- Services: There is a comprehensive “services” folder that contains modules addressing specific bot functionalities such as AI interaction, action handling, various state or game-like aspects (food, mood, hygiene, energy, etc.), and even a specialized WebHook service. These services act as the business logic layer.
- External API & Utility Integrations: Under “wrappers” there are multiple files like “OpenAIWrapper.js,” “AnthropicWrapper.js,” “BarkAIWrapper.js,” “LocalAIWrapper.js,” etc., which indicate the bot’s ability to integrate with external APIs (for AI services, image generation, etc.). There are also Puppeteer wrappers for UI automation.
- Configuration and Environmental Setup: The README highlights the need for configuration via a .env file with keys (OPENAI_KEY, TOKEN, etc.). This represents an external configuration aspect to the architecture.

##### Relationships and interactions
- Incoming Discord events (such as messages or reactions) are received by the Discord Integration Layer. These events flow into command handling logic.
- The command handler uses the Core Classes to parse commands and then delegates processing to the appropriate Service modules.
- The Service modules may call on various utilities or external API wrappers (e.g., for AI or image processing) to perform an action.
- Updated responses are then forwarded back through the messaging system via Discord Service, and possibly logged or processed further using the LoggingWrapper.

##### Architectural patterns and design principles
- Modularization: Commands, services, and wrappers are neatly separated. This ensures that each functional unit of the bot is decoupled, facilitating easier testing and updates.
- Dependency Injection / Abstraction: Wrappers and classes abstract the details of the external APIs and Discord library operations.
- Separation of concerns: By isolating business logic in service modules and keeping command definitions separate, the design adheres to good object-oriented practices.
- Extensibility: There is a “commands-unused” folder which might indicate a history of experimental commands and a potential for future expansion or refactoring.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    subgraph "Configuration"
        CONFIG[".env Configuration"]:::config
    end

    subgraph "Discord Integration Layer"
        DW["DiscordWrapper"]:::discord
        DWN["DiscordWrapperNew"]:::discord
        DS["DiscordService"]:::discord
    end

    subgraph "Command Handling"
        subgraph "Utility Commands"
            CMD_ALCOHOL["alcohol.js"]:::command
            CMD_DARKMOON["darkmoonfaire.js"]:::command
            CMD_DRINK["drink.js"]:::command
        end
        subgraph "Legacy Commands"
            CMD_MOON["moon.js"]:::command
            CMD_SERVER["server.js"]:::command
            CMD_STATS["stats.js"]:::command
            CMD_USER["user.js"]:::command
        end
    end

    subgraph "Core Classes"
        RC["RequestClass"]:::core
        RSP["ResponseClass"]:::core
    end

    subgraph "Services Layer"
        AI["AIService"]:::services
        ACT["ActionService"]:::services
        ALC_S["AlcoholService"]:::services
        BATH_S["BathroomService"]:::services
        DMF_S["DarkmoonFaireService"]:::services
        DUNGEON_S["DungeonTimerService"]:::services
        ENERGY_S["EnergyService"]:::services
        FOOD_S["FoodService"]:::services
        HOLIDAY_S["HolidayService"]:::services
        HUNGER_S["HungerService"]:::services
        HYGIENE_S["HygieneService"]:::services
        MESSAGE_S["MessageService"]:::services
        MOOD_S["MoodService"]:::services
        SICKNESS_S["SicknessService"]:::services
        THIRST_S["ThirstService"]:::services
        YAPPER_S["YapperService"]:::services
        WEBHOOK_S["WebHookService"]:::services
        POST_WEBHOOK["PostWebHook Route"]:::services
        UTIL_S["Consolidated Services"]:::services
    end

    subgraph "External API & Utility Wrappers"
        OPENAI["OpenAIWrapper"]:::external
        ANTHROPIC["AnthropicWrapper"]:::external
        BARK["BarkAIWrapper"]:::external
        LOCALAI["LocalAIWrapper"]:::external
        COMFYUI["ComfyUIWrapper"]:::external
        LIGHT["LightWrapper"]:::external
        PUPP1["PuppeteerWrapper"]:::external
        PUPP2["PuppeteerWrapper2"]:::external
        LOGGING["LoggingWrapper"]:::external
    end

    %% Data Flow Connections
    CONFIG --> DS
    DS -->|"receives Discord events"| CMD_ALCOHOL
    DS --> CMD_DARKMOON
    DS --> CMD_DRINK
    DS --> CMD_MOON
    DS --> CMD_SERVER
    DS --> CMD_STATS
    DS --> CMD_USER

    %% Command Handling to Core Processing
    CMD_ALCOHOL --> RC
    CMD_DARKMOON --> RC
    CMD_DRINK --> RC
    CMD_MOON --> RC
    CMD_SERVER --> RC
    CMD_STATS --> RC
    CMD_USER --> RC

    RC -->|"parses command"| RSP

    %% Core triggers Services
    RSP -->|"invokes"| AI
    RSP --> ACT
    RSP --> ALC_S
    RSP --> BATH_S
    RSP --> DMF_S
    RSP --> DUNGEON_S
    RSP --> ENERGY_S
    RSP --> FOOD_S
    RSP --> HOLIDAY_S
    RSP --> HUNGER_S
    RSP --> HYGIENE_S
    RSP --> MESSAGE_S
    RSP --> MOOD_S
    RSP --> SICKNESS_S
    RSP --> THIRST_S
    RSP --> YAPPER_S
    RSP --> WEBHOOK_S
    RSP --> POST_WEBHOOK
    RSP --> UTIL_S

    %% Services call External API Wrappers
    AI --> OPENAI
    AI --> ANTHROPIC
    ACT --> BARK
    ALC_S --> LOCALAI
    DMF_S --> COMFYUI
    ENERGY_S --> LIGHT
    FOOD_S --> PUPP1
    MOOD_S --> PUPP2

    %% Logging integration
    UTIL_S --> LOGGING
    MESSAGE_S --> LOGGING
    WEBHOOK_S --> LOGGING

    %% Services send responses via Discord Service
    MESSAGE_S --> DS

    %% Click Events for Components
    click DW "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/DiscordWrapper.js"
    click DWN "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/DiscordWrapperNew.js"
    click DS "https://github.com/rodrigo-barraza/lupos/blob/master/services/DiscordService.js"

    click CMD_ALCOHOL "https://github.com/rodrigo-barraza/lupos/blob/master/commands/utility/alcohol.js"
    click CMD_DARKMOON "https://github.com/rodrigo-barraza/lupos/blob/master/commands/utility/darkmoonfaire.js"
    click CMD_DRINK "https://github.com/rodrigo-barraza/lupos/blob/master/commands/utility/drink.js"
    click CMD_MOON "https://github.com/rodrigo-barraza/lupos/blob/master/commands-unused/moon.js"
    click CMD_SERVER "https://github.com/rodrigo-barraza/lupos/blob/master/commands-unused/server.js"
    click CMD_STATS "https://github.com/rodrigo-barraza/lupos/blob/master/commands-unused/stats.js"
    click CMD_USER "https://github.com/rodrigo-barraza/lupos/blob/master/commands-unused/user.js"

    click RC "https://github.com/rodrigo-barraza/lupos/blob/master/classes/RequestClass.js"
    click RSP "https://github.com/rodrigo-barraza/lupos/blob/master/classes/ResponseClass.js"

    click AI "https://github.com/rodrigo-barraza/lupos/blob/master/services/AIService.js"
    click ACT "https://github.com/rodrigo-barraza/lupos/blob/master/services/ActionService.js"
    click ALC_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/AlcoholService.js"
    click BATH_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/BathroomService.js"
    click DMF_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/DarkmoonFaireService.js"
    click DUNGEON_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/DungeonTimerService.js"
    click ENERGY_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/EnergyService.js"
    click FOOD_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/FoodService.js"
    click HOLIDAY_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/HolidayService.js"
    click HUNGER_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/HungerService.js"
    click HYGIENE_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/HygieneService.js"
    click MESSAGE_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/MessageService.js"
    click MOOD_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/MoodService.js"
    click SICKNESS_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/SicknessService.js"
    click THIRST_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/ThirstService.js"
    click YAPPER_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/YapperService.js"
    click WEBHOOK_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/WebHookService/WebHookService.js"
    click POST_WEBHOOK "https://github.com/rodrigo-barraza/lupos/blob/master/services/WebHookService/routes/PostWebHook.js"
    click UTIL_S "https://github.com/rodrigo-barraza/lupos/blob/master/services/services.js"

    click OPENAI "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/OpenAIWrapper.js"
    click ANTHROPIC "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/AnthropicWrapper.js"
    click BARK "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/BarkAIWrapper.js"
    click LOCALAI "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/LocalAIWrapper.js"
    click COMFYUI "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/ComfyUIWrapper.js"
    click LIGHT "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/LightWrapper.js"
    click PUPP1 "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/PuppeteerWrapper.js"
    click PUPP2 "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/PuppeteerWrapper2.js"
    click LOGGING "https://github.com/rodrigo-barraza/lupos/blob/master/wrappers/LoggingWrapper.js"

    %% Styles
    classDef discord fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef command fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef core fill:#ccffff,stroke:#006666,stroke-width:2px;
    classDef services fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef external fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
    classDef config fill:#e0e0e0,stroke:#666666,stroke-width:2px;
```
