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 IDnumber
: User-specific task numbertitle
: Task titledescription
: Task descriptioncategory
: User-defined categorystatus
: Task status (enum)priority
: Task priority (enum)dueAt
: Due datecreatedAt
: Creation timestampupdatedAt
: 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)
3. Legal Documentation
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 tokenMONGO_URL
: MongoDB connection string
Installation & Setup
- Clone the repository
- Install dependencies:
npm install
- Set up MongoDB database
- Configure environment variables
- Run database migrations:
npx prisma generate
- Build the project:
npm run build
- 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