This guide explains how to use the admin features in Mulm to manage the Breeder Awards Program (BAP), Horticultural Awards Program (HAP), and Coral Awards Program (CAP).

Admins have access to special features for:

• Reviewing and approving submissions from members
• Managing member accounts and permissions
• Processing witness confirmations
• Monitoring waiting periods for draft status submissions
• Granting specialty awards and level upgrades
• Inviting new members to join programs

Admin Access: Contact the system administrator to be granted admin privileges.

1. Dashboard and Navigation
2. Approval Queue
3. Approving Submissions
4. Witness Confirmation
5. Waiting Period Monitor
6. Requesting Changes
7. Editing Submissions
8. Admin Notes
9. Member Management
10. Inviting Members
11. Specialty Awards
12. Level Management
13. Species Database Management

Once logged in with admin privileges, you'll see additional navigation options:

• Approval Queue - Submissions awaiting review (by program)
• Witness Queue - Submissions awaiting witness confirmation
• Waiting Period - Submissions in draft status waiting period
• Members - Member roster and management

All admin queues are organized by program:

• Fish (Breeder Awards Program)
• Plant (Horticultural Awards Program)
• Coral (Coral Awards Program)

Click the program tab to view that program's queue.

Each queue shows the number of pending items:

• Approval Queue (12) - 12 submissions ready for review
• Witness Queue (3) - 3 submissions awaiting witness confirmation

Path: /admin/queue/{program}

The approval queue shows submissions that have been:

• ✅ Submitted by member (not in draft status)
• ✅ Witness confirmed (if witness was required)
• ❌ Not yet approved by admin

Sorted by: Submission date (oldest first)

Each submission shows:

Step 1: Review Submission Details

Click "View" to see full submission details:

• Species information (common name, scientific name, classification)
• Reproduction/propagation details (date, count, methods)
• Tank parameters (size, filtration, water chemistry)
• Lighting and supplementation (for plants/corals)
• Photos (if uploaded)

Step 2: Verify Information

Check that:

• ✅ Species name is spelled correctly
• ✅ Scientific name is accurate
• ✅ Classification is appropriate
• ✅ Tank parameters are reasonable
• ✅ Reproduction/propagation date is plausible
• ✅ Photos show valid breeding evidence (if provided)

Step 3: Assign Points

Point values are assigned based on species difficulty:

Bonus Points:

• Article Points: 1-5 points for detailed breeding report
• First-Time Species: Check if this is the first breeding of this species in the club
• Flowering Bonus (plants): Equal to base points (e.g., 10pt plant that flowers = 20pt total)

Step 4: Record Species in Catalog

Enter the canonical species name (standardized scientific name):

• Canonical Genus: Standardized genus (e.g., "Betta")
• Canonical Species: Standardized species name (e.g., "splendens")

This links the submission to the species catalog and enables species search.

Step 5: Submit Approval

Click "Approve Submission"

The system will automatically:

• ✅ Record approval timestamp and admin
• ✅ Calculate total points (base + bonuses)
• ✅ Send email notification to member
• ✅ Update member's point total
• ✅ Check for level upgrades
• ✅ Check for specialty awards
• ✅ Add to public activity feed

Basic Approval:

Points: [10] ▼
Canonical Genus: [Betta]
Canonical Species: [splendens]

Advanced Options:

☑ First-time species (bonus points)
☑ Flowered (plants only - doubles points)

Article Points: [0] (0-5)

Actions:

[Approve Submission]  [Request Changes]  [Cancel]

Path: /admin/witness-queue/{program}

Shows submissions where a member has designated a witness but the witness has not yet confirmed or declined.

Members must designate a witness for:

• High-point submissions (typically 15-20 point species)
• First-time species submissions
• Rare or unusual breeding achievements

Each submission in the witness queue shows:

• Member: Submitter's name
• Species: What they bred/propagated
• Witness: Who they designated as witness
• Date Requested: When witness request was sent

If the witness has verified the breeding:

1. Review submission details
2. Verify witness is legitimate club member
3. Click "Confirm Witness"

The submission will move to the Approval Queue for final admin review.

If the witness has not verified or needs more documentation:

1. Click "Request More Documentation"
2. A dialog will open with a template message
3. Edit the message to explain what's needed:
   • Photos of fry/plantlets/frags
   • Photos of parent specimens
   • Video evidence
4. Click "Send Request"

The system will:

• ✅ Email member with the request
• ✅ Set witness status to "declined"
• ✅ Remove submission from witness queue

Member can then resubmit with additional evidence.

Additional documentation is needed to verify this spawn.

• Please provide images or video links clearly showing the fry (and eggs if applicable).
• Photos of the parents will also be helpful.

Customize this template based on the species type (fish/plant/coral).

The waiting period monitor shows submissions that are in draft status after being returned to the member for changes.

Path: /admin/waiting-period/{program}

When a submission is returned with "Request Changes":

• Member has 7 days to make edits without losing their place in queue
• After 7 days, submission is marked as "expired" and must be resubmitted
• Member can make unlimited edits during the waiting period

Each submission shows:

• Days Remaining: How many days left in waiting period
• Status:
  • Active - 5 days left
  • Expired

During Waiting Period:

• No action needed - member is editing
• Monitor for resubmission

After Expiration:

• Contact member if they haven't resubmitted
• Member must submit as new submission (loses original submission date)

Request changes when:

• ❌ Species name is incorrect or misspelled
• ❌ Tank parameters seem implausible
• ❌ Missing critical information
• ❌ Photos needed but not provided
• ❌ Reproduction date is unclear

Don't approve if you have doubts - ask for clarification!

1. From the approval queue, click "Request Changes" on the submission
2. A dialog opens with a pre-filled summary of the submission
3. Add your feedback below the summary:

   Please make the following changes:
   
   1. The scientific name appears to be misspelled.
      Did you mean "Corydoras paleatus" instead of "Coradoras paleatus"?
   
   2. Could you provide more detail about spawning triggers?
      What water changes or feeding regimen prompted the spawn?
   

4. Click "Send Request"

The system will:

• ✅ Email member with your feedback
• ✅ Move submission back to draft status
• ✅ Start 7-day waiting period
• ✅ Remove from approval queue
• ✅ Add to waiting period monitor

The system includes a summary of the submission:

Changes are requested for your BAP submission. Please review the notes below,
make appropriate changes, and resubmit.

-----------------

Water Type: Freshwater
Species Class: Catfish
Common Name: Peppered Cory
Latin Name: Corydoras paleatus

Date: 2025-09-15
Spawn Locations: Broadleaf plants, Tank glass
Foods: Frozen bloodworms, Sinking pellets

Tank Size: 20 gallon long
Filter Type: Sponge filter
Water Change: 50% weekly
Temperature: 72°F
pH: 7.0
...

[Your feedback here]

Admins can edit any submission regardless of status:

• Draft submissions
• Submitted (pending approval)
• Approved submissions

Use with caution! Editing approved submissions will not recalculate points or trigger notifications.

1. From any queue, click "Edit" on a submission
2. Make changes to any field
3. Click "Update Submission"

Appropriate reasons:

• Fix minor typos in species names
• Correct obvious data entry errors
• Update species classification after research
• Add missing information member provided via email

Inappropriate reasons:

• ❌ Changing point values after approval (use admin override carefully)
• ❌ Altering member data without member knowledge
• ❌ Fabricating information

Best Practice: When making significant edits, add an admin note explaining what was changed and why.

Admin notes are private comments visible only to admins. Use them to:

• Record communication with member
• Document approval decisions
• Track submission history
• Note concerns or follow-up items

1. View a submission detail page
2. Scroll to "Admin Notes" section
3. Type your note in the text area
4. Click "Add Note"

Example Notes:

2025-10-07: Member confirmed via email that spawn was witnessed
by John Doe. Proceeding with approval.

2025-09-15: Requested photos of fry. Member will upload within
24 hours.

2025-08-20: Approved with 15 points (first breeding of this
species in club history).

All notes are shown below the submission with:

• Admin name who wrote the note
• Timestamp when note was added
• Note text

• Edit: Click pencil icon next to note
• Delete: Click trash icon (use cautiously - action cannot be undone)

Path: /admin/members

View all members with their:

• Name (editable)
• Email (editable)
• Admin Status (toggleable)
• Program Levels (Fish, Plant, Coral)
• Total Points (per program)
• Actions (Edit, Check Levels, Send Welcome)

1. Click "Edit" next to a member
2. Row becomes editable
3. Change name, email, or admin status
4. Click "Save" (checkmark icon)

Admin Status:

• ☑ Is Admin - Member has admin privileges
• ☐ Is Admin - Regular member (default)

Caution: Be careful when toggling admin status. Only trusted club officers should be admins.

If a member's level appears incorrect (e.g., after manual point adjustment):

1. Click "Check Levels" next to member
2. System recalculates levels for all programs
3. Updates levels if needed
4. Shows result message:

   Updated 1 level(s): Fish level upgraded to "Breeder" (was "Hobbyist")
   

For members imported from legacy system who don't have login credentials:

1. Click "Send Welcome" next to member
2. System generates password setup link
3. Sends email with:
   • Welcome message
   • Link to set password
   • Summary of their approved submissions
   • Current point totals and levels

Note: Only works for members who don't already have password or Google account.

1. Click "Invite Member" button (top of members page)
2. Fill in the form:

   Email: [email protected]
   Name: John Doe
   

3. Click "Send Invite"

The system will:

1. Create member account (if doesn't exist)
2. Generate password setup code (valid 7 days)
3. Send invitation email with:
   • Welcome to the program
   • Link to set password
   • Instructions for first submission

Welcome to the BASNY Breeder Awards Program!

You've been invited to participate in our breeding awards program.
Visit the link below to set your password and access your account:

https://bap.basny.org/auth/set-password?code=abc123...

This link expires in 7 days.

Once you're logged in, you can:
- Submit breeding achievements for points
- Track your progress toward levels
- View the species catalog and standings

See you on the leaderboard!

If the email already exists in the system:

• System won't create duplicate account
• Will generate new password reset link
• Sends invitation email with reset link

Specialty awards recognize expertise in specific species categories. Awards are granted automatically when a member meets requirements.

Species-Specific Awards (require breeding multiple species in category):

• Anabantoids Specialist - 5+ species from Anabantoids class
• Catfish Specialist - 5+ species from Catfish class
• Characins Specialist - 5+ species from Characins class
• Killifish Specialist - 5+ species from Killifish class
• Livebearers Specialist - 5+ species from Livebearers class
• New World Cichlids Specialist - 5+ species
• Old World Cichlids Specialist - 5+ species
• Cyprinids Specialist - 5+ species
• Brackish Water Specialist - 5+ species
• Marine Fish Specialist - 5+ species
• Marine Invertebrates & Corals Specialist - 5+ species

Meta Awards (require earning multiple specialist awards):

• Senior Specialist Award - Earn 3+ specialist awards
• Expert Specialist Award - Earn 5+ specialist awards

Specialty awards are checked automatically:

• ✅ After every submission approval
• ✅ When member reaches level milestone
• ✅ When admin clicks "Check Specialty Awards"

To manually check awards for a member:

1. Go to Members page
2. Find the member
3. Click "Check Specialty Awards"
4. System scans all approved submissions
5. Grants any qualifying awards
6. Shows result:

   Granted 2 new specialty awards:
   - Catfish Specialist
   - Characins Specialist
   

When awarded, members receive:

• ✅ Email congratulating them
• ✅ Award appears on profile
• ✅ Activity feed entry (public)

Each program has progressive levels based on point thresholds and requirements:

Levels are checked automatically:

• ✅ After every submission approval
• ✅ Awards appropriate level based on total points
• ✅ Sends email notification if level increased
• ✅ Updates member profile

To manually recalculate levels:

1. Go to Members page
2. Find the member
3. Click "Check Levels"
4. System recalculates all three programs
5. Shows result:

   Updated 1 level(s):
   - Fish: Hobbyist → Breeder
   

When to use:

• After manually editing points
• After fixing data issues
• If level appears incorrect

✅ DO:

• Review each submission carefully
• Check species names against reliable sources
• Ask for clarification when uncertain
• Use admin notes to document decisions
• Approve promptly (members are waiting!)

❌ DON'T:

• Approve without reviewing details
• Make assumptions about species identification
• Edit approved submissions without documentation
• Grant points inconsistently

✅ DO:

• Be encouraging in "Request Changes" messages
• Explain clearly what's needed
• Respond to member questions promptly
• Thank witnesses for confirming

❌ DON'T:

• Be overly critical or discouraging
• Use jargon without explanation
• Leave members waiting without updates

✅ DO:

• Use canonical species names consistently
• Document significant edits in admin notes
• Check for duplicate submissions
• Verify point calculations

❌ DON'T:

• Change historical data without reason
• Delete submissions (archive if needed)
• Modify points after approval (unless correcting error)

Symptoms: Approval button doesn't work or shows error

Solutions:

• Ensure canonical genus/species are filled in
• Check that points field is not empty
• Verify member account still exists
• Check browser console for errors

Symptoms: Member didn't receive approval/level email

Solutions:

• Check member's email address is correct
• Check server email logs (requires SSH access)
• Ask member to check spam folder
• Resend via "Send Welcome" if needed

Symptoms: Member has enough points but level didn't upgrade

Solutions:

1. Click "Check Levels" next to member
2. Verify points meet level requirements (including category requirements)
3. Check that submissions are approved (not just submitted)
4. Review program-specific level rules

Symptoms: Member's total points don't match sum of submissions

Solutions:

1. Check for unapproved submissions (don't count toward total)
2. Verify article_points are included
3. Check for first-time species bonus
4. For plants: verify flowering bonus (doubles points)

• Database Schema - Submissions and awards tables
• Production Deployment - Deployment and troubleshooting
• API Documentation - Species search API
• CLAUDE.md - Full project documentation

For technical issues or questions about admin features:

• Technical Issues: Contact system administrator
• Program Rules: Contact club president or program coordinator
• Member Concerns: Respond directly or forward to appropriate officer

Admin Access Required: This guide assumes you have been granted admin privileges by the system administrator. If you cannot access admin features, contact your club's system administrator.

The species database management interface (/admin/species) provides tools for maintaining 2,300+ species and 5,000+ name variants.

From any admin page, visit /admin/species to access the full species management interface.

1. Browse & Search - Filter by type, class, points, CARES status
2. Bulk Point Assignment - Select multiple species and assign points
3. Edit Species - Update canonical names, points, CARES status
4. Manage Name Variants - Add/delete common and scientific names
5. Merge Duplicates - Combine duplicate species into one
6. Empty States - Helpful guidance when no names exist

Assign Points to Species:

• Filter "Without Points" → Check species → "Bulk Edit Points" → Select value → Apply

Merge Duplicate Species:

• Open defunct species → Edit → Danger Zone → "Merge Into Another Species" → Select canonical → Confirm

Add Name Variant:

• Open species → Edit → Name Variants → "+ Add" → Enter name → Saved automatically

Mark CARES Species:

• Open species → Edit → Check "CARES Conservation Species" → Save

See Admin Species Management for complete guide covering:

• All features and workflows
• Data model and relationships
• Technical implementation
• Troubleshooting tips