Flush System Documentation

The Flush System keeps your Discord server clean and synchronized with Albion Online. It automatically removes roles and database records from members and allies who have left their respective guilds, ensuring only active players retain their Discord permissions.

Prerequisites: Before using flush features, your bot must be configured via /setup start and the member role must be set. For the Ally Flush, the Alliance System must also be configured.

🔍 System Overview

The Flush System has two independent components that operate separately:

Member Flush

Checks primary and secondary guilds only. Runs automatically at the top of every hour (e.g., 01:00, 02:00 UTC). Can also be triggered manually via /flush command or the Dashboard.

Ally Flush

Checks allied guilds only. Runs automatically at every half hour (e.g., 01:30, 02:30 UTC). Can also be triggered manually via the Dashboard.

Important separation: The Member Flush never touches allies, and the Ally Flush never touches main guild members. They are completely independent processes.

⚙️ How the Flush Works

Both flush types follow the same general logic:

Connect to the Albion Online API — The bot fetches the current member list from each configured guild.
Compare with the database — The bot cross-references the API data with its local database of registered members/allies.
Identify who left — Players no longer in any of their guilds are flagged for removal.
Check Discord presence — The bot checks whether flagged users are still in the Discord server.
Take action — Roles are removed and/or database records are deleted based on each user's situation.
Log the result — A detailed embed is sent to the configured log channel.

Safety-first approach: If the Albion Online API returns an error, the flush is skipped entirely for that cycle. The bot never removes roles based on incomplete data — it's better to do nothing than to accidentally remove a legitimate member.

👥 Member Flush

What It Checks

The Member Flush checks all users registered as members against your configured primary and secondary guilds. Allied guilds are completely ignored in this process.

Who Gets Processed

The flush identifies three categories of users to process:

Category	Situation	Action Taken
🦵 Left Guild, Still in Discord	Player left the Albion guild but is still in the Discord server	All roles are removed (except Booster role). Record deleted from database.
👻 Left Guild & Left Discord	Player left both the Albion guild and the Discord server	Record deleted from database only (no Discord action needed).
🎭 Unregistered with Member Role	User has the member role in Discord but is not registered with the bot	Member role is removed (except Booster role). Any orphaned database records are cleaned up.

Booster role protection: If a user is a server booster, their booster role is always preserved even during a flush. All other roles are removed.

Automatic Schedule

The automatic member flush runs at minute 0 of every hour in UTC:

01:00 UTC, 02:00 UTC, 03:00 UTC, and so on — every full hour.
The schedule can be customized via the MEMBER_FLUSH_CRON environment variable.

🤝 Ally Flush

What It Checks

The Ally Flush checks all users registered as allies against every configured allied guild. A player is only removed if they are absent from all allied guilds simultaneously. If they are in at least one allied guild, they are kept.

Who Gets Processed

The ally flush identifies four result categories:

Category	Situation	Action Taken
✅ Kept (Still Active)	Player is still in at least one allied guild	No action. Role and record are preserved.
🚪 Left All Allied Guilds	Player is no longer in any allied guild but still in Discord	Ally role is removed. Record deleted from database.
🚪 Left Discord	Player left the Discord server (regardless of guild status)	Record deleted from database only.
⚠️ Unauthorized (Role without record)	User has the ally role but is not registered as an ally in the database	Ally role is removed.

Optimized API Approach

The ally flush is designed to be efficient: it makes exactly one API request per allied guild, builds an in-memory map of all alliance members, and then checks every registered ally against that map. This avoids hundreds of individual API calls for large alliances.

Retry Logic

For each allied guild, the bot retries the API request up to 3 times with increasing delays (1s, 2s, 3s) before giving up. If any guild fetch fails after all retries, the entire ally flush is skipped to avoid false removals.

Automatic Schedule

The automatic ally flush runs at minute 30 of every hour in UTC:

01:30 UTC, 02:30 UTC, 03:30 UTC, and so on — every half hour.
Running 30 minutes offset from the member flush avoids Albion API congestion.

💬 Discord Command: /flush

Purpose

The /flush command allows managers to manually trigger a Member Flush at any time, without waiting for the automatic hourly cycle. This is useful after mass guild changes or when roles seem out of sync.

Members only: The /flush command handles main guild members only. To manually flush allies, use the Dashboard's Ally Flush button.

Usage

/flush

No parameters required. The command automatically reads your configured guilds.

Required Permissions

The user must have the Management Role configured in your server settings. Regular members cannot use this command.

Step-by-Step Flow

Step 1 — Confirmation Preview

After running /flush, the bot queries the Albion Online API and displays a preview embed listing all users that will be affected, organized by category:

Players who left the guild (roles will be removed)
Unregistered users with the member role (roles will be removed)
Players who left the guild and also left Discord (database cleanup only)

If everything is already in sync, the bot reports "No actions required" and shows no buttons.

Step 2 — Buttons

Two buttons appear on the confirmation embed:

Button	Style	Action
Confirm	Red (Danger)	Executes the flush immediately. Processes all listed members and shows a progress counter. After completion, sends a detailed result report.
Cancel	Gray (Secondary)	Cancels the operation without making any changes.

Timeout: The confirmation buttons expire after 10 minutes. If neither button is pressed within that time, the operation is automatically cancelled and no changes are made.

Step 3 — Progress Updates

While processing, the bot updates the message with a live counter every 10 members:

🔄 Processing members... 10/47 completed

Step 4 — Result Embeds

After completion, the bot sends up to 3 result embeds, one per category:

🦵 Players Who Quit Guild — Roles Removed: Shows successfully processed members vs failed cases, displayed in 3 columns for readability.
🎭 Unregistered Users — Member Role Removed: Shows users who had roles without registration.
👻 Players Who Left Everything — Removed from Database: Shows player names cleaned from the database.

A log embed is also sent to your configured log channel with full details including who executed the command.

🖥️ Dashboard: Flush Configuration

The Flush Configuration page in the dashboard allows managers to control the automatic flush behaviour and trigger manual flushes for both members and allies.

Navigate to: Dashboard → Flush System (or equivalent menu entry for your server).

Status Overview Card

The top card shows the current status of both flush systems at a glance:

Member Flush status — Enabled / Disabled indicator with schedule info (runs at minute 0)
Ally Flush status — Enabled / Disabled indicator with schedule info (runs at minute 30)
Last Auto Member Flush — Timestamp of the last successful automatic member flush
Last Auto Ally Flush — Timestamp of the last successful automatic ally flush
Last Manual Member Flush — Timestamp of the last manual member flush via dashboard
Last Manual Ally Flush — Timestamp of the last manual ally flush via dashboard
Failure Count — Number of consecutive flush failures (resets to 0 on success)
Last Error — If the last flush had an error, a brief description is shown here (orange alert)

Member Flush Settings Card

This card has two controls:

Auto Toggle (Enable/Disable)

A toggle switch that enables or disables the automatic hourly member flush. This does not affect the manual flush button.

When enabled (default): The flush runs automatically every hour at minute 0.
When disabled: The hourly schedule is skipped. You can still run flushes manually.

Execute Member Flush Now (Button)

Clicking this button triggers an immediate member flush, identical to what the automatic system does. A confirmation dialog appears before execution.

A modal window shows the flush execution progress in real time with a live log. After completion, a summary is shown and the modal's close button becomes available.

Ally Flush Settings Card

Same two controls as the member flush card, but for allies:

Auto Toggle (Enable/Disable)

Enables or disables the automatic hourly ally flush (runs at minute 30). Alliance configuration must be set up for this to have any effect.

Execute Ally Flush Now (Button)

Triggers an immediate ally flush with a real-time log modal. The close button is disabled while the flush is running and becomes available when it finishes.

📝 Log Channel Output

After every flush run (automatic or manual), a detailed embed is sent to your server's configured log channel. If no log channel is configured, logs are silently skipped.

Automatic Member Flush Log

Sent every hour after the member flush cycle completes. Contains:

Total successfully processed and total failed
Breakdown: Left Guild (roles removed) / Unregistered (roles removed) / Database Cleanup
List of main guilds checked
Individual lines for each processed member with the action taken
Individual lines for each failed case with the error reason
API warnings (if any guilds had partial errors)

Color coding: Green = all success, Orange = partial failures, Red = all failed.

If no changes are needed, a clean "✅ Automatic Hourly Member Flush — No Changes" embed is sent instead.

Automatic Ally Flush Log

Sent every half hour after the ally flush cycle completes. Contains:

Total kept (still in allied guilds), total removed
Breakdown: Left Allied Guilds / Left Discord / Unauthorized
Total alliance members found across all guilds
List of allied guilds checked
Up to 10 kept allies listed individually (if more, a count summary is shown)
Full list of removed allies with reasons

If API errors occur during guild fetching, a separate "⚠️ Ally Flush Skipped — API Errors" embed is sent listing which guilds failed.

Manual /flush Command Log

After a manual /flush command is confirmed and executed, a log embed is sent containing:

Which user executed the command (name + mention)
Total successfully processed and total failed per category
Complete list of all affected members (with Discord mentions when available)

🛡️ Safety Measures & API Errors

The flush system is built with a safety-first approach. It never removes roles when it cannot fully confirm someone has left.

When the flush is skipped

Critical API errors (504 Gateway Timeout, 503 Service Unavailable, 502 Bad Gateway, 500 Internal Server Error, ECONNRESET, ETIMEDOUT): The flush is completely skipped. A warning is sent to the log channel and returned to the user if using the Discord command.
All guilds fail to load: If 100% of configured guilds return errors, the flush is skipped.
Ally guild fetch failure: For the ally flush, if even one allied guild fails to load after 3 retries, the entire ally flush is skipped to prevent false removals.

When the flush continues with a warning

Some guilds fail, others succeed (member flush only): If at least one guild loaded successfully, the flush continues with the available data. A warning is shown indicating partial data. This means members from the failed guild(s) will not be processed in that cycle.

Discord Command Error Messages

Error	Cause	What to do
Server Not Configured	Bot setup has not been completed	Run `/setup start` to configure the bot
Permission Denied	User does not have the Management Role	Ask an admin to assign the management role
No Guilds Configured	No primary or secondary guild has been set up	Run `/setup start` and configure at least one guild
🚫 API Service Unavailable	Albion Online API is down or unreachable	Wait a few minutes and try again. Check Albion Online server status.
⚠️ Albion Online API Error	API returned timeout or server-side error (5xx)	Temporary issue. Wait and retry.
⚠️ All Guild Synchronizations Failed	All guilds failed to load from API	Check Albion API status, network connectivity, and guild configuration.

🔒 Required Permissions

Discord Command (/flush)

User must have the Management Role assigned in your server's bot configuration.
Regular members cannot use this command.

Dashboard (Flush Configuration Page)

User must be logged in via Discord OAuth.
User must have access to the selected guild's dashboard (admin or manager role).

Bot Permissions Required in Discord

For the flush to successfully remove roles, the bot needs:

Manage Roles permission in the server.
The bot's role must be higher in the role hierarchy than the Member and Ally roles it needs to remove. If the bot's role is below the target role, it will fail with a "Missing Permissions" error (code 50013).

Role hierarchy is critical: If members have roles positioned above the bot's own role in the Discord role list, the bot cannot remove them. Make sure the bot's role is near the top of the role list in Server Settings → Roles.

🔧 Troubleshooting

Flush ran but some members still have their roles

Check if the bot's role is high enough in the role hierarchy. The bot cannot remove roles positioned above its own.
Check the log channel for "Failed to Process" entries with specific errors.
Ensure the bot has the Manage Roles permission in Server Settings.

Automatic flush is not running

Verify the auto toggle is enabled on the Dashboard flush configuration page.
Check the "Last Auto Member Flush" / "Last Auto Ally Flush" timestamps on the dashboard. If they are recent, the system is working.
Check the log channel — if the flush ran but found no changes, it still sends a "No Changes" embed every hour.
Check the "Failure Count" field. If it's high, check the "Last Error" message for clues.

Ally flush is not removing anyone who left

Confirm that the Alliance System is configured. The ally flush requires alliance configuration to be set up (/alliance command).
Confirm the correct allied guilds are listed. If a guild was removed from the alliance but still registered in the bot, players from that guild won't be checked correctly.
Check if the API was returning errors during the last flush cycle (check log channel for API error embeds).

The /flush command shows "No actions required" but roles seem wrong

This can happen if the Albion Online API has not yet updated. The API can take up to a few hours to reflect guild membership changes.
If a player recently left and the API still shows them as a guild member, the bot correctly keeps their role. Wait for the next hourly cycle.

Log channel is not receiving flush logs

Verify a log channel is configured via /setup start or the Dashboard configuration.
Ensure the bot has Send Messages and Embed Links permissions in the log channel.
Check that the log channel still exists and has not been deleted.