Coding Standards

Official architectural rules and coding standards for the Kythia project.

This document outlines the mandatory coding standards for the Kythia project. Following these rules ensures scalability and maintainability as the project grows.

I. Directory & File Structure

The core of our architecture is the strict separation of responsibilities.

src
utils/ The "Plumber" (Pure JS, No Discord.js)
addons
core
helpers/ The "Building Manager" (Shared Logic)
economy
helpers/ The "Specialist" (Addon-specific)
commands/
- addon.json

1. `src/utils`

Purpose: Reusable, low-level functions (logger, time, formatter).

Strict Rules

MUST NOT import discord.js.
MUST NOT import database models.
MUST NOT reference the global config.

2. `addons/core/helpers`

Purpose: Bot-level helper functions shared across multiple addons.

CAN import discord.js and Core Models.
MUST be used if a function is needed by more than one addon.
MUST use a barrel file (index.ts) for exports.

3. `addons/<name>/helpers`

Purpose: Logic specific to a single addon.

MUST NOT be imported by other addons.
If logic needs to be shared, promote it to addons/core/helpers.

II. Naming Conventions

Consistency is key.

Type	Convention	Example
Files & Folders	`camelCase`	`guildMemberAdd.js`, `kythiaManager.js`
Variables	`camelCase`	`let newCooldown = ...`
Classes	`PascalCase`	`class KythiaManager {}`
Constants	`UPPER_SNAKE`	`const SPAM_THRESHOLD = 5;`

Special Prefixes:

_command.js: Defines the base slash command for a group.
_group.js: Defines a slash command sub-group.

III. Module Rules

Barrel Files & Aliases

We use path aliases to avoid relative path hell (../../).

Correct: import { logger } from '@utils';
Incorrect: import { logger } from '../../src/utils/index';

Circular Dependencies: Files within the same helper directory (e.g., two files in @utils) MUST NOT import each other.

IV. Internationalization (i18n)

All text must be translatable using our t() function.

Key Structure

Keys must follow a semi-nested structure mirroring the file path:

Common: common.error.generic
Addon: economy.commands.rob.success
Core: core.commands.moderation.ban.success

Dynamic Keys

Dynamic keys like t(`key.${variable}`) are strongly discouraged. If unavoidable, all possible variations MUST be manually added to en.json to pass the linter.

V. Documentation (JSDoc)

Every file and public function must be documented.

/**
 * Adds experience points to a user.
 * @param {string} userId - The ID of the user.
 * @param {number} amount - The amount of XP to add.
 * @returns {Promise<void>}
 */
export async function addXp(userId, amount) { ... }