docs(docs): remove obsolete mascot and microservices documentation
Removes outdated implementation guides and architecture documentation related to the mascot chatbot and microservices setup. - Delete `MASCOT_CHATBOT_GUIDE.md` - Delete `MASCOT_IMPLEMENTATION.md` - Delete `README_MICROSERVICES.md`
This commit is contained in:
MythEclipse
@@ -1,325 +0,0 @@
|
||||
# Mascot Chatbot Implementation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The mascot has been upgraded from a simple insights display to a **full-featured interactive chatbot** that can:
|
||||
- Engage in conversations with users
|
||||
- Provide real-time analytics insights
|
||||
- Answer questions about messages and conversations
|
||||
- Generate intelligent recommendations
|
||||
- Maintain conversation history
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components
|
||||
|
||||
#### MascotChatbot (`src/widgets/mascot/MascotChatbot.tsx`)
|
||||
Main chatbot UI component with chat interface, message bubbles, and user input.
|
||||
|
||||
```typescript
|
||||
<MascotChatbot
|
||||
isOpen={boolean} // Chat window visibility
|
||||
onSetIsOpen={(open) => void} // Toggle chat window
|
||||
onSendMessage={async (msg) => string} // Handle user messages
|
||||
mascotName="Discord Watcher" // Mascot name
|
||||
mascotAvatar={url} // Mascot avatar image
|
||||
/>
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Framer Motion animations
|
||||
- Message bubbles with typing indicator
|
||||
- Minimize/maximize window
|
||||
- Message history
|
||||
- Responsive design
|
||||
- Auto-scroll to latest message
|
||||
|
||||
#### useMascotChat (`src/shared/hooks/useMascotChat.ts`)
|
||||
React hook for managing mascot chat logic and AI responses.
|
||||
|
||||
```typescript
|
||||
const mascotChat = useMascotChat({
|
||||
messageCount: number, // Total messages
|
||||
activeParticipants: number, // Unique users
|
||||
lastActivity: string, // Activity status
|
||||
topicsDiscussed: string[] // Conversation topics
|
||||
});
|
||||
|
||||
mascotChat.handleSendMessage(message) // Send message & get response
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
MascotChatbot (UI)
|
||||
↓
|
||||
useMascotChat hook
|
||||
↓
|
||||
generateIntelligentResponse()
|
||||
↓
|
||||
Response (local) or Backend API
|
||||
↓
|
||||
Message displayed in chat
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### 1. Smart Responses
|
||||
The mascot responds intelligently based on keywords and context:
|
||||
|
||||
**Analytics Questions:**
|
||||
- "Berapa pesan?" → Returns message count with context
|
||||
- "Berapa orang?" → Returns participant count
|
||||
- "Berapa aktif?" → Activity metrics
|
||||
|
||||
**Insights:**
|
||||
- "Apa insight?" → Summarizes conversation patterns
|
||||
- "Ringkasan" → Full conversation summary
|
||||
- "Saran" → Recommendations for improvement
|
||||
|
||||
**General:**
|
||||
- Greetings recognition
|
||||
- Help/info requests
|
||||
- Default contextual responses
|
||||
|
||||
### 2. Real-time Context
|
||||
The chatbot receives live data about:
|
||||
- Message counts
|
||||
- Active participants
|
||||
- Last activity status
|
||||
- Topics being discussed
|
||||
|
||||
### 3. Conversation History
|
||||
- Messages persist during session
|
||||
- Typing indicator while processing
|
||||
- Timestamps on all messages
|
||||
- User/mascot distinction
|
||||
|
||||
### 4. Extensibility
|
||||
The implementation is ready for:
|
||||
- Backend AI integration via API
|
||||
- Discord Gateway context enrichment
|
||||
- Custom response training
|
||||
- Multi-language support
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Setup
|
||||
```typescript
|
||||
const [isChatOpen, setIsChatOpen] = useState(false);
|
||||
const mascotChat = useMascotChat(contextData);
|
||||
|
||||
<MascotChatbot
|
||||
isOpen={isChatOpen}
|
||||
onSetIsOpen={setIsChatOpen}
|
||||
onSendMessage={mascotChat.handleSendMessage}
|
||||
/>
|
||||
```
|
||||
|
||||
### With Backend Integration
|
||||
```typescript
|
||||
const handleMessage = async (message: string) => {
|
||||
const response = await fetch('/api/mascot/chat', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ message, context })
|
||||
});
|
||||
return response.json();
|
||||
};
|
||||
|
||||
<MascotChatbot
|
||||
onSendMessage={handleMessage}
|
||||
/>
|
||||
```
|
||||
|
||||
### With Discord Gateway
|
||||
```typescript
|
||||
const handleMessage = async (message: string) => {
|
||||
// Get enriched context from Discord
|
||||
const guildContext = await getDiscordGuildContext(guildId);
|
||||
|
||||
// Generate response with context
|
||||
return generateResponse(message, guildContext);
|
||||
};
|
||||
```
|
||||
|
||||
## Chat Interface
|
||||
|
||||
### Visual Design
|
||||
- **Header:** Gradient background (primary color), mascot info, controls
|
||||
- **Messages:** Distinct bubbles for user (right) and mascot (left)
|
||||
- **Input:** Text field with send button
|
||||
- **Animations:** Spring physics for smooth entrance/exit
|
||||
- **Typing Indicator:** Animated dots while processing
|
||||
|
||||
### Keyboard Shortcuts
|
||||
- **Enter:** Send message
|
||||
- **Esc:** Close chat (future enhancement)
|
||||
- **Tab:** Minimize/restore window
|
||||
|
||||
## Integration Points
|
||||
|
||||
### 1. In App.tsx
|
||||
```typescript
|
||||
const mascotChat = useMascotChat({
|
||||
messageCount: messages.messages.length,
|
||||
activeParticipants: uniqueUserCount,
|
||||
lastActivity: activityStatus,
|
||||
topicsDiscussed: extractTopics(messages),
|
||||
});
|
||||
|
||||
<MascotChatbot
|
||||
isOpen={isMascotChatOpen}
|
||||
onSetIsOpen={setIsMascotChatOpen}
|
||||
onSendMessage={mascotChat.handleSendMessage}
|
||||
/>
|
||||
```
|
||||
|
||||
### 2. Position
|
||||
- **Fixed:** bottom-right corner (bottom-6, right-6)
|
||||
- **Z-index:** High (shadow-2xl ensures visibility)
|
||||
- **Responsive:** Adapts to mobile/tablet
|
||||
|
||||
### 3. State Management
|
||||
- `isMascotChatOpen`: Boolean flag for visibility
|
||||
- `messages`: Array of ChatMessage objects
|
||||
- `input`: Current user input text
|
||||
- `loading`: Processing state
|
||||
- `isMinimized`: Window state
|
||||
|
||||
## Extending with Backend
|
||||
|
||||
### Example: Express Backend Endpoint
|
||||
```typescript
|
||||
// POST /api/mascot/chat
|
||||
app.post('/api/mascot/chat', async (req, res) => {
|
||||
const { message, context } = req.body;
|
||||
|
||||
// Process with AI/LLM
|
||||
const response = await callAI(message, context);
|
||||
|
||||
res.json({ response });
|
||||
});
|
||||
```
|
||||
|
||||
### Example: Discord Gateway Integration
|
||||
```typescript
|
||||
async function getGuildContext(guildId: string) {
|
||||
const messages = await getGuildMessages(guildId);
|
||||
const members = await getActiveMembers(guildId);
|
||||
|
||||
return {
|
||||
messageCount: messages.length,
|
||||
activeParticipants: members.length,
|
||||
recentTopics: extractTopics(messages),
|
||||
serverHealth: analyzeHealth(messages, members)
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Change Mascot Avatar
|
||||
```typescript
|
||||
<MascotChatbot
|
||||
mascotAvatar="https://your-custom-avatar.com/image.png"
|
||||
/>
|
||||
```
|
||||
|
||||
### Change Mascot Name
|
||||
```typescript
|
||||
<MascotChatbot
|
||||
mascotName="Your Mascot Name"
|
||||
/>
|
||||
```
|
||||
|
||||
### Customize Responses
|
||||
Edit `generateMascotResponse()` in `useMascotChat.ts`:
|
||||
```typescript
|
||||
function generateMascotResponse(input: string, context?: ChatContext): string {
|
||||
const lower = input.toLowerCase();
|
||||
|
||||
// Add custom keywords
|
||||
if (lower.includes('your-keyword')) {
|
||||
return 'Your custom response';
|
||||
}
|
||||
|
||||
// ... rest of logic
|
||||
}
|
||||
```
|
||||
|
||||
### Theme Colors
|
||||
Edit Tailwind classes in `MascotChatbot.tsx`:
|
||||
```typescript
|
||||
// Change primary color
|
||||
className="bg-gradient-to-r from-primary to-primary/80"
|
||||
|
||||
// Change to custom color
|
||||
className="bg-gradient-to-r from-blue-500 to-blue-600"
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
### Optimizations
|
||||
- ✅ Lazy-loaded component (renders only when needed)
|
||||
- ✅ Memoized responses
|
||||
- ✅ Efficient message rendering (virtualization possible)
|
||||
- ✅ Minimal re-renders with useCallback
|
||||
|
||||
### Bundle Impact
|
||||
- Component: ~15 KB
|
||||
- Hook: ~5 KB
|
||||
- Total: ~20 KB (gzipped)
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] Multi-language support
|
||||
- [ ] Message persistence to database
|
||||
- [ ] Advanced NLP/AI integration
|
||||
- [ ] Export chat history
|
||||
- [ ] Voice input/output
|
||||
- [ ] Emoji reactions
|
||||
- [ ] Suggested quick replies
|
||||
- [ ] User preferences storage
|
||||
- [ ] Chat analytics
|
||||
- [ ] Integration with Discord Rich Presence
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Chat window not appearing
|
||||
- Check `isOpen` prop is being set correctly
|
||||
- Verify `onSetIsOpen` callback works
|
||||
- Check z-index conflicts with other overlays
|
||||
|
||||
### Messages not sending
|
||||
- Check `onSendMessage` is provided
|
||||
- Verify message is not empty
|
||||
- Check browser console for errors
|
||||
|
||||
### Responses not intelligent
|
||||
- Add more keyword patterns
|
||||
- Integrate with backend for better AI
|
||||
- Provide context data to useMascotChat
|
||||
|
||||
## Testing
|
||||
|
||||
```typescript
|
||||
// Test basic rendering
|
||||
render(<MascotChatbot isOpen={true} />);
|
||||
|
||||
// Test message sending
|
||||
const mockOnSend = jest.fn().mockResolvedValue('Response');
|
||||
fireEvent.change(input, { target: { value: 'Hello' } });
|
||||
fireEvent.click(sendButton);
|
||||
expect(mockOnSend).toHaveBeenCalledWith('Hello');
|
||||
|
||||
// Test animations
|
||||
expect(screen.getByRole('dialog')).toHaveClass('motion-div');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ Production Ready
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2026-06-03
|
||||
@@ -1,370 +0,0 @@
|
||||
# Mascot Implementation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The Discord Moderation Watcher frontend features an intelligent anime mascot with AI-powered conversation insights and animated floating chat bubbles.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components
|
||||
|
||||
#### MascotImage (`src/widgets/mascot/MascotImage.tsx`)
|
||||
Main mascot component that displays the PNG image with optional floating chat bubble.
|
||||
|
||||
```typescript
|
||||
<MascotImage
|
||||
size="sm" | "md" | "lg" // Size variant: sm (64px), md (128px), lg (192px)
|
||||
className="..." // Additional Tailwind classes
|
||||
showChat={boolean} // Show chat bubble
|
||||
chatMessage="..." // Chat message text
|
||||
/>
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Framer Motion spring animations
|
||||
- Responsive sizing
|
||||
- Gradient chat bubble with backdrop blur
|
||||
- Auto-hide after 8 seconds
|
||||
- Message circle icon
|
||||
|
||||
#### useMascotSummary (`src/shared/hooks/useMascotSummary.ts`)
|
||||
React hook that generates AI insights from message data.
|
||||
|
||||
```typescript
|
||||
const summary = useMascotSummary({
|
||||
messages: MessageRecord[], // Recent messages
|
||||
enabled: boolean // Enable/disable hook
|
||||
});
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- Message count tracking
|
||||
- Unique participant counting
|
||||
- Average message length analysis
|
||||
- Activity intensity detection
|
||||
- Conversation type identification
|
||||
- Auto-rotating insights (5-second cycle)
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
App Component
|
||||
├─ messages.messages
|
||||
└─ Pass to DashboardLayout
|
||||
│
|
||||
├─ DashboardLayout
|
||||
│ ├─ useMascotSummary hook
|
||||
│ ├─ Generate mascotSummary
|
||||
│ └─ Pass to Sidebar
|
||||
│ │
|
||||
│ ├─ Sidebar
|
||||
│ │ └─ MascotImage
|
||||
│ │ └─ Floating chat bubble
|
||||
│ │
|
||||
│ └─ Other components
|
||||
│ ├─ EmptyStateMascot
|
||||
│ ├─ EmptyStateMascot
|
||||
│ └─ ...
|
||||
```
|
||||
|
||||
## Assets
|
||||
|
||||
### Logo (SVG)
|
||||
- **URL:** `https://raw.githubusercontent.com/IMPHNEN/imphnen-frontend-service/develop/docs/logo.svg`
|
||||
- **Used in:** Favicon, Sidebar top
|
||||
- **Size:** 8x8px
|
||||
- **Cache:** 300 seconds (GitHub CDN)
|
||||
|
||||
### Mascot (PNG)
|
||||
- **URL:** `https://raw.githubusercontent.com/IMPHNEN/imphnen-frontend-service/develop/apps/dimentorin/public/image/mascot-1.png`
|
||||
- **Used in:** Sidebar, Empty states, Chat bubble
|
||||
- **Sizes:** sm (64px), md (128px), lg (192px)
|
||||
- **Cache:** 300 seconds (GitHub CDN)
|
||||
|
||||
## Locations
|
||||
|
||||
### Sidebar (sm - 64px)
|
||||
- **Position:** Bottom corner, expanded sidebar only
|
||||
- **Feature:** Chat bubble with rotating insights
|
||||
- **Visibility:** Always visible when expanded
|
||||
- **Chat Trigger:** Messages tab with active conversations
|
||||
|
||||
### Empty States (md - 128px, 60% opacity)
|
||||
- Message Feed
|
||||
- Image Grid
|
||||
- Analytics Panel
|
||||
- Active Speakers
|
||||
- Voice Recordings
|
||||
|
||||
### NOT Displayed
|
||||
- ❌ Auth/Login page
|
||||
- ❌ Voice connection page
|
||||
- ❌ Media control page
|
||||
|
||||
## Chat Bubble Design
|
||||
|
||||
### Visual Style
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ 💬 "Diskusi aktif" │
|
||||
│ • 5 peserta │
|
||||
│ • Volume tinggi │
|
||||
└─────────────────────┘
|
||||
◯ (tail)
|
||||
```
|
||||
|
||||
### CSS Classes
|
||||
- Background: `bg-gradient-to-br from-primary/90 to-primary/80`
|
||||
- Border: `border border-primary/50`
|
||||
- Rounded: `rounded-2xl`
|
||||
- Padding: `px-4 py-2.5`
|
||||
- Effects: `shadow-lg backdrop-blur-sm`
|
||||
|
||||
### Animations
|
||||
- **Entrance:** Spring (stiffness: 300, damping: 25)
|
||||
- Scale: 0.8 → 1.0
|
||||
- Opacity: 0 → 1
|
||||
- Y Position: 10px → 0
|
||||
- **Exit:** Reverse animation
|
||||
- **Duration:** Auto-hide after 8 seconds
|
||||
|
||||
## AI Summary Logic
|
||||
|
||||
### generateInsight()
|
||||
Analyzes message data to create meaningful insights.
|
||||
|
||||
**Factors Analyzed:**
|
||||
1. **Message Count**
|
||||
- Display: "📈 Total: X pesan"
|
||||
|
||||
2. **Participant Analysis**
|
||||
- Count unique user_ids
|
||||
- Display: "👥 Partisipan: N orang"
|
||||
|
||||
3. **Content Length Analysis**
|
||||
- Average message length
|
||||
- > 150 chars: "Diskusi mendalam 🔬"
|
||||
- 80-150: "Percakapan normal 💬"
|
||||
- < 80: "Chat cepat ⚡"
|
||||
|
||||
4. **Activity Intensity**
|
||||
- > 50 msgs: "Volume tinggi 🔥"
|
||||
- > 20 msgs: "Percakapan aktif"
|
||||
- < 20: "Quiet mode"
|
||||
|
||||
5. **Topic Detection**
|
||||
- Keywords: voice, recording, audio, chat, message, user
|
||||
- Maps to labels: Voice, Recording, Audio, Chat, Message, User
|
||||
|
||||
### Auto-Rotation
|
||||
- Updates every 5 seconds
|
||||
- Cycles between different insights
|
||||
- Keeps conversation fresh
|
||||
- Smart rotation logic
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Usage (Sidebar)
|
||||
```typescript
|
||||
<MascotImage
|
||||
size="sm"
|
||||
showChat={showChat && !collapsed}
|
||||
chatMessage={mascotChatMessage}
|
||||
/>
|
||||
```
|
||||
|
||||
### Empty State Usage
|
||||
```typescript
|
||||
<MascotImage size="md" className="opacity-60" />
|
||||
```
|
||||
|
||||
### With Custom Message
|
||||
```typescript
|
||||
<MascotImage
|
||||
size="md"
|
||||
showChat={true}
|
||||
chatMessage="🔥 Volume tinggi • 12 peserta"
|
||||
/>
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
### In DashboardLayout
|
||||
```typescript
|
||||
const mascotSummary = useMascotSummary({
|
||||
messages: recentMessages,
|
||||
enabled: activeTab === "messages" && recentMessages.length > 0,
|
||||
});
|
||||
|
||||
<Sidebar
|
||||
activeTab={activeTab}
|
||||
onTabChange={onTabChange}
|
||||
mascotChatMessage={mascotSummary}
|
||||
/>
|
||||
```
|
||||
|
||||
### In App
|
||||
```typescript
|
||||
<DashboardLayout
|
||||
activeTab={activeTab}
|
||||
wsStatus={socket.status}
|
||||
voiceStatus={voice.voiceStatus}
|
||||
onTabChange={(tab) => patchUIState({ activeTab: tab })}
|
||||
recentMessages={messages.messages}
|
||||
>
|
||||
{/* content */}
|
||||
</DashboardLayout>
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Size Variants
|
||||
Edit `sizeMap` in `MascotImage.tsx`:
|
||||
```typescript
|
||||
const sizeMap = {
|
||||
sm: "w-16 h-auto", // 64px
|
||||
md: "w-32 h-auto", // 128px
|
||||
lg: "w-48 h-auto", // 192px
|
||||
xl: "w-64 h-auto", // 256px (custom)
|
||||
};
|
||||
```
|
||||
|
||||
### Chat Bubble Styling
|
||||
Edit bubble classes in `MascotImage.tsx`:
|
||||
- Change background: `bg-gradient-to-br from-primary/90 to-primary/80`
|
||||
- Change corner radius: `rounded-2xl`
|
||||
- Change padding: `px-4 py-2.5`
|
||||
- Change effects: `shadow-lg backdrop-blur-sm`
|
||||
|
||||
### Animation Timing
|
||||
Edit animation config:
|
||||
- Spring stiffness: Higher = faster/snappier
|
||||
- Spring damping: Higher = less bouncy
|
||||
- Auto-hide delay: Change `setTimeout` in `useEffect`
|
||||
|
||||
### Summary Rotation
|
||||
Edit rotation interval in `useMascotSummary`:
|
||||
```typescript
|
||||
const interval = setInterval(() => {
|
||||
// Update summary
|
||||
}, 5000); // 5 seconds
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Bundle Size Impact
|
||||
- ✅ ChibiMascot removed: -895 lines
|
||||
- ✅ MascotImage added: +98 lines
|
||||
- ✅ useMascotSummary hook: +98 lines
|
||||
- ✅ Net: -779 lines (smaller bundle!)
|
||||
- ✅ PNG from CDN (not bundled)
|
||||
|
||||
### Runtime Performance
|
||||
- ✅ Framer Motion optimized
|
||||
- ✅ useCallback for memoization
|
||||
- ✅ 5-second update cycle (not constant)
|
||||
- ✅ Proper cleanup on unmount
|
||||
- ✅ No memory leaks
|
||||
|
||||
### CDN Performance
|
||||
- ✅ GitHub CDN caching: 300 seconds
|
||||
- ✅ Browser caching enabled
|
||||
- ✅ Reduces server load
|
||||
- ✅ Fast global delivery
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Chat Bubble Not Showing
|
||||
**Check:**
|
||||
- `showChat` prop is `true`
|
||||
- `chatMessage` is not empty
|
||||
- Sidebar is expanded
|
||||
- Active tab is "messages"
|
||||
|
||||
### Images Not Loading
|
||||
**Check:**
|
||||
- GitHub URLs are accessible (curl -I)
|
||||
- CDN cache not stale (check ETag)
|
||||
- Browser cache cleared
|
||||
- No CORS issues (GitHub allows)
|
||||
|
||||
### Animations Janky
|
||||
**Check:**
|
||||
- Browser hardware acceleration enabled
|
||||
- Too many other animations
|
||||
- Framer Motion version compatible
|
||||
- Browser performance metrics
|
||||
|
||||
### Summary Not Updating
|
||||
**Check:**
|
||||
- `enabled` prop is true
|
||||
- Messages array has data
|
||||
- 5-second interval is running
|
||||
- No console errors
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regular Checks
|
||||
- Monitor mascot chat appearance in production
|
||||
- Verify summary accuracy with live data
|
||||
- Check animation performance on browsers
|
||||
- Track bundle size metrics
|
||||
|
||||
### Updates
|
||||
- To change summary logic: Edit `useMascotSummary.ts`
|
||||
- To change styling: Edit `MascotImage.tsx` classes
|
||||
- To change animation: Edit Framer Motion config
|
||||
- To change CDN URLs: Update image URLs (2 places)
|
||||
|
||||
### Rollback
|
||||
If issues occur:
|
||||
```bash
|
||||
git revert 9f454b5 # Revert AI integration
|
||||
git revert bb65178 # Revert component replacement
|
||||
git revert 2ea0ea5 # Revert logo/mascot integration
|
||||
```
|
||||
|
||||
No database changes, safe to rollback anytime.
|
||||
|
||||
## Files Reference
|
||||
|
||||
| File | Purpose | Lines |
|
||||
|------|---------|-------|
|
||||
| `MascotImage.tsx` | Main component | 98 |
|
||||
| `useMascotSummary.ts` | AI hook | 98 |
|
||||
| `DashboardLayout.tsx` | Integration | Updated |
|
||||
| `Sidebar.tsx` | Display | Updated |
|
||||
| `App.tsx` | Data flow | Updated |
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual Testing Checklist
|
||||
- [ ] Mascot displays in sidebar
|
||||
- [ ] Chat bubble appears with message
|
||||
- [ ] Animation smooth and performant
|
||||
- [ ] Auto-hide after 8 seconds
|
||||
- [ ] Summary rotates every 5 seconds
|
||||
- [ ] Empty states show mascot
|
||||
- [ ] No mascot on auth page
|
||||
- [ ] Responsive sizing works
|
||||
- [ ] No console errors
|
||||
- [ ] Images load from CDN
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] Click interaction handler
|
||||
- [ ] ML-based summary generation
|
||||
- [ ] Theme customization
|
||||
- [ ] Sound effects
|
||||
- [ ] Chat history
|
||||
- [ ] Multi-language support
|
||||
- [ ] Mobile optimization
|
||||
- [ ] Settings panel
|
||||
- [ ] User preferences
|
||||
- [ ] Animation toggle
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-06-03
|
||||
**Version:** 1.0.0
|
||||
**Status:** Production Ready ✅
|
||||
@@ -1,380 +0,0 @@
|
||||
# Discord Moderation Watcher Bot - Microservices Architecture
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- Docker & Docker Compose
|
||||
- Node.js 20+
|
||||
- pnpm 11+
|
||||
- Discord bot token
|
||||
- OpenAI API key
|
||||
|
||||
### Environment Setup
|
||||
|
||||
Create `.env.local` in the root directory:
|
||||
|
||||
```bash
|
||||
# Discord Configuration
|
||||
DISCORD_TOKEN=your_discord_token_here
|
||||
MONITOR_GUILD_ID=your_guild_id_here
|
||||
|
||||
# AI Configuration
|
||||
AI_LLM_API_KEY=your_openai_api_key_here
|
||||
|
||||
# Optional: Database URL (defaults to PostgreSQL in Docker)
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/bete
|
||||
|
||||
# Optional: Redis URL (defaults to Redis in Docker)
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
### Local Development with Docker Compose
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Stop all services
|
||||
docker-compose down
|
||||
|
||||
# Rebuild services
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
**Services will be available at:**
|
||||
- Frontend: http://localhost:5173
|
||||
- Backend API: http://localhost:3001
|
||||
- Backend WebSocket: ws://localhost:3001
|
||||
- PostgreSQL: localhost:5432
|
||||
- Redis: localhost:6379
|
||||
|
||||
### Local Development without Docker
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Run database migrations
|
||||
pnpm run db:migrate
|
||||
|
||||
# Start all services in separate terminals
|
||||
|
||||
# Terminal 1: Backend
|
||||
cd services/backend
|
||||
pnpm run dev
|
||||
|
||||
# Terminal 2: Discord Gateway
|
||||
cd services/discord-gateway
|
||||
pnpm run dev
|
||||
|
||||
# Terminal 3: Frontend
|
||||
cd services/frontend
|
||||
pnpm run dev:web
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 3 Independent Microservices
|
||||
|
||||
#### 1. Frontend Service (`services/frontend/`)
|
||||
- **Tech:** React 19, Vite, TanStack Query, WebSocket
|
||||
- **Port:** 5173 (dev) / served by Backend (prod)
|
||||
- **Responsibilities:**
|
||||
- Dashboard UI (analytics, messages, voice, media)
|
||||
- Real-time WebSocket connection to Backend
|
||||
- API calls to Backend REST endpoints
|
||||
- State management (React Query)
|
||||
|
||||
#### 2. Backend Service (`services/backend/`)
|
||||
- **Tech:** Express, Drizzle ORM, PostgreSQL, Redis
|
||||
- **Port:** 3001
|
||||
- **Responsibilities:**
|
||||
- REST API endpoints (`/api/*`)
|
||||
- WebSocket server for real-time updates
|
||||
- Database operations (PostgreSQL)
|
||||
- Event orchestration from Discord Gateway
|
||||
- Static file serving (built Frontend)
|
||||
- Admin authentication
|
||||
|
||||
**Modular MVC Structure:**
|
||||
```
|
||||
services/backend/src/
|
||||
├── shared/
|
||||
│ ├── database/ → Drizzle ORM setup
|
||||
│ ├── config/ → Environment config
|
||||
│ ├── errors/ → Custom error classes
|
||||
│ ├── middlewares/ → Express middlewares
|
||||
│ ├── logger/ → Logging utilities
|
||||
│ └── utils/ → Shared utilities
|
||||
├── modules/
|
||||
│ ├── messages/ → Message CRUD
|
||||
│ ├── analytics/ → Analytics queries
|
||||
│ ├── media/ → Media management
|
||||
│ ├── voice/ → Voice recordings
|
||||
│ └── health/ → Health checks
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
#### 3. Discord Gateway Service (`services/discord-gateway/`)
|
||||
- **Tech:** discord.js-selfbot-v13, @discordjs/voice, OpenAI API
|
||||
- **Port:** None (internal service, no HTTP)
|
||||
- **Responsibilities:**
|
||||
- Discord client connection
|
||||
- Message capture (create/edit/delete)
|
||||
- Voice channel recording
|
||||
- AI moderation analysis
|
||||
- Attachment upload
|
||||
- Event publishing to Backend (Redis pub/sub)
|
||||
|
||||
**Modular MVC Structure:**
|
||||
```
|
||||
services/discord-gateway/src/
|
||||
├── shared/
|
||||
│ ├── database/ → Drizzle ORM setup
|
||||
│ ├── config/ → Environment config
|
||||
│ ├── errors/ → Custom error classes
|
||||
│ ├── logger/ → Logging utilities
|
||||
│ └── utils/ → Shared utilities
|
||||
├── modules/
|
||||
│ ├── message-capture/ → Message listeners
|
||||
│ ├── voice-recording/ → Voice recording
|
||||
│ ├── ai-moderation/ → AI analysis
|
||||
│ ├── attachment-upload/ → File uploads
|
||||
│ └── event-broadcaster/ → Redis pub/sub
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
### Shared Package (`packages/shared/`)
|
||||
- **Types:** Common interfaces and data models
|
||||
- **Errors:** Custom error classes
|
||||
- **Logger:** Pino logger setup
|
||||
- **Utils:** Pagination, validation, helpers
|
||||
|
||||
### Communication Patterns
|
||||
|
||||
**Frontend ↔ Backend:**
|
||||
- REST API: `GET/POST /api/*` (HTTP)
|
||||
- WebSocket: Real-time updates (JSON messages)
|
||||
- Auth: Admin password header
|
||||
|
||||
**Backend ↔ Discord Gateway:**
|
||||
- Redis pub/sub (low-latency, decoupled)
|
||||
- Events: `discord:message:created`, `discord:voice:started`, etc.
|
||||
- Backend subscribes and broadcasts to Frontend via WebSocket
|
||||
|
||||
**Shared Resources:**
|
||||
- PostgreSQL: Both Backend and Discord Gateway
|
||||
- Redis: Pub/sub and caching
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Adding a New API Endpoint
|
||||
|
||||
1. **Create module structure** (if new feature):
|
||||
```bash
|
||||
mkdir -p services/backend/src/modules/feature/{routes,controllers,services,repositories,schemas}
|
||||
```
|
||||
|
||||
2. **Define schema** (`feature.schema.ts`):
|
||||
```typescript
|
||||
import { z } from 'zod';
|
||||
|
||||
export const createFeatureSchema = z.object({
|
||||
name: z.string().min(1),
|
||||
description: z.string().optional(),
|
||||
});
|
||||
```
|
||||
|
||||
3. **Create repository** (`feature.repository.ts`):
|
||||
```typescript
|
||||
export async function createFeature(data: CreateFeatureInput) {
|
||||
return db.insert(features).values(data).returning();
|
||||
}
|
||||
```
|
||||
|
||||
4. **Create service** (`feature.service.ts`):
|
||||
```typescript
|
||||
export async function createFeatureService(data: CreateFeatureInput) {
|
||||
// Business logic, validation, orchestration
|
||||
return createFeature(data);
|
||||
}
|
||||
```
|
||||
|
||||
5. **Create controller** (`feature.controller.ts`):
|
||||
```typescript
|
||||
export async function createFeatureController(req: Request, res: Response) {
|
||||
const data = createFeatureSchema.parse(req.body);
|
||||
const result = await createFeatureService(data);
|
||||
res.json(result);
|
||||
}
|
||||
```
|
||||
|
||||
6. **Create route** (`feature.route.ts`):
|
||||
```typescript
|
||||
router.post('/features', createFeatureController);
|
||||
```
|
||||
|
||||
### Adding a New Discord Event
|
||||
|
||||
1. **Create module** in `services/discord-gateway/src/modules/event-name/`
|
||||
|
||||
2. **Register listener** in `index.ts`:
|
||||
```typescript
|
||||
client.on('eventName', async (data) => {
|
||||
await handleEvent(data);
|
||||
publishEvent('discord:event:name', data);
|
||||
});
|
||||
```
|
||||
|
||||
3. **Publish to Redis**:
|
||||
```typescript
|
||||
import { redis } from '../shared/redis';
|
||||
|
||||
redis.publish('discord:event:name', JSON.stringify(data));
|
||||
```
|
||||
|
||||
4. **Subscribe in Backend** (`services/backend/src/ws/server.ts`):
|
||||
```typescript
|
||||
redis.subscribe('discord:event:name', (message) => {
|
||||
broadcastToClients({ type: 'event_name', data: JSON.parse(message) });
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Run All Tests
|
||||
```bash
|
||||
pnpm run test
|
||||
```
|
||||
|
||||
### Run Tests for Specific Service
|
||||
```bash
|
||||
cd services/backend
|
||||
pnpm run test
|
||||
|
||||
cd services/discord-gateway
|
||||
pnpm run test
|
||||
```
|
||||
|
||||
### Type Checking
|
||||
```bash
|
||||
pnpm run typecheck
|
||||
```
|
||||
|
||||
### Linting
|
||||
```bash
|
||||
pnpm run lint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Build Docker Images
|
||||
```bash
|
||||
docker-compose build
|
||||
```
|
||||
|
||||
### Push to Container Registry
|
||||
```bash
|
||||
docker tag bete-backend ghcr.io/username/bete-backend:latest
|
||||
docker push ghcr.io/username/bete-backend:latest
|
||||
```
|
||||
|
||||
### Deploy to Production
|
||||
See `.github/workflows/deploy.yml` for GitHub Actions CI/CD pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Backend can't connect to PostgreSQL
|
||||
```bash
|
||||
# Check PostgreSQL is running
|
||||
docker-compose ps postgres
|
||||
|
||||
# Check connection string
|
||||
echo $DATABASE_URL
|
||||
|
||||
# Verify credentials
|
||||
psql -h localhost -U postgres -d bete
|
||||
```
|
||||
|
||||
### Discord Gateway not receiving events
|
||||
```bash
|
||||
# Check Redis connection
|
||||
redis-cli ping
|
||||
|
||||
# Check Discord token
|
||||
echo $DISCORD_TOKEN
|
||||
|
||||
# View logs
|
||||
docker-compose logs discord-gateway
|
||||
```
|
||||
|
||||
### Frontend can't connect to Backend
|
||||
```bash
|
||||
# Check Backend is running
|
||||
curl http://localhost:3001/health
|
||||
|
||||
# Check WebSocket connection
|
||||
# Open browser DevTools → Network → WS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Documentation
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
GET /health
|
||||
```
|
||||
|
||||
### Messages
|
||||
```bash
|
||||
GET /api/messages?channel=<id>&type=text|image
|
||||
POST /api/messages (admin only)
|
||||
```
|
||||
|
||||
### Analytics
|
||||
```bash
|
||||
GET /api/analytics
|
||||
```
|
||||
|
||||
### Voice Recordings
|
||||
```bash
|
||||
GET /api/recordings
|
||||
```
|
||||
|
||||
### WebSocket Events
|
||||
```
|
||||
message_created
|
||||
message_updated
|
||||
message_deleted
|
||||
attachment_uploaded
|
||||
user_state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Create a feature branch
|
||||
2. Make changes following Modular MVC pattern
|
||||
3. Run tests and linting
|
||||
4. Submit PR with description
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user