aethex-forge/docs/DISCORD-ACTIVITY-SETUP.md

Discord Activity Setup & Deployment Guide

Overview

AeThex can be embedded as a Discord Activity, allowing users to access the platform directly within Discord servers. This guide covers the setup, configuration, and deployment process.

What is a Discord Activity?

A Discord Activity is an embedded application that runs within Discord. It allows users to:

• Access AeThex features directly in Discord
• Share their experience with server members
• Collaborate in real-time without leaving Discord

Architecture

Discord Server
    ↓
Discord Activity (https://aethex.dev/discord)
    ↓
AeThex Frontend + Backend
    ↓
Supabase + DevConnect DBs

Prerequisites

• Discord Application: Application ID 578971245454950421
• Domain: https://aethex.dev (must be a proper domain, not IP)
• SSL/HTTPS: Required for Discord Activities
• Cloudflare: Configured to allow traffic to aethex.dev

Configuration Files

1. Discord Manifest (code/public/discord-manifest.json)

This file tells Discord how to handle the AeThex Activity:

{
  "id": "578971245454950421",
  "name": "AeThex",
  "url": "https://aethex.dev",
  "instance_url": "https://aethex.dev/discord",
  "oauth2": {
    "client_id": "578971245454950421",
    "scopes": ["identify", "email", "guilds"],
    "redirect_uris": ["https://aethex.dev/discord/callback"]
  }
}

Key Configuration Points:

• instance_url: Where Discord Activity iframe loads (MUST be domain, not IP)
• redirect_uris: OAuth callback endpoint (MUST match Discord app settings)
• scopes: What Discord permissions the Activity requests

2. Code Configuration

Frontend Pages (code/client/pages/):

• DiscordActivity.tsx - Main Activity page mounted at /discord
• Discord OAuth callback handler at /discord/callback

Context (code/client/contexts/DiscordContext.tsx):

• Manages Discord user session
• Handles OAuth flow
• Exposes Discord user data to components

Routes (code/client/App.tsx):

<Route path="/discord" element={<DiscordActivity />} />
<Route path="/discord/callback" element={<DiscordOAuthCallback />} />

3. HTML Configuration (code/index.html)

The Discord SDK is loaded in the HTML head:

<script async src="https://cdn.discordapp.com/assets/embed.js"></script>

This must be present for Discord Activity to initialize.

Local Testing

Prerequisites

• Node.js 18+
• npm or yarn
• Running AeThex dev server

Steps

1. Start the dev server:

   npm run dev
   # or
   yarn dev
   

2. Access locally via tunnel (if testing Discord Activity):

   • Use a tool like ngrok to expose localhost to Discord
   • Or use Discord's local testing tools

3. Test routes:

   • Activity: http://localhost:5173/discord (becomes domain in production)
   • Callback: http://localhost:5173/discord/callback

Local Testing Limitations

⚠️ Note: Discord Activities require HTTPS and a proper domain. Local testing with IP addresses will fail with Cloudflare Error 1003.

Local testing workarounds:

• Use ngrok with a tunnel URL
• Use Discord's local testing documentation
• Test OAuth flow after deploying to staging

Deployment

Production URLs (MUST use domain, not IP)

• Activity URL: https://aethex.dev/discord
• OAuth Redirect: https://aethex.dev/discord/callback
• Manifest: https://aethex.dev/public/discord-manifest.json

Deployment Checklist

• App deployed to aethex.dev domain
• SSL/HTTPS certificate valid and active
• Cloudflare configured to allow traffic to aethex.dev
• Discord manifest file accessible at /public/discord-manifest.json
• Discord SDK script loads successfully in browser console
• OAuth redirect URIs match Discord app settings
• Discord Application ID is correct: 578971245454950421

Cloudflare Configuration

Critical: Cloudflare blocks direct IP access (Error 1003). Ensure:

1. DNS record for aethex.dev points to correct server/CDN
2. Cloudflare allows traffic to your origin
3. SSL/TLS encryption is enabled
4. No IP-based redirect rules that block Activity iframe

Environment Variables

No special environment variables needed for Discord Activity. The configuration is done via:

• code/public/discord-manifest.json
• Discord Application settings
• code/client/contexts/DiscordContext.tsx

OAuth Flow

High-Level Flow

1. User opens AeThex Activity in Discord
2. DiscordActivity page loads (/discord)
3. Discord SDK initializes with manifest config
4. User clicks "Login with Discord"
5. Redirects to Discord's OAuth authorization page
6. User grants permissions (identify, email, guilds)
7. Discord redirects back to https://aethex.dev/discord/callback
8. DiscordOAuthCallback processes the authorization code
9. Backend exchanges code for access token
10. User session created, redirected to main Activity UI

Implementation Details

DiscordActivity.tsx handles:

• Discord SDK initialization
• OAuth trigger and callback handling
• Activity UI rendering

DiscordContext.tsx manages:

• Discord user state
• Token storage
• Session lifecycle

API calls use Discord access token for:

• User identification
• Guild information
• Activity-specific operations

Error Handling

Cloudflare Error 1003: Direct IP Access Not Allowed

Cause: Accessing Activity via IP address instead of domain

Solution:

❌ http://192.168.1.100:5173/discord
✅ https://aethex.dev/discord

Error Message in UI: Users will see a helpful error message explaining:

• The issue (Cloudflare blocking IP access)
• How to fix it (use domain instead)
• Troubleshooting steps

Discord SDK Error

Cause: Discord SDK not loaded or manifest invalid

Solution:

• Verify Discord SDK script in code/index.html
• Check manifest is accessible at /public/discord-manifest.json
• Verify Discord Application ID: 578971245454950421

Testing Checklist

Functional Tests

• Activity loads without Cloudflare errors
• Discord SDK initializes successfully
• OAuth flow completes successfully
• User is authenticated in AeThex after OAuth
• Activity can access user Discord profile info
• Activity can read server/guild information
• Multiple users can run Activity simultaneously

Security Tests

• OAuth tokens are stored securely
• HTTPS enforced (no HTTP fallback)
• CORS headers properly configured
• No sensitive data in localStorage
• Logout properly clears session

Browser Tests

• Works in Discord desktop client
• Works in Discord web client
• Works in Discord mobile app
• Responsive design works in Discord's narrow sidebar

Troubleshooting

Activity Won't Load

Error: Blank white screen in Discord Activity

Debug Steps:

1. Open browser DevTools in Discord
2. Check Console for errors
3. Check Network tab for failed requests
4. Verify domain is accessible (test in regular browser tab)
5. Verify Cloudflare isn't blocking traffic

Common Causes:

• IP address used instead of domain (Cloudflare Error 1003)
• Discord SDK script failed to load
• Manifest file not accessible
• CORS policy violation

OAuth Not Working

Error: OAuth flow doesn't complete or redirect fails

Debug Steps:

1. Check Discord Application settings - redirect URIs match exactly
2. Verify OAuth callback route exists: /discord/callback
3. Check browser console for authorization error codes
4. Verify Discord Application permissions (identify, email, guilds)

Common Causes:

• Redirect URI mismatch between manifest and Discord app
• Discord Application doesn't have "Identify" scope enabled
• Activity not installed in Discord server

User Can't See Guild Information

Error: Guild list is empty or shows no servers

Debug Steps:

1. Verify "guilds" scope is in OAuth config
2. Check user actually has permission in those guilds
3. Verify Discord OAuth token has guilds scope

Deployment to Production

Step 1: Build

npm run build
# or
yarn build

This creates optimized bundles in dist/ directory.

Step 2: Verify Configuration

• Discord manifest is in dist/public/discord-manifest.json
• All routes are correctly wired in App.tsx
• No hardcoded localhost URLs

Step 3: Deploy

Using your deployment provider (Netlify, Vercel, custom):

# Deploy dist/ folder to https://aethex.dev

Step 4: Verify in Production

1. Access https://aethex.dev/discord in browser
2. Check DevTools Console for errors
3. Try Discord Activity in actual Discord server
4. Test OAuth flow end-to-end

Step 5: Add to Discord

In Discord Developer Portal:

1. Go to Application Settings
2. Add Activity URL: https://aethex.dev/discord
3. Set OAuth2 Redirect URIs to: https://aethex.dev/discord/callback
4. Publish Application
5. Users can now install AeThex Activity in servers

File Structure

code/
├── client/
│   ├── pages/
│   │   └── DiscordActivity.tsx        # Main Activity page
│   ├── contexts/
│   │   └── DiscordContext.tsx         # Discord OAuth/session management
│   └── App.tsx                        # Routes: /discord, /discord/callback
├── index.html                         # Discord SDK script loaded here
├── public/
│   └── discord-manifest.json          # Discord Activity configuration
└── docs/
    └── DISCORD-ACTIVITY-SETUP.md      # This file

Related Documentation

• IP Governance: code/docs/IP-GOVERNANCE-FRAMEWORK.md - Data ownership and licensing
• Onboarding: code/client/pages/Onboarding.tsx - User onboarding flow
• Authentication: code/client/contexts/AuthContext.tsx - Primary auth system

Support

For issues or questions:

1. Check this guide for common troubleshooting
2. Check Discord Developer Docs: https://discord.com/developers/docs/activities/building-an-app
3. Check browser console for specific error messages
4. Verify domain/DNS configuration with Cloudflare

Version History

• v1.0.0 (Current)
  • Discord Activity foundation
  • OAuth 2.0 integration
  • Cloudflare Error 1003 handling
  • Multi-user support

---

Last Updated: 2024 Maintained by: AeThex Engineering Team