Overview

Everything Medusa executes at runtime lives inside a module. All native features (starting with the core module) run as modules. Custom modules load identically, receive the identical runtime primitives, and have full access to Medusa's database, Discord gateway, HTTP router, web dashboard, audit logs, and localization systems.

Module Architecture

Each directory located directly in modules/ represents an isolated module. On boot, Medusa scans the directory, imports main.js, constructs the exported module class, and recursively registers and loads every subsystem located within src/ and resources/.

modules/
  example/
    main.js
    resources/
      cards/
      config/
      dashboard/
        pages/
      emojis/
      lang/
      leaderboards/
      logs/
      nodes/
      placeholders/
      posts/
    src/
      clocks/
      commands/
      events/
      handlers/
      models/
      routes/

Loading Lifecycle

Medusa initializes modules only after the internal API is listening and the dashboard reports ready. If either fails to start, boot stops before any module registers. Modules then load in two strict phases:

1. Registration Phase: Medusa verifies licensing, installs any missing dependencies.node packages, initializes schemas, loads configuration groups, language dictionaries, logging categories, leaderboard providers, post providers, automation flow nodes, database models, HTTP routes, and custom dashboard pages.
2. Loading Phase: Medusa initializes handlers, Discord slash and prefix commands, Discord gateway events, and scheduled clocks. Medusa then triggers onStartup(), syncs database tables, mounts HTTP routes on the API server, and registers cron schedules.

Per-Server Modules

Every installed module loads once for the whole bot, but each server can turn modules on or off from the dashboard Modules page. Changes apply immediately, with no restart. When a module is off in a server, Medusa:

• Leaves its slash commands out of that server's command sync and blocks its prefix commands and autocomplete.
• Answers its buttons, select menus, and modals (medusa:<component>:<module>:... ids) with the core moduleDisabled warning.
• Skips its Discord and internal events when the payload resolves to that server (guildId, guild, or message.guildId).
• Hides its dashboard pages, configs, logging groups, leaderboard metrics, and /help entries for that server, and its routes answer 404 to dashboard requests scoped to that server.
• Skips its automation nodes in flows running in that server.

Clocks run once for the whole bot, so a clock that loops over servers or posts into channels must check the server itself:

for (const guild of this.medusa.discord.client.guilds.cache.values()) {
    if (!this.medusa.modules.enabled(this.module, guild.id)) continue;
}

Dashboard requests carry the selected server in the x-guild-id header, so module routes can read it from request.headers["x-guild-id"].

When Medusa shuts down or a module is deloaded, Medusa stops all running clocks, triggers onShutdown(), unmounts routes, and closes resources cleanly.

Subsystem Layout

Medusa loads files automatically based on folder location and filename conventions:

Base Module Class

Every module entrypoint (modules/<name>/main.js) must export a default or named class extending Modules imported from #medusa/modules.

import { Modules } from "#medusa/modules";

export class ExampleModule extends Modules {
    constructor(medusa) {
        super(medusa, {
            name: "example",
            displayName: "Example",
            icon: "puzzle",
            author: "Zero Development",
            version: "1.0.0.0",
            description: "Production ready example module for Medusa.",
            dependencies: {
                hard: "",
                soft: "",
                node: []
            }
        });
    }

    permissions() {
        return [
            {
                id: "example:manage",
                name: "Example ( Manage )",
                description: "Administrative access to configure and manage example items.",
                group: "Example",
                module: "example"
            }
        ];
    }

    async onStartup() {
        this.medusa.console.log(this.medusa.console.levels.startup, `${this.getName()} module initialized successfully.`);
    }

    async onShutdown() {
        this.medusa.console.log(this.medusa.console.levels.info, `${this.getName()} module deloaded.`);
    }
}

Module Metadata Properties

The configuration object passed to super(medusa, meta) accepts the following properties:

Renaming a Module

Rename the folder and name, then list the old id in formerly so existing servers keep their settings:

super(medusa, {
    name: "join-to-create",
    formerly: ["voicehub"],
    displayName: "Join to Create"
});

Rename config groups and log categories that started with the old id to the camelCase form of the new id (voicehub becomes joinToCreate, voicehubEvents becomes joinToCreateEvents) so the migrated values line up. Give renamed models a formerly table name too.

If the old folder is still on disk, the loader skips it with a warning so both ids never load together. For official modules, the release build records every rename in package.json under formerly, and the auto-updater installs the renamed module into its new folder and deletes the old one. A folder listed in MODULE_FROZEN is never deleted.

Module Methods

The Modules class provides the following built-in methods:

Library Exports: #medusa/modules

Modules import all required base classes from the #medusa/modules import alias:

import {
    Modules,
    Commands,
    Events,
    Clocks,
    Models,
    Routes,
    Handlers,
    Pages,
    Configs,
    Langs,
    Logs,
    Leaderboards,
    Posts,
    Nodes
} from "#medusa/modules";

Cross-Module Communication

Every subsystem receives the root medusa instance. The this.medusa.modules manager allows any module to access any registered subsystem across the entire bot:

const economyHandler = this.medusa.modules.handlers.get("economy", "balances");
const ticketsModel = this.medusa.modules.models.get("ticket", "ticket_tickets");
const moderationRoute = this.medusa.modules.routes.get("moderation", "cases");
const coreCommand = this.medusa.modules.commands.get("core", "ping");
const configuredCurrency = this.medusa.modules.config.value("economy", "settings", "currencySymbol");
const localizedWelcome = this.medusa.modules.lang.phrase("core", "messages", "welcome", { user: interaction.user.id });

Module Registry Accessors