@helyx/module-starboard

Starboard highlights messages that receive a configured community reaction, creates one managed Discord card, and keeps that card aligned through bounded reaction and source-message lifecycle work.

Availability and deployment

Starboard is Live and supports Hosted Helyx and Helyx Self-Hosted. It uses only Helyx runtime services and Discord capabilities available in both deployment modes. Every server starts with the module disabled; an enabled server without saved settings remains safely idle.

What it does

Managers choose one destination, reaction emoji, threshold, public source-channel rule, presentation mode, tracking window, and card lifecycle policy. Starboard deduplicates simultaneous promotions, coalesces rapid count changes, archives tracked entries at the configured deadline, and compensates when Discord publishing succeeds but durable state cannot be completed.

It does not store source-message content, attachment bodies, or reactor lists. It does not support private or role-gated sources, forum posts, multiple boards, weighted reactions, force-add, or message imports.

Commands and interactions

Starboard has no slash command. Discord reaction-add/remove/clear and source-message update/delete events drive automatic work. Managers inspect and operate retained entries through the dashboard actions below.

| Dashboard action | Default access | Purpose | | ---------------- | -------------------------------- | ---------------------------------------------------------- | | Remove entry | Members with Manage Messages | Delete the managed card and suppress automatic recreation. | | Restore entry | Members with Manage Messages | Restore an eligible suppressed or below-threshold entry. | | Refresh entry | Members with Manage Messages | Re-read the source and reconcile the saved count and card. |

Entry list and detail access uses the starboard.status manager policy. Action identities remain starboard.remove, starboard.restore, and starboard.refresh.

Dashboard configuration

Settings define the destination, emoji, threshold, Preview or link-only mode, channel inclusion rule, self-star and bot-message policy, below-threshold and source-deletion behavior, edit synchronization, attachment limits, tracking window, capacity archival, and bounded retention windows.

The Entries resource provides bounded search, status filtering, graphical detail, an on-demand source-message relation, and revision-aware actions. Existing entries retain their snapshotted rules when settings change.

Discord requirements

Starboard needs View Channel, Read Message History, Send Messages, Embed Links, and Manage Messages in the applicable channels. Reaction and guild-message events are required. Preview mode additionally requires the privileged Message Content intent; link-only mode does not.

The destination and every source must remain safely accessible. Private or role-restricted sources are rejected, and age-restricted content is never copied into a non-age-restricted destination.

Data, privacy and retention

The entries collection retains bounded server, source-channel, source-message, destination, managed-card, author and manager identifiers; snapshotted rules; derived counts; lifecycle state; and timestamps. It never stores message bodies, attachments, usernames, avatars, or reactor identities.

The versioned privacy provider covers source_author_user_id and removed_by_user_id, including while Starboard is disabled. Suppressed, terminal, and archived mappings use the configured retention windows; fixed deletion is scheduled through the platform boundary.

Operations and failure behavior

PostgreSQL-backed records are authoritative. Exact source/card lookups use bounded positive and negative caches with concurrent-load coalescing; caches are discarded on stop and correctness survives a cold restart. Promotion uses a unique source-message claim and an idempotent Discord send. A failed post-send state transition deletes the untracked card or records cleanup_pending for durable retry.

Count refreshes are coalesced, while expiry and cleanup use bounded at-least-once scheduled tasks. Task handlers re-read current state and use status/count fences so duplicate or stale delivery converges without recreating side effects. Required service loss or a recent primary failure reports unhealthy; recoverable cleanup, scheduling, or reaction-removal trouble reports degraded with fixed safe text. Optional customer Logging failure never reverses committed Starboard work.

Documentation and support

See the Starboard guide, settings, entries, permissions, logging, and FAQ.