Skip to content

Melody Iuvo

Melody Iuvo (hereinafter the β€œApplication”) is a powerful task management bot for Discord that enables users to create, organize, and track their tasks, deadlines, and goals directly within Discord. The bot provides a comprehensive set of slash commands for task management with support for categories, priorities, status tracking, and due dates.

1. User Documentation

This section is for those interacting with a live instance of the Application.

Getting Started

To use Melody Iuvo, you’ll need to add the bot to your Discord account and subscribe to access the premium features.

Available Commands

The bot provides the following slash commands for task management:

Core Commands

  • /create - Create a new task

    • title: The title for your task (required, max 256 characters)
    • description: The description for your task (required, max 2048 characters)
    • status: Task status - TODO, In Progress, In Review, or Complete (required)
    • priority: Task priority - None, Low, Medium, High, or Critical (required)
    • category: The category for your task (required, max 1024 characters)
    • due-date: Due date in YYYY/MM/DD format (optional)
  • /list - View your currently active tasks (excludes completed tasks)

    • Shows up to 10 tasks sorted by due date
    • Displays tasks in rich embed format with all details
  • /view - View details of a specific task

    • number: The task number you wish to view (required)

Task Modification Commands

  • /retitle - Update the title of an existing task

    • number: The task number to update (required)
    • title: New title for the task (required, max 256 characters)
  • /redescribe - Update the description of an existing task

    • number: The task number to update (required)
    • description: New description for the task (required, max 2048 characters)
  • /restate - Update the status of an existing task

    • number: The task number to update (required)
    • status: New status (TODO, In Progress, In Review, Complete) (required)
  • /reprioritise - Update the priority of an existing task

    • number: The task number to update (required)
    • priority: New priority (None, Low, Medium, High, Critical) (required)
  • /recategorise - Update the category of an existing task

    • number: The task number to update (required)
    • category: New category (required, max 1024 characters)
  • /retarget - Update the due date of an existing task

    • number: The task number to update (required)
    • due-date: New due date in YYYY/MM/DD format (optional)

Information Commands

  • /about - Learn more about the bot
    • Shows version information, commit details, and useful links
    • Provides buttons for support, source code, and subscription

Task Features

Status Types

  • TODO: Task is planned but not started
  • In Progress: Task is currently being worked on
  • In Review: Task is completed and awaiting review
  • Complete: Task is fully finished

Priority Levels

  • None: No specific priority
  • Low: Low priority task
  • Medium: Medium priority task
  • High: High priority task
  • Critical: Urgent, critical priority task

Task Numbering

Each user has their own task numbering system starting from 1. Task numbers are unique per user and automatically assigned when creating new tasks.

Task Embeds

Tasks are displayed in rich Discord embeds showing:

  • Title and description
  • Category, status, and priority
  • Due date, creation date, and last updated date
  • Color-coded by status (red for TODO, orange for in-progress, yellow for in-review, green for complete)

Subscription Model

Melody Iuvo operates on a premium subscription model. Users must subscribe to access the task management features. The subscription is managed through Discord’s built-in premium subscription system.

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

Architecture Overview

Melody Iuvo is built as a Node.js Discord bot using the following technology stack:

  • Runtime: Node.js with TypeScript
  • Discord Library: Discord.js v14.18.0
  • Database: MongoDB with Prisma ORM
  • Web Server: Fastify (for health monitoring)
  • Logging: Custom logger (@nhcarrigan/logger)

Project Structure

src/
β”œβ”€β”€ commands/ # Slash command definitions
β”œβ”€β”€ modules/ # Command implementation logic
β”œβ”€β”€ config/ # Configuration files (choices, names)
β”œβ”€β”€ interfaces/ # TypeScript type definitions
β”œβ”€β”€ db/ # Database connection
β”œβ”€β”€ server/ # Web server for health monitoring
└── utils/ # Utility functions

Key Components

Command System

The bot uses a modular command system where:

  • /src/commands/ contains Discord slash command definitions
  • /src/modules/ contains the actual command implementation logic
  • Commands are registered in the main index file

Database Schema

The application uses a single Tasks model with the following fields:

  • id: MongoDB ObjectId (primary key)
  • userId: Discord user ID
  • number: User-specific task number
  • title: Task title
  • description: Task description
  • category: User-defined category
  • status: Task status (enum)
  • priority: Task priority (enum)
  • dueAt: Due date
  • createdAt: Creation timestamp
  • updatedAt: Last update timestamp

Subscription System

The bot integrates with Discord’s premium subscription system (Discord Store) to manage user access. All commands (except /about) require an active subscription.

Web Interface

A simple web server runs on port 5443 providing:

  • Health monitoring endpoint
  • Basic information page with links
  • Discord bot invite link

API Integration

The bot integrates with:

  • Discord API (via Discord.js)
  • Discord Store API (for subscriptions)
  • MongoDB (via Prisma)

This section covers the legal policies and requirements specific to the Application.

4. Contributing Documentation

This section is for documentation related to contributing to the Application’s codebase.

Environment Variables

Required environment variables:

  • DISCORD_TOKEN: Discord bot token
  • MONGO_URL: MongoDB connection string

Installation & Setup

  1. Clone the repository
  2. Install dependencies: npm install
  3. Set up MongoDB database
  4. Configure environment variables
  5. Run database migrations: npx prisma generate
  6. Build the project: npm run build
  7. Start the bot: npm start

Development

  • Build: npm run build - Compiles TypeScript to JavaScript
  • Lint: npm run lint - Runs ESLint with zero warnings policy
  • Start: npm start - Runs the production build