Dashboard Setup

This guide covers setting up and running the moderator dashboard locally.

Prerequisites

• Node.js v20+
• pnpm v10+
• The bot is already configured and running (see Getting Started)

1. Discord Developer Portal Setup

The dashboard uses Discord OAuth2 to authenticate moderators. You need to register a redirect URI in the Discord Developer Portal.

1. Go to the Discord Developer Portal
2. Select your application
3. Navigate to OAuth2 in the sidebar
4. Under Redirects, add:

http://localhost:4000/api/oauth/callback

This is the bot's API callback endpoint — Discord will redirect users here after they authorize.

2. Bot Environment Variables

In your root .env file, ensure these three variables are set:

Variable	Description	Example
CLIENT_ID	Your Discord application's client ID	123456789012345678
CLIENT_SECRET	Your Discord application's client secret	abcdef...
API_REDIRECT	Must exactly match the redirect URI registered in the Discord portal	http://localhost:4000/api/oauth/callback

You also need DASHBOARD_URL to tell the bot where to redirect after OAuth completes:

DASHBOARD_URL=http://localhost:3000

3. Dashboard Environment Variables

Create dashboard/.env.local with:

# Bot API URL (must match where the bot's HTTP API is running)
NEXT_PUBLIC_BOT_API_URL=http://localhost:4000

Or copy from the example:

cp dashboard/.env.example dashboard/.env.local

4. Running the Dashboard

cd dashboard
pnpm install
pnpm dev

The dashboard will be available at http://localhost:3000.

Make sure the bot is also running (pnpm dev in the project root) — the dashboard calls the bot's REST API for all data.

OAuth Login Flow

When a user clicks Login on the dashboard, this is the full flow:

1. Dashboard redirects to bot API
   GET http://localhost:4000/api/oauth/login
                    │
                    ▼
2. Bot redirects to Discord
   GET https://discord.com/api/oauth2/authorize
   (with client_id, redirect_uri, scopes)
                    │
                    ▼
3. User authorizes on Discord
                    │
                    ▼
4. Discord redirects back to bot
   GET http://localhost:4000/api/oauth/callback?code=...
                    │
                    ▼
5. Bot exchanges code for access token (server-side)
   POST https://discord.com/api/v10/oauth2/token
                    │
                    ▼
6. Bot redirects to dashboard with token
   GET http://localhost:3000/api/auth/callback?token=...
                    │
                    ▼
7. Dashboard sets DASHBOARD_AUTH cookie
   Redirects to /guilds

The critical point: the API_REDIRECT env var must match exactly what you registered in the Discord Developer Portal. The DASHBOARD_URL must match the URL where the dashboard is running.

Mod Dashboard Authentication

The /mod/* routes are protected by a Next.js middleware that checks for the DASHBOARD_AUTH cookie. Unauthenticated users are redirected to /mod/login.

The mod login page reuses the same bot-backend OAuth flow described above. When the user clicks Authenticate with Discord:

1. A mod_auth_redirect cookie is set with value /mod (expires in 5 minutes)
2. The browser is redirected to BOT_API_URL/api/oauth/login
3. The standard OAuth flow runs (Discord authorize -> bot callback -> dashboard callback)
4. The dashboard auth callback checks for the mod_auth_redirect cookie
5. If present, it redirects to /mod instead of the default /guilds

This means no separate OAuth application or auth library is needed — the mod dashboard shares the same DASHBOARD_AUTH session as the rest of the dashboard. The middleware simply gates access at the Next.js layer.

Account Switcher

The sidebar includes an AccountSwitcher component at the bottom. It fetches the current user from BOT_API_URL/api/users/@me (using the DASHBOARD_AUTH cookie) and provides:

• Switch Account — opens the OAuth flow in a popup window
• Log Out — calls POST /api/oauth/logout to clear the cookie, then redirects to /mod/login

Troubleshooting

Login button does nothing

The dashboard can't reach the bot API. Check that:

• NEXT_PUBLIC_BOT_API_URL in dashboard/.env.local points to the running bot (default: http://localhost:4000)
• The bot is actually running

Discord says "Invalid redirect URI"

The redirect URI registered in the Discord Developer Portal doesn't match API_REDIRECT in your .env. They must be identical, including protocol, host, port, and path:

http://localhost:4000/api/oauth/callback

Redirects to dashboard but not logged in

The bot is redirecting to the wrong dashboard URL. Check that DASHBOARD_URL in your root .env matches where the dashboard is actually running:

# Must match the dashboard's actual URL and port
DASHBOARD_URL=http://localhost:3000

401 on API calls

• Verify the bot is running and accessible at the URL configured in NEXT_PUBLIC_BOT_API_URL
• Check that the DASHBOARD_AUTH cookie is being set (inspect cookies in browser dev tools)
• Try logging out and logging in again

CORS errors in browser console

When API_ORIGIN=* (the default), the bot automatically uses DASHBOARD_URL as the CORS origin since cookie-based auth requires a specific origin (browsers reject the * wildcard with credentials: 'include').

If you still get CORS errors, set API_ORIGIN explicitly:

API_ORIGIN=http://localhost:3000

For production, set it to your dashboard's domain.

Related

• Getting Started - Bot setup
• REST Routes - API endpoint reference
• Evidence System - Evidence upload and management
• Architecture - System design overview