Architecture

Architecture

High-Level Flow

1. Discord interaction arrives.
2. Client routes to slash command or context command.
3. Command validates input and permissions.
4. Data is persisted into environment-scoped JSON files.
5. Runtime maps are updated in memory.
6. Reaction events update vote state continuously.

Main Runtime Components

• src/core/client.js

  • Initializes Discord client intents, partials, and in-memory maps.

• src/core/index.js

  • Loads environment file (.env or .env.staging).
  • Loads commands recursively from src/commands.
  • Initializes data files and runtime state.
  • Handles interactionCreate, messageReactionAdd, messageReactionRemove.
  • Hosts Express endpoints for dashboard integration.

• src/commands/

  • polls: poll creation and draft management.
  • users: monthly member and creator helpers.
  • admin: context operations for closing polls and toggling draft options.

• src/utils/

  • config.js: environment and path configuration.
  • file-handler.js: JSON persistence and initialization.
  • validators.js: poll and options validation.
  • permissions.js: creator/admin authorization checks.
  • mensalista-binding.js: optional role binding for monthly member detection.

Data Lifecycle

Startup:

• ensureDataFiles creates missing JSON files per environment.
• active polls and drafts are loaded into maps.
• old drafts (older than 90 days) are removed during load.
• active poll reactions are synchronized with current Discord state.
• vote limits are enforced after synchronization.

Runtime:

• Poll data changes are written back through saveActivePolls/saveDraftPolls.
• Reaction add/remove updates poll.votos for each user.
• Weighted voting is applied only when poll.usarPesoMensalista is true.

HTTP Surface

Express server in src/core/index.js exposes:

• GET /
• POST /api/commands/:commandName
• POST /api/csv/upload

See Dashboard API for request contracts.