flint/README.md

Discord.js v14 Framework Template

Professional command framework template for Discord.js 14.26.2 with:

• Single command object schema
• Minimal command authoring (name, category, execute)
• Optional per-user command cooldown (cooldown in seconds)
• Shared execution logic for prefix and slash
• External JSON i18n
• Automatic prefix and slash localizations from locale files
• One localized name per language drives both prefix and slash triggers
• Typed argument schema
• User permission checks
• Auto-generated help from command metadata

Presence Storage

• The presence command is persisted in PostgreSQL.
• Storage is keyed by bot_id (Discord user id), so one PostgreSQL instance can serve multiple bots.
• Presence survives bot restarts and container restarts.

Setup

1. Install dependencies: npm install
2. Create environment file: cp .env.example .env
3. Fill required values in .env:
   • DISCORD_TOKEN
   • DISCORD_CLIENT_ID
   • DATABASE_URL
4. Optional values:
   • DATABASE_SSL (true for managed cloud DB, false for local Docker)
   • PRESENCE_STREAM_URL (used when activity type is STREAMING)
   • AUTO_DEPLOY_SLASH (true to sync slash commands on startup)
   • DEV_GUILD_ID (optional guild scope for faster slash sync)
5. Start in development: npm run dev
6. Validate code quality:
   • npm run typecheck
   • npm run test
   • npm run check

Docker Deployment (Bot + PostgreSQL)

1. Configure .env with at least:
   • DISCORD_TOKEN
   • DISCORD_CLIENT_ID
   • POSTGRES_DB
   • POSTGRES_USER
   • POSTGRES_PASSWORD
2. Start stack: docker compose up -d --build
3. Stop stack: docker compose down

By default, docker-compose.yml provisions:

• bot: the Discord bot container
• postgres: PostgreSQL 16 with persistent volume postgres_data

The bot container uses:

• DATABASE_URL=postgresql://<POSTGRES_USER>:<POSTGRES_PASSWORD>@postgres:5432/<POSTGRES_DB>

Security defaults:

• PostgreSQL is bound to 127.0.0.1 by default in Compose.
• Keep strong values for POSTGRES_PASSWORD and rotate credentials if exposed.

Multi-Bot With One DB

You can run several bot services against the same PostgreSQL instance.

• Keep one shared postgres service.
• Add additional bot services with different DISCORD_TOKEN / DISCORD_CLIENT_ID.
• Keep DATABASE_URL pointing to the same PostgreSQL service.

Because rows are keyed by bot_id, each bot keeps its own independent presence configuration.

An example with two bot services is available in docker-compose.multi-bot.example.yml.

Architecture

• src/app/bootstrap.ts: runtime bootstrap, dependency wiring, graceful shutdown
• src/commands/*: thin command wrappers (defineCommand + delegated execute)
• src/features/presence/*: presence runtime, panel orchestration, repository contract
• src/features/memberMessages/*: member-message dispatch, panel orchestration, image rendering, repository contract
• src/core/commands/*: registry, parsing, slash payload, usage helpers
• src/core/execution/CommandExecutor.ts: unified execution pipeline (permissions/cooldown/error handling)
• src/core/discord/*: shared Discord helpers (reply message resolver, panel session registry)
• src/database/stores/*: PostgreSQL store implementations
• src/database/dbLifecycle.ts: centralized DB init/shutdown lifecycle
• src/validators/*: business validation/sanitization
• src/types/*: pure shared types and contracts
• src/i18n/*.json: external i18n dictionaries

Included Commands

• kiss (fun) with required user arg
• ping (utility)
• welcome (utility) interactive welcome-message panel
• goodbye (utility) interactive goodbye-message panel
• presence (utility) with interactive status/activity/text panel
• help (core) with auto category and usage generation

Adding A Command

1. Create a command object in src/commands/...
2. Follow the schema in src/types/command.ts
3. Add command to src/commands/index.ts
4. If AUTO_DEPLOY_SLASH=true, restart the bot to sync slash commands automatically