Overview

Architectural overview of Medusa, module lifecycles, and core building blocks for developers.

Medusa is architected around an isolated module engine. Every feature in the bot (whether moderation, ticketing, leveling, or games) is implemented as an independent module. Modules register their commands, database models, events, API routes, and dashboard schemas with the core kernel on boot.

This section covers how to develop, extend, and integrate with Medusa.

Architecture Principles

Medusa adheres to strict design conventions:

Strict Handler Pattern: Business logic is encapsulated in handlers. There are no arbitrary utility or library directories; logic belongs in handlers/.
Resource Separation: Code belongs in src/, while configuration schemas, localization dictionaries, and documentation live in resources/.
Zero Hardcoded UI: The web dashboard does not contain hardcoded module interfaces. All configuration inputs, permission declarations, and navigation pages are schema-driven through Medusa's internal API.
Relational Persistence: Database tables are modeled with Sequelize and persist to PostgreSQL.
Multi-Language by Design: All runtime messages, embeds, and config labels are defined in JSON dictionaries across 16 supported languages.

Module Directory Structure

Every module in Medusa lives in modules/<name>/ and follows this layout:

modules/my-module/
  main.js                          # Main module entrypoint extending Modules
  resources/                       # Static schemas, locales, and documentation
    config/                        # Dynamic dashboard configuration schemas
    docs/                          # MDX documentation pages for the module
    lang/                          # Multilingual dictionaries (16 locales)
    logs/                          # Audit and channel logging schemas
    leaderboards/                  # Optional leaderboard provider schemas
    nodes/                         # Automation flow trigger and action nodes
  src/                             # Runtime code
    clocks/                        # Cron and scheduled tasks extending Clocks
    commands/                      # Slash and prefix commands extending Commands
    events/                        # Discord gateway events extending Events
    handlers/                      # Business logic extending Handlers
    models/                        # Sequelize database models extending Models
    routes/                        # Internal REST API routes extending Routes

Module Import Aliases

Medusa defines root imports in package.json:

#medusa: Accesses the Medusa root kernel, console layout, colors, and core classes.
#medusa/modules: Exports the base classes for all module components:
- Modules
- Commands
- Events
- Clocks
- Models
- Routes
- Handlers
- Pages
- Configs
- Langs
- Logs
- Leaderboards
- Nodes

The `medusa` Root Instance

Every component receives the shared medusa root instance in its constructor:

Path	Purpose
`this.medusa.config`	Read root configuration from `config.json`.
`this.medusa.console`	Structured colored console logging (`levels.startup`, `levels.info`, `levels.warning`, `levels.error`).
`this.medusa.database`	Direct access to the Sequelize instance and database connection.
`this.medusa.discord`	Discord.js client manager, bot info, guild resolver, and presence updater.
`this.medusa.embeds`	Standardized embed resolver and message dispatcher.
`this.medusa.locales`	Multi-language translation resolver across all 16 locales.
`this.medusa.settings`	Dynamic database-backed settings store.
`this.medusa.audit`	Records actions to the persistent audit log.
`this.medusa.modules`	The module registry and loader catalog.