# zumitoteam/zumito-framework architecture

> Architecture diagram of the GitHub repository zumitoteam/zumito-framework, 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/zumitoteam/zumito-framework
- Repository: https://github.com/zumitoteam/zumito-framework

## Overview

##### Main Components
- Framework Core: At the heart is the main entry point (ZumitoFramework.ts) that initializes the bot, sets up Discord.js integrations, and wires all the services.
- Definitions & Contracts: The “src/definitions” folder contains type definitions (commands, errors, events, settings, APIs, parameters, decorators) that form the system’s contract layer. This forms the backbone for enforcing structure in the framework.
- Services: In “src/services” you find the essential modules (e.g., CommandParser, EmojiFallback, InteractionIdGenerator) and service managers (CommandManager, EventManager, ModuleManager, StatusManager, TranslationManager). These services encapsulate domain-specific logic and operations.
- Core Modules: Under “src/modules” the “core” folder – especially “baseModule” – provides a template for building modular components of your bot. It handles Discord events (like InteractionCreate, MessageCreate) and related models (e.g., Guild).
- Discord Integration: The “src/discord” directory indicates dedicated code handling Discord-specific initializations and event listeners, ensuring the bot can interact properly with Discord’s ecosystem.
- Utilities: The “src/services/utilities” folder holds helper classes (like DatabaseConfigLoader, GuildDataGetter, InviteUrlGenerator, etc.) that provide ancillary functionality to support the main services and modules.
- External Dependencies: Notice the integration and reliance on libraries like Discord.js and Express, as noted in the README. These are crucial for communication with the Discord API and (potentially) for providing a web dashboard later on.

##### Relationships and Interactions
- The Framework Core (ZumitoFramework.ts) acts as the orchestrator. It initializes the services, registers modules, and starts both the Discord and HTTP (Express) integrations.
- The Services layer (managers and handlers) interacts with the Core to process incoming commands and events. Each manager (for commands, events, modules, etc.) handles a specific part of the bot’s logic and uses definitions as contracts.
- The Definitions layer informs every part of the system (services, modules, and decorators like Injectable) ensuring type safety and consistency.
- The Discord integration code communicates with Discord's API through Discord.js, feeding events into pre-defined handlers.
- Utility components supply the underlying support for tasks like generating invite URLs, merging configuration objects, or formatting texts.

##### Architectural Patterns and Design Principles
- Modular Architecture: The separation between “core modules”, “services”, and “definitions” encourages reusability and ease of integration.
- Dependency Injection: With decorators (such as in “src/definitions/decorators/Injectable.decorator.ts”), the design promotes loose coupling and testability.
- DRY Principle: The framework abstracts common bot functionalities (command and event handling, status management) to remove repetition across bots built on it.
- Layered Design: Having a distinct “definitions” layer separate from logic (services, modules) makes the framework more maintainable and scalable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Layer"
        FrameworkCore["Framework Core"]:::coreLayer
    end

    %% Definitions Layer
    subgraph "Definitions Layer"
        Definitions["Definitions & Contracts"]:::definitions
    end

    %% Services Layer
    subgraph "Services Layer"
        MainServices["Main Services"]:::services
        ServiceManagers["Service Managers"]:::services
        ServiceHandlers["Service Handlers"]:::services
        Utilities["Utilities"]:::services
    end

    %% Modules Layer
    subgraph "Modules Layer"
        CoreModules["Core Modules"]:::modules
    end

    %% Discord and External Integration
    subgraph "Discord & External Integration"
        DiscordIntegration["Discord Integration"]:::integration
        ExternalDiscordJS["Discord.js"]:::external
        ExternalExpress["Express"]:::external
        ExternalNode["Node.js"]:::external
    end

    %% Relationships
    FrameworkCore -->|"initializes"| MainServices
    MainServices -->|"comprises"| ServiceManagers
    MainServices -->|"comprises"| ServiceHandlers
    MainServices -->|"includes"| Utilities
    ServiceManagers -->|"uses"| Definitions
    ServiceHandlers -->|"uses"| Definitions

    FrameworkCore -->|"registers"| CoreModules
    FrameworkCore -->|"connects"| DiscordIntegration
    CoreModules -->|"triggersEvent"| DiscordIntegration

    DiscordIntegration <-->|"communicates"| ExternalDiscordJS
    FrameworkCore -->|"startsHTTP"| ExternalExpress
    ExternalNode -->|"runs"| FrameworkCore

    %% Click Events
    click FrameworkCore "https://github.com/zumitoteam/zumito-framework/blob/master/src/ZumitoFramework.ts"
    click Definitions "https://github.com/zumitoteam/zumito-framework/tree/master/src/definitions"
    click MainServices "https://github.com/zumitoteam/zumito-framework/tree/master/src/services"
    click ServiceManagers "https://github.com/zumitoteam/zumito-framework/tree/master/src/services/managers"
    click ServiceHandlers "https://github.com/zumitoteam/zumito-framework/tree/master/src/services/handlers"
    click Utilities "https://github.com/zumitoteam/zumito-framework/tree/master/src/services/utilities"
    click CoreModules "https://github.com/zumitoteam/zumito-framework/tree/master/src/modules/core/baseModule"
    click DiscordIntegration "https://github.com/zumitoteam/zumito-framework/tree/master/src/discord"

    %% Styles
    classDef coreLayer fill:#ccf,stroke:#333,stroke-width:2px;
    classDef definitions fill:#cfc,stroke:#333,stroke-width:2px;
    classDef services fill:#fcf,stroke:#333,stroke-width:2px;
    classDef modules fill:#ffc,stroke:#333,stroke-width:2px;
    classDef integration fill:#cff,stroke:#333,stroke-width:2px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;
```
