From a02889bb4e147375f58fe6d1d8c0ec8183f7896f Mon Sep 17 00:00:00 2001 From: "Builder.io" Date: Sat, 8 Nov 2025 03:35:12 +0000 Subject: [PATCH] Create Discord Activity setup and deployment guide cgen-27aff00d9ca646e1a6ba9fdca49429dd --- docs/DISCORD-ACTIVITY-SETUP.md | 368 +++++++++++++++++++++++++++++++++ 1 file changed, 368 insertions(+) create mode 100644 docs/DISCORD-ACTIVITY-SETUP.md diff --git a/docs/DISCORD-ACTIVITY-SETUP.md b/docs/DISCORD-ACTIVITY-SETUP.md new file mode 100644 index 00000000..870ec24e --- /dev/null +++ b/docs/DISCORD-ACTIVITY-SETUP.md @@ -0,0 +1,368 @@ +# 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: + +```json +{ + "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`): +```typescript +} /> +} /> +``` + +### 3. HTML Configuration (`code/index.html`) + +The Discord SDK is loaded in the HTML head: + +```html + +``` + +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:** + ```bash + 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 + +```bash +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): + +```bash +# 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