Admin Module

The Admin Module (@zumito-team/admin-module) provides a web-based dashboard for managing your Zumito bot. It includes superadmin management, server browsing, and a dynamic sidebar navigation system that other modules can extend.

Installation

npm install @zumito-team/admin-module

Add to your zumito.config.ts:

bundles: ['@zumito-team/admin-module']

What it provides

Dashboard

A full web interface at /admin showing:

• Bot uptime, user count, channel count, server count
• Node.js and discord.js versions
• Server list with guild names and icons
• Superadmin user management (add/remove)

Authentication

Discord OAuth2-based login flow via the shared discord-auth module:

1. User clicks “Login” → redirected to Discord authorization.
2. Discord redirects back to /admin/login/callback.
3. A JWT (admin_token, purpose: 'admin') is issued with 2-hour expiry.
4. All admin routes validate this token via AdminAuthService (which extends DiscordAuthService).
5. Tokens issued for other modules (e.g., User Panel) are rejected thanks to the purpose claim.

Services

| Service | Purpose | |---|---|---| | NavigationService | Register sidebar items in the admin panel. | | AdminAuthService | Extends DiscordAuthService. Validates JWT tokens with purpose: 'admin' and checks superadmin status. | | AdminViewService | Render pages within the admin layout (EJS templates). | | AdminColorsService | Manage the dashboard color palette. |

Routes

Method	Path	Description
GET	/admin	Dashboard with bot stats.
GET	/admin/login	Redirect to Discord OAuth2.
GET	/admin/login/callback	OAuth2 callback handler.
GET	/admin/logout	Clear auth cookie and redirect to /admin.
GET	/admin/servers	List all guilds.
GET	/admin/superadmins	List superadmin users.
POST	/admin/superadmins/add	Add a superadmin by Discord user ID.
POST	/admin/superadmins/remove	Remove a superadmin.

Configuration

Environment variables

Variable	Required	Description
DISCORD_CLIENT_ID	Yes	Discord application client ID.
DISCORD_CLIENT_SECRET	Yes	Discord application client secret.
SECRET_KEY	Yes	Secret key for JWT signing.
HOST	Yes	Bot host URL (for OAuth2 redirects).
FRONTEND_URL	Yes	Frontend URL (for redirects after login).
ADMIN_COLORS_FILE	No	Path to a JSON file with color overrides.
ADMIN_COLORS	No	JSON string with color overrides.

Color palette

The dashboard colors can be customized via ADMIN_COLORS env var or a JSON file. Defaults match Discord’s brand palette:

{
  "primary": "#5865f2",
  "accent": "#5865f2",
  "success": "#57f287",
  "warning": "#fee75c",
  "danger": "#ed4245",
  "foreground": "#ffffff",
  "dark": {
    "100": "#36393f",
    "200": "#2f3136",
    "300": "#292b2f",
    "400": "#202225"
  }
}

Tip

You can set colors inline via ADMIN_COLORS='{"primary":"#ff0000"}' or point to a file with ADMIN_COLORS_FILE=/path/to/colors.json.

Extending the admin panel

Other modules can register navigation items in the admin sidebar by consuming NavigationService:

import { ServiceContainer } from 'zumito-framework';

const nav = ServiceContainer.getService('NavigationService');
nav.registerItem({
    id: 'my-page',
    label: 'My Page',
    icon: 'settings',
    link: '/admin/my-page',
    order: 50
});

The AdminViewService.render() method can be used to wrap custom content in the admin layout:

const view = ServiceContainer.getService('AdminViewService');
const html = await view.render({
    title: 'My Page',
    content: '<h1>Hello World</h1>',
    reqPath: '/admin/my-page',
    user: req.user
});

Module dependencies

Your module must declare the requirement in its class:

class MyModule extends Module {
    requirements = {
        services: ['NavigationService']
    };
}

Dependencies

• discord-auth — Shared Discord OAuth2 authentication service.
• ejs — Template rendering for admin pages.
• jose — JWT verification and signing.
• zumito-framework

Related modules

• Reactions Module — Uses NavigationService to register its admin pages.
• User Panel — Similar pattern for user-facing dashboards.