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.

Public Buyer Experience

It's worth understanding what your buyers see, because it shapes how you set up waffles. The public page lives at /waffle/:slug and shows: title, description, payment info, Instagram media link buttons, an image thumbnail (if image_url is set), a fill progress bar, and the spot grid.

Manual Claim Flow

1. Buyer taps one or more available spots in the grid — they highlight as selected.
2. They enter their Instagram handle in the input below the grid (with or without the @).
3. They tap Claim Spots. The selected spots transition to Pending for everyone watching the page (WebSocket broadcast).
4. Buyer sends payment to you via DM / Venmo / CashApp out-of-band.
5. You mark the spots paid from the manage view.

Random Spot Selection

How it works for buyers:

1. Buyer enters their Instagram handle.
2. Instead of tapping the grid, they enter a count (e.g. 5) into the random-spots input and tap Pick Random Spots.
3. The server picks that many available spots at random under a transactional row lock and claims them in one shot.
4. The claimed spot numbers are returned to the buyer and broadcast via WebSocket to everyone watching.

Partial Fulfillment

If the buyer asks for more spots than are currently available, the server claims as many as it can and returns both requested_count and claimed_count in the response. There is no client-side maximum cap — the server is authoritative.

Mutual exclusivity with manual selection (v0.1.22-beta.0)

To prevent confusion, the random-claim controls are disabled while any manual spot is selected, and vice versa. A buyer either taps specific spots or asks for N random ones — not both in the same submission.

Same handle, same rate limits

Random claims hit the POST /api/claims/random endpoint, which reuses the same Instagram handle normalization, rate limiting, and WebSocket broadcasting as manual claims. The user registry is updated the same way.

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. You pick the winning spot(s) from a dropdown listing every paid spot with its Instagram handle (e.g. Spot #7 — @dani_boo_glass), then click Set Winner.

Single-winner waffles (item_count = 1)

The default case. Pick one spot from the dropdown. What happens when you click Set Winner:

• 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.
• The waffle's winning_spot_numbers and winning_instagram_handles arrays are populated.
• A waffle_completed WebSocket broadcast fires to all connected clients.
• A winner banner appears at the top of the manage page.

Multi-item waffles (item_count > 1)

For waffles where you set item_count above 1 at creation, the Set Winner UI shows one dropdown per item. You pick a distinct paid spot for each item, then click Set Winner once to commit all of them.

• Each chosen spot is marked Winner.
• All remaining paid spots are marked Loser.
• Each winner's total_wins increments by 1 (so picking the same buyer twice is intentionally not allowed — dropdown values must be distinct).
• The public waffle page renders a winner list, one row per item.

Recorded in the audit log as set_winner.

Changing or Clearing Winners

After winners are set, the manage page swaps the Set Winner UI for Change Winner and Clear Winner controls.

Clear Winner

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

Change Winner

Reassigns one or more winners. The dropdowns are pre-populated with the current winning spots; change any of them to a different paid spot and click Change Winner. Old winning spots that are no longer in the selection revert to Paid; new selections become Winner; loser status is recomputed across all paid spots. 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 Management → 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.

Payment Methods v0.1.22

Added in v0.1.22, the payment methods feature replaces the free-text payment_info field on waffles with a structured pool of stored payment options. You maintain one shared list at /admin/payment-methods; each waffle picks which methods to display via multi-select checkboxes on the create/edit form. Public waffle pages render the selected methods grouped by type, with icons (Venmo, PayPal, CashApp, Zelle) and clickable links.

Available to admin and super_admin. Navigate to Management → Payment Methods.

Managing the Pool (CRUD & Soft Delete)

The Payment Methods page lists every stored payment option. Each row has these fields:

Create / Update

Click Add Payment Method to create one, or click any row's edit control to update an existing entry. Type, display name, and handle/URL are all required.

Soft delete (deactivate)

Click Deactivate on a row to mark it inactive. The record is preserved so past waffles that referenced it still render correctly. If the method is currently selected on one or more active waffles, you get a usage warning before the deactivation goes through — that's the system telling you the deactivation will hide an option that's currently in use.

To reactivate a method later, the equivalent API call sets is_active = true; there is currently no dedicated reactivate button in the UI.

Selecting Methods on a Waffle

On the create-waffle and edit-waffle forms, the old payment_info textarea is gone. In its place is a multi-select checkbox list of every active payment method, grouped by type. Check the ones you want this waffle to advertise; uncheck the ones you don't.

The selected methods are stored as an association — not a copy — so editing a payment method's display name or handle later will update every waffle that uses it. (This is usually what you want; if you need a one-off variant, create a new payment method with a distinct display name.)

What buyers see

On the public waffle page, the payment section now renders one row per active method on this waffle, with:

• An icon for the payment type (Venmo, PayPal, CashApp, or Zelle)
• The display name
• The handle or a clickable link that opens the payment app (or web fallback)

Multiple methods of the same type (e.g. two Venmo accounts) are grouped together.

Share to Instagram v0.1.23-beta

Waffle can generate a branded PNG card and a customizable caption for each drop, so you can share a waffle directly to your Instagram Story or feed without leaving the app. The feature has two parts: Share Templates (reusable captions, managed in Settings) and the Share to Instagram section on each waffle's manage page.

Share Templates

Navigate to Management → Settings → Share Templates. Available to all roles. Templates are reusable caption bodies that support placeholder variables substituted at render time:

You can create multiple templates (e.g. a short teaser, a launch caption, a last-call reminder) and set one as the default. The default is pre-selected whenever you open the share editor on a waffle.

Waffle Card PNG

Every active waffle has a downloadable PNG card at /waffle/:slug/card.png. Two formats are available via the ?format= query parameter:

• Story (default) — 1080×1920 vertical, sized for Instagram Stories
• Square — 1080×1080, sized for feed posts

The card shows the waffle title, spot price, spots remaining, and the public claim URL. It's generated with Inter font and Project Syrup branding, then cached on disk. The cache is automatically invalidated when you update the share message or click Regenerate Card.

Share to Instagram (on the Manage Page)

At the bottom of each waffle's manage page (Management → Waffles → [waffle] → Manage) there is a Share to Instagram card. From here you can:

1. Pick a template from your saved templates (default is pre-selected).
2. Edit the rendered caption — placeholders are substituted live. Click Save Message to persist the custom caption to this waffle.
3. Copy the public claim URL with one tap.
4. Toggle Story / Square format and click Download Card to save the PNG.
5. Click Regenerate Card to force a fresh render if you've made changes after the card was first generated.
6. Click Copy Message to copy the final caption to your clipboard.

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 Management → 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 for your own logins. The full admin login history (admin+ roles) lives at /admin/login-history — it's still accessible but no longer in the Management dropdown menu as of v0.1.22.

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 Management → 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.