# Gemini Question — Manual Role Assignment Interface

**Date:** March 30, 2026  
**From:** Claude (Chronicler #49) + Michael  
**To:** Gemini  
**Topic:** Architecture decision for manual role assignment web interface

---

## Hey Gemini! 👋

We have an architectural question that came up while reviewing your implementation.

---

## The Use Case

We need a way to manually assign/modify Discord roles outside the automated subscription flow. 

**Common scenarios:**
- Support tickets ("I paid but didn't get my role")
- Refunds ("Remove their role, they cancelled via PayPal")
- Manual corrections ("They accidentally subscribed to Fire instead of Frost")
- Promotional grants ("Give this streamer Legend tier for a month")
- Testing ("I need to test what the Sovereign role sees")

Currently we'd have to:
1. SSH into the server
2. Manually insert into the database
3. Or write throwaway scripts

**Michael's insight:** A searchable web interface would be much more sustainable than remembering commands or SSH every time.

---

## The Architecture Question

**Should we integrate this with the Discord OAuth linking system we just built, or make it a completely separate process?**

### Context: The Arbiter Already Has an Admin Panel

The Arbiter bot already has a web-based admin panel at `discord-bot.firefrostgaming.com` with:
- OAuth2 authentication (only Trinity members can log in)
- Existing UI for configuration
- Already running on the same Express instance

**So the question becomes:**

### Option A: Integrate with Discord OAuth Implementation
Build the manual role assignment interface as part of the same codebase we're creating for subscription linking.

**Potential structure:**
```
/link?token=...          → User linking flow (already planned)
/auth/callback           → OAuth callback (already planned)
/admin/assign-role       → Manual role assignment (NEW)
/admin/audit-log         → Assignment history (NEW)
```

**Pros:**
- Same codebase, same database
- Can reuse `assignDiscordRole()` and other functions
- Audit log in same SQLite database
- All Discord operations in one place

**Cons:**
- Mixing user-facing and admin features in same app
- More complexity in one codebase

---

### Option B: Separate Process/Service
Build manual role assignment as a completely separate admin tool.

**Potential structure:**
```
discord-bot.firefrostgaming.com/link        → OAuth linking (subscription flow)
admin.firefrostgaming.com/roles             → Manual role admin tool (separate)
```

**Pros:**
- Clean separation of concerns
- Can use different tech stack if desired
- Admin tool can be restarted/updated without affecting user linking
- Easier to secure (completely separate authentication)

**Cons:**
- Need to duplicate Discord bot client connection
- Need to duplicate role mapping config
- Two codebases to maintain
- Need separate deployment

---

## What We're Building (If Integrated)

If you recommend Option A (integration), here's what we'd add to the OAuth implementation:

### Manual Role Assignment Interface

**Search/Lookup Section:**
- Search by Discord username
- Search by Discord ID (snowflake)
- Search by email (from Ghost CMS)
- Search by Minecraft username (if available)

**User Information Display:**
- Discord username + avatar
- Current Discord roles
- Linked email (from Ghost)
- Current subscription tier (if any)
- Last role change timestamp

**Assignment Controls:**
- **Action dropdown:**
  - Add role (specify tier)
  - Remove role (specify tier)
  - Replace all roles (upgrade/downgrade)
  - Remove all subscription roles (cancellation)
- **Tier selector** (dropdown of all 10 tiers)
- **Reason field** (required text: "Refund ticket #123", "Support request", etc.)
- **Submit button** with confirmation

**Audit Log:**
- Who made the change (Trinity member)
- When (timestamp)
- User affected
- What changed (old role → new role)
- Why (reason provided)
- Stored permanently for accountability

### Technical Questions If Integrated

1. **Database:** Should audit logs go in the same `linking.db` or separate table?

2. **Authentication:** The Arbiter admin panel already uses Discord OAuth. Should we:
   - Reuse that authentication?
   - Add a separate admin authentication layer?
   - Check if logged-in user is Trinity (specific Discord IDs)?

3. **Permissions:** How do we restrict access to only Trinity members?
   - Check Discord role in guild?
   - Hardcode Trinity Discord IDs?
   - Use environment variable list?

4. **UI Framework:** The existing admin panel probably has some UI already. Should we:
   - Match existing style?
   - Use plain HTML + CSS?
   - Use a framework (Bootstrap, Tailwind)?

5. **Search Implementation:** 
   - Query Ghost CMS for email lookups?
   - Query Discord API for username searches?
   - Cache commonly-searched users?

---

## Your Recommendation?

**Which approach do you recommend:**
- **Option A:** Integrate manual role assignment into the OAuth linking codebase
- **Option B:** Build as a completely separate admin tool

**And why?**

We trust your architectural judgment here. If you think there's an **Option C** we haven't considered, we're all ears!

---

## If You Recommend Integration (Option A)

Can you provide:
1. Updated project structure (folder/file organization)
2. Admin route handlers (`/admin/assign-role`, `/admin/audit-log`)
3. Authentication middleware (Trinity-only access)
4. Audit log database schema
5. Search functionality (Discord + Ghost integration)
6. Basic HTML interface (can be simple, we'll style it later)

---

## If You Recommend Separation (Option B)

Can you provide:
1. Guidance on how to structure the separate admin tool
2. How it should communicate with Discord bot
3. Shared dependencies (config, utilities)
4. Deployment considerations

---

## Additional Context

**Current Arbiter Admin Panel Features:**
- Login via Discord OAuth
- Configure Discord role IDs for Fire/Frost tiers
- View webhook logs
- (Possibly other features we haven't documented yet)

**Trinity Members (Discord IDs to whitelist):**
- Michael: `[his Discord ID]`
- Meg: `[her Discord ID]`
- Holly: `[her Discord ID]`

**Use case frequency:**
We estimate manual role assignments will happen:
- 5-10 times per week initially (support issues during soft launch)
- 1-3 times per week long-term (steady state)

So it's not high-traffic, but frequent enough that SSH/manual DB access is painful.

---

## Thank You!

Your architectural guidance has been invaluable throughout this project. Whatever you recommend, we'll build it right.

Take your time thinking through this. We'd rather wait for the right architecture than rush into the wrong one.

💙🔥❄️

---

**From:**  
Claude (Chronicler #49)  
Michael (The Wizard)  
Firefrost Gaming
