# plyoox/plyoox-v3 architecture

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

- Interactive diagram: https://gitdiagram.com/plyoox/plyoox-v3
- Repository: https://github.com/plyoox/plyoox-v3

## Overview

##### Main Components
- Bot Core/Launcher:
- Central entry point (src/launcher.py and src/main.py) that initializes the bot.
- This is responsible for loading extensions, setting up database connections, and establishing the environment (like reading the .env variables for PostgreSQL and Discord token).

- Extensions/Cogs:

- Libraries and Utilities:
- Helper libraries (located in src/lib and src/utils) that provide functions for database interactions, caching, messaging, formatting, and error handling.
- Subcomponents such as:
– Cache Manager and Models (src/cache)
– Database helper (src/lib/database.py)
– Parsing, formatting, and types modules (src/lib/parsers.py, src/lib/types)

- gRPC Services:
- RPC subsystem running under src/rpc, including:
– Generated gRPC service definitions (e.g., twitch, youtube, cache).
– The server component that listens for and processes remote calls (src/rpc/grpc_server.py and src/rpc/service).
- This shows how your bot may communicate with external or microservice-based modules via the gRPC layer.

- Translation Module:
- Translation subsystem (src/translation) that handles internationalization — building message catalogs, merging translations, and providing locale-based outputs.

- External Dependencies & Environment:
– Discord (the API service that the bot interacts with).
– PostgreSQL (the database configured via environment variables).
– External webhook logging services if LOGGING_WEBHOOK_ID and TOKEN are provided.
- Also, there’s evidence of containerization (Dockerfile, .dockerignore) which might be noted in deployment concerns.

##### Relationships and Interactions
- Extensions to the Libraries/Utilities to show that they leverage shared functionality (like database operations, caching, error handling).
- Link the Translator module to the Bot Core and any UI/response component, illustrating that messages or command outputs can be localized.

##### Architectural Patterns & Design Principles
- The overall design demonstrates modularity reminiscent of the “cogs” approach typical in Discord bots, promoting separation of concerns.
- The use of shared libraries for common functions (e.g., formatting, database, cache) supports DRY principles.
- The RPC subsystem suggests a microservices-like pattern for handling certain asynchronous/external work, decoupling internal operations.
- A layered architecture: core launcher --> extension/cog layer --> utility libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Bot Core/Launcher"]
    subgraph "Extensions/Cogs"
        A1["Anilist Extension"]
        A2["Moderation Extension"]
        A3["Fun Extension"]
        A4["Infos Extension"]
        A5["Leveling Extension"]
        A6["Notification Extension"]
        A7["Owner Extension"]
        A8["Statistics Extension"]
        A9["Timers Extension"]
        A10["Welcome Extension"]
    end
    subgraph "Libraries & Utilities"
        L1["Shared Libraries"]
        L2["Caching & Helpers"]
        L3["Utilities"]
    end
    subgraph "gRPC Services"
        G1["gRPC Server"]
        G2["gRPC Implementations"]
        G3["gRPC Definitions"]
    end
    T["Translation Module"]
    subgraph "External Services"
        D["Discord API"]
        P["PostgreSQL"]
        W["Logging Webhook"]
    end

    %% Bot Core loads Extensions
    A -->|"loads_extensions"| A1
    A -->|"loads_extensions"| A2
    A -->|"loads_extensions"| A3
    A -->|"loads_extensions"| A4
    A -->|"loads_extensions"| A5
    A -->|"loads_extensions"| A6
    A -->|"loads_extensions"| A7
    A -->|"loads_extensions"| A8
    A -->|"loads_extensions"| A9
    A -->|"loads_extensions"| A10

    %% Bot Core initializes shared libraries and utilities
    A -->|"initializes"| L1
    A -->|"initializes"| L2
    A -->|"initializes"| L3

    %% Bot Core communicates with gRPC services
    A -->|"calls_RPC"| G1
    A -->|"calls_RPC"| G2
    A -->|"calls_RPC"| G3

    %% Bot Core integrates translation capabilities
    A -->|"localizes_output"| T

    %% Bot Core connects to external services
    A -->|"communicates_with"| D
    A -->|"connects_to"| P
    A -->|"sends_logs_to"| W

    %% Extensions use shared libraries
    A1 -->|"uses_library"| L1
    A2 -->|"uses_library"| L1
    A3 -->|"uses_library"| L1
    A4 -->|"uses_library"| L1
    A5 -->|"uses_library"| L1
    A6 -->|"uses_library"| L1
    A7 -->|"uses_library"| L1
    A8 -->|"uses_library"| L1
    A9 -->|"uses_library"| L1
    A10 -->|"uses_library"| L1

    %% Some Extensions also use caching functionality
    A1 -->|"calls_cache"| L2
    A2 -->|"calls_cache"| L2
    A3 -->|"calls_cache"| L2

    %% Extensions communicate with gRPC implementations when needed
    A1 -->|"calls_RPC"| G2
    A2 -->|"calls_RPC"| G2
    A3 -->|"calls_RPC"| G2

    %% Translation module provides localization support to Bot Core
    T -->|"provides_translation_to"| A

    %% Click Events for Bot Core/Launcher
    click A "https://github.com/plyoox/plyoox-v3/blob/main/src/launcher.py"
    click A "https://github.com/plyoox/plyoox-v3/blob/main/src/main.py"

    %% Click Events for Extensions/Cogs
    click A1 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Anilist/anilist_cog.py"
    click A2 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Moderation/moderation_cog.py"
    click A3 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Fun/fun_group.py"
    click A4 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Infos/infos_cog.py"
    click A4 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Infos/guild_group.py"
    click A4 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Infos/user_group.py"
    click A5 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Leveling.py"
    click A6 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Notification.py"
    click A7 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Owner.py"
    click A8 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Statistics.py"
    click A9 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Timers.py"
    click A10 "https://github.com/plyoox/plyoox-v3/blob/main/src/extensions/Welcome.py"

    %% Click Events for Libraries and Utilities
    click L1 "https://github.com/plyoox/plyoox-v3/tree/main/src/lib"
    click L1 "https://github.com/plyoox/plyoox-v3/blob/main/src/lib/database.py"
    click L1 "https://github.com/plyoox/plyoox-v3/blob/main/src/lib/parsers.py"
    click L1 "https://github.com/plyoox/plyoox-v3/blob/main/src/lib/formatting.py"
    click L1 "https://github.com/plyoox/plyoox-v3/tree/main/src/lib/types"
    click L2 "https://github.com/plyoox/plyoox-v3/tree/main/src/cache"
    click L2 "https://github.com/plyoox/plyoox-v3/blob/main/src/cache/manager.py"
    click L2 "https://github.com/plyoox/plyoox-v3/blob/main/src/cache/models.py"
    click L2 "https://github.com/plyoox/plyoox-v3/blob/main/src/lib/message_cache.py"
    click L3 "https://github.com/plyoox/plyoox-v3/tree/main/src/utils"

    %% Click Events for gRPC Services
    click G1 "https://github.com/plyoox/plyoox-v3/blob/main/src/rpc/grpc_server.py"
    click G2 "https://github.com/plyoox/plyoox-v3/tree/main/src/rpc/service"
    click G3 "https://github.com/plyoox/plyoox-v3/tree/main/src/rpc/generated"

    %% Click Event for Translation Module
    click T "https://github.com/plyoox/plyoox-v3/tree/main/src/translation"

    %% Styles
    classDef core fill:#f96,stroke:#333,stroke-width:2px;
    classDef extension fill:#bbf,stroke:#333,stroke-width:2px;
    classDef library fill:#dfd,stroke:#333,stroke-width:2px;
    classDef grpc fill:#fdd,stroke:#333,stroke-width:2px;
    classDef translation fill:#ffd,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;

    %% Assign classes
    class A core;
    class A1,A2,A3,A4,A5,A6,A7,A8,A9,A10 extension;
    class L1,L2,L3 library;
    class G1,G2,G3 grpc;
    class T translation;
    class D,P,W external;
```
