Admin Manual

Roles & Permissions

Every admin account carries exactly one role. Role determines what menu items appear, what API calls succeed, and which confirmation requirements apply.

Detailed permission matrix

Logging In

Navigate to /admin/login and enter your username and password.

If you are already logged in and visit the login page, you are redirected to the dashboard automatically — you will not see the login form.

Login Lockout

The throttle tracks failed attempts by the combination of IP address + username. After 5 consecutive failed attempts, that IP/username pair is locked out for 15 minutes. The lockout counter is held in memory (not persisted to the database) and is automatically cleaned up after it expires.

A successful login resets the counter for that IP/username pair. If you are locked out, wait 15 minutes for the lockout to expire automatically — there is no manual unlock UI. The lockout is per-IP, so a super_admin cannot unlock your account early; you must wait out the timer or try from a different IP.

Forgot Your Password?

Click Forgot password? on the login page. Enter your username. A single-use reset token is generated.

Reset tokens expire after 1 hour and are single-use. Once used, they cannot be replayed even if the expiry hasn't passed. To complete the reset, navigate to /admin/reset-password and submit the token and new password.

Navigation

The admin top bar contains the following links, visible based on your role:

How your name appears in the nav

The top-right button shows your name using this priority:

1. Display Name — if set and non-empty, it is used as-is
2. First Name + Last Name — if both are set
3. First Name alone — if only first name is set
4. Username — fallback when no profile fields are filled in

Set these fields under Settings → Profile.

Dashboard

The dashboard is your home screen after login. It shows all waffles and a summary card for each one.

Two tabs control which waffles are shown:

• Active (default) — non-archived waffles, newest first
• Archived — waffles you've archived after completion

Each waffle card shows: title, price per spot, total spots, status badge (Active / Completed), counts for available / pending / paid spots, a fill progress bar, and an image thumbnail if an image_url is set on the waffle. The nav bar footer also shows total waffle count and active waffle count.

From a waffle card you can click:

• Manage — opens the spot management view
• Edit — opens the edit form
• Archive / Unarchive — toggles archived state (admin or higher)

Creating a Waffle

Click New Waffle from the dashboard. Fill in the form fields described below.

Fields & Validation

Quick-fill Templates

The New Waffle form includes four pre-fill buttons to jumpstart common configurations:

Clicking a template fills the Total Spots and Spot Price fields — you still need to enter a title and any media links.

Editing a Waffle

From the dashboard card or the manage view, click Edit. You can change:

• Title
• Description
• Spot price
• Payment info
• Instagram media links (add, remove, or reorder)

All edits require a valid CSRF token (automatically included in the form). The edit is recorded in the audit log as update_waffle.

Archive & Delete

Archiving

Archive a waffle to move it off the active dashboard without destroying any data. Archived waffles appear under the Archived tab. Buyer stats, activity history, and all spot records are preserved. Only admin and super_admin can archive.

Click Unarchive from the Archived tab to restore it to active if you archived by mistake.

Both actions are recorded in the audit log as archive_waffle / unarchive_waffle.

Permanent Deletion

Permanent deletion requires two confirmations to prevent accidents:

1. Type the word DELETE exactly (case-sensitive) into the confirmation field.
2. Enter your current admin password.

Both checks run server-side. If either fails, the delete is aborted and you are redirected back. When it succeeds, the waffle, all its spots, and its activity history are removed permanently. The audit entry for the delete is still written because it is recorded before the deletion occurs.

CSV Export

Export a waffle's full spot list as a CSV file for external reconciliation or record keeping. The export button appears in the waffle info header on the manage page.

The export is also available without authentication at GET /api/waffles/:slug/export, so you can link buyers directly to a post-draw results file if you choose.

Columns in the export: spot number, status, claimed_by_handle, claimed timestamp, paid timestamp.

Manage View

Click Manage on any waffle card. This is your primary working screen during a live drop. It has five sections: a waffle info header, a stats bar, the spot grid, a pending claims list, and the winner section.

Stats Bar

A row of tiles at the top of the manage view shows real-time counts:

Spot Grid

A grid of numbered buttons — one per spot. Each button is color-coded by status:

Loser is a derived status set automatically on all paid spots (other than the winner) when a winner is entered. It feeds into buyer win/loss statistics. Buyers do not see the loser label on the public page — they just see the spot as completed.

A WebSocket connection icon in the top-right of the grid shows live connection status. Updates from other admin sessions or buyer claims appear instantly without a page refresh.

Bulk Pay Mode

For fast payment reconciliation, click Bulk Pay Mode in the top-right of the spot grid. The grid enters selection mode: tap any pending spots to select them (they highlight). A footer bar shows how many are selected and a Mark Paid button that sends all selected spots to the pay API simultaneously.

Bulk pay mode is only shown when the waffle is still active (not completed).

Pending Claims List

Below the spot grid, the Pending Claims panel shows every pending spot as a card with:

• Spot number
• Instagram handle of the claimer (@handle)
• Timestamp of when the spot was claimed
• Mark Paid button
• Release button

This is the most efficient way to work through pending claims one at a time as DM payments come in. When there are no pending claims, it shows "No pending claims."

Spot Actions

Mark Paid

Transitions a Pending spot to Paid. Available from both the pending claims list and the spot grid click-handler. A WebSocket broadcast updates all connected clients immediately. Recorded in the audit log as mark_paid.

Release

Transitions a Pending or Paid spot back to Available. Use this when a buyer claims a spot but doesn't pay, or if you accidentally marked the wrong spot paid. Broadcasts a spot update to all clients. Recorded as release_spot.

Winner Flow

The Set Winner section appears at the bottom of the manage page for active waffles. Type the winning spot number and click Set Winner.

What happens when a winner is set:

• The winning spot's status is changed to Winner.
• All other spots with status Paid are updated to Loser.
• The winner's buyer stats (total_wins) increment by 1.
• All losing buyers' stats (total_losses) increment by 1.
• The waffle status changes from Active to Completed.
• A waffle_completed WebSocket broadcast fires to all connected clients.
• A winner banner appears at the top of the manage page.

Recorded in the audit log as set_winner.

Changing or Clearing the Winner

After a winner is set, the manage page shows two additional controls:

Clear Winner

Removes the current winner. The winning spot reverts to Active. All loser spots revert to Paid. Buyer win/loss stats are fully recalculated for all affected spots on the waffle. The waffle status reverts to Active. Fires a winner_cleared WebSocket broadcast. Recorded as clear_winner.

Change Winner

Reassigns the win to a different spot number without clearing first. The old winning spot reverts to Paid, the new spot becomes Winner, and all loser spots are re-evaluated. Buyer stats are recalculated for all affected spots. Fires a winner_changed WebSocket broadcast. Recorded as change_winner.

Admin User Management

Available to super_admin only. Navigate to Admin Tools → Admin Users. The page shows a table of all admin accounts — active and inactive — with username, email, role, status, and last login. An inline role-permissions guide is shown at the top of the page (collapsed on mobile, always visible on desktop) to help you choose the right role when creating a new admin.

Creating an Admin

Click New Admin and fill in the form:

All form errors are returned inline on the page (username required, email required, password required, password policy failures). The new admin is created active and with timezone set to UTC by default.

Recorded as create_admin.

Changing a Role

Click the role badge on an admin row in the table. Select the new role from the dropdown. Role changes for demotions (e.g. admin → waffle_manager) require your current password as confirmation before the API call proceeds.

Recorded as update_admin_role.

Resetting Another Admin's Password

Click Reset Password on an admin row. Enter a new temporary password (must pass the password policy). The admin's current session is not invalidated — they will need to log out and back in with the new password. Send the temporary password to them securely and ask them to change it immediately.

Recorded as reset_admin_password.

Deactivating an Admin

Click Deactivate on an admin row and confirm your password. The account is set to active = false. Deactivated admins cannot log in — authentication returns an "account deactivated" error even with a correct password. Their audit history, login history, and any waffles they created are fully preserved.

To reactivate a deactivated admin, use the API directly (PATCH /api/admin/admins/:id with {"active": true}) — there is no UI reactivation button at this time.

Recorded as deactivate_admin.

Reports

Navigate to Reports in the top nav. Available to all roles. Reports are rendered client-side from JSON endpoints — the page loads first, then data is fetched via JavaScript.

Each report has a date range selector. The default range varies by report.

Drought List

Shows buyers who have been entering waffles but haven't won in a long time. Sorted by longest_drought — the number of days since their last win (buyers who have never won are listed as 99,999 days).

Columns: Instagram handle, total waffle entries in the date range, last entry date, days since last win.

Use this to identify loyal buyers who are overdue for attention — or to reward buyers who've been entering for a long time without a win.

Power Buyers

Ranks buyers by the number of paid spots across all waffles in the date range. Shows your most financially committed participants.

Columns: Instagram handle, total spots claimed (paid), total amount spent, win rate percentage.

Win rate is calculated as: wins ÷ (wins + losses) × 100, rounded to one decimal place. A buyer with no completed waffles (only pending spots) shows 0%. Default limit: top 20 buyers.

Monthly Activity

Aggregates three streams of activity by calendar month:

• Waffles — number of waffles created that month
• Spots Claimed — number of spots claimed (any status) that month
• Revenue — sum of spot_price for all spots marked paid that month

This is the primary tool for tracking the health and growth of your waffle operation over time.

Spot Velocity

Measures how quickly your waffles fill up, grouped by waffle status (active vs completed):

• Waffle Count — number of waffles in the group
• Avg Time to First Claim — average hours from waffle creation until the first spot was claimed
• Avg Time to Completion — average hours from waffle creation until completed_at (only meaningful for completed waffles)

Useful for understanding buyer demand and deciding how large to make your waffles.

Audit Log

Available to admin and super_admin. Navigate to Admin Tools → Audit Log.

Every state change performed by any admin is written to the audit_log table. Writes are asynchronous (in a goroutine) so they do not slow down the operation that triggered them. Each entry records: timestamp, the acting admin's ID, the action code, the affected entity type and ID, a human-readable detail string, and the admin's IP address at time of action.

Audited Actions

• create_waffle Waffle created — includes the title
• update_waffle Waffle edited — includes the new title
• archive_waffle Waffle archived
• unarchive_waffle Waffle restored from archive
• delete_waffle Waffle permanently deleted
• mark_paid Spot marked paid — includes spot number
• release_spot Spot released back to available — includes spot number
• set_winner Winner set — includes winning spot number
• clear_winner Winner cleared
• change_winner Winner changed — includes new winning spot number
• create_admin New admin created — includes username and role
• update_admin_role Admin role changed — includes new role
• update_admin_profile Admin profile updated
• reset_admin_password Another admin's password was reset
• deactivate_admin Admin deactivated — includes username
• update_whois_settings WHOIS server setting updated — includes new value
• update_setting Any system setting updated — includes key and new value

Filters & Export

The audit log page has filter controls:

• Admin — filter by acting admin (super_admin can see all; admin sees self and waffle_managers)
• Action — filter by action code (e.g. mark_paid)
• Target type — filter by entity type (waffle, spot, admin, settings)
• Date range — from/to timestamps

Results are paginated (default 20 per page). Click Export CSV to download the current filter results as a CSV file. The export URL includes URL-encoded filter parameters so it is reproducible and shareable.

Audit log entries older than the configured retention period (default 90 days) are automatically purged. Change this under Server Settings.

Login History

Navigate to your username dropdown → My Login History, or Admin Tools → Login History for the full admin view.

Each login entry captures:

WHOIS lookups are asynchronous with a 10-second timeout — they do not slow down the login flow. Private/RFC1918 addresses (10.x, 172.16–31.x, 192.168.x) are skipped and WHOIS fields are left empty.

Visibility by role

• waffle_manager — own entries only
• admin — own entries + all waffle_manager entries
• super_admin — all entries; can also filter by admin

Login history entries older than the configured retention period (default 90 days) are purged automatically. Change this under Server Settings.

Users Registry

Navigate to Users in the top nav. Available to all roles.

The users registry is a deduplicated list of every Instagram handle that has ever claimed a spot. On startup, the app backfills all existing claimed_by_handle values from the spots table into the users table automatically. Every new spot claim upserts the handle if it isn't already present.

Columns

Search and pagination

• A search box at the top filters by Instagram handle (substring match). A Clear button appears when a search is active.
• Results are paginated — 25 per page by default, up to 100 per page via the per_page query param.
• The pagination footer shows current page, total pages, and total user count.

Settings — Timezone

Click your username → Settings. The timezone dropdown accepts any valid IANA timezone string (e.g. America/New_York, Europe/London, Asia/Tokyo). Invalid values are rejected by the server.

All timestamps shown in the admin UI — waffle creation dates, spot claimed/paid times, login history — are displayed in your selected timezone.

Settings — Change Password

From Settings, scroll to the Change Password section. You must provide your current password before a new password is accepted.

Password policy

The minimum password length is configurable (default 8, stored in password_min_length system setting). Passwords are also checked against a blocklist of common passwords. Blocked values include:

password  password1  password123  12345678  123456789
qwerty  qwerty123  admin  admin123  letmein  welcome
welcome123  iloveyou  monkey  dragon  football  baseball
abc123  111111  00000000

Passwords are hashed with bcrypt before storage. The plaintext is never logged or stored.

Settings — Profile & Social Links

From Settings, the profile section allows you to set:

Social links

You can store up to 10 social links. Each link has a platform and a handle. Valid platforms:

Handles are limited to 100 characters each. Duplicate platforms in the same admin's profile are not allowed. These are stored for your profile only — they are not displayed publicly.

System Settings

super_admin only. Navigate to Admin Tools → Server Settings. Each setting is stored as a key/value pair in the system_settings table, so changes persist across restarts.

Changes to any system setting are recorded in the audit log as update_setting (or update_whois_settings for WHOIS specifically), with the old key and new value captured in the details field.