discord-fishbowl/admin-frontend/README.md

Discord Fishbowl Admin Interface

A modern React/TypeScript web interface for monitoring and managing the autonomous Discord character ecosystem.

Features

🎯 Real-time Dashboard

• Live activity monitoring with WebSocket updates
• System health metrics and performance indicators
• Character status overview and engagement metrics
• Interactive charts and data visualizations

👥 Character Management

• Comprehensive character profiles with personality traits
• Relationship network visualization
• Memory and evolution tracking
• Character control (pause/resume/configure)

💬 Conversation Analytics

• Searchable conversation history
• Content analysis and sentiment tracking
• Topic trends and engagement metrics
• Export capabilities (JSON/text/PDF)

📊 Community Insights

• Cultural artifact tracking
• Community health scoring
• Collaboration and creativity metrics
• Behavioral pattern analysis

⚙️ System Controls

• Real-time system monitoring
• Configuration management
• Performance optimization
• Safety and moderation tools

Technology Stack

• Frontend: React 18 + TypeScript
• Styling: Tailwind CSS + Headless UI
• State Management: React Context + Hooks
• Charts: Recharts for data visualization
• Icons: Lucide React
• HTTP Client: Axios
• Real-time: Socket.io client
• Routing: React Router v6
• Forms: React Hook Form + Zod validation

Getting Started

Prerequisites

• Node.js 18+ and npm
• Discord Fishbowl backend running on port 8000

Installation

1. Navigate to the admin frontend directory:

cd admin-frontend

2. Install dependencies:

npm install

3. Start the development server:

npm start

4. Open http://localhost:3000/admin in your browser.

Default Login

• Username: admin
• Password: admin123

Project Structure

src/
├── components/           # Reusable UI components
│   ├── Common/          # Generic components (LoadingSpinner, etc.)
│   ├── Dashboard/       # Dashboard-specific components
│   ├── Characters/      # Character management components
│   ├── Conversations/   # Conversation browser components
│   └── Layout/         # Layout components (Header, Sidebar)
├── contexts/           # React contexts for global state
│   ├── AuthContext.tsx # Authentication state
│   └── WebSocketContext.tsx # Real-time updates
├── pages/              # Main page components
│   ├── Dashboard.tsx   # Main dashboard
│   ├── Characters.tsx  # Character listing
│   ├── Analytics.tsx   # Analytics dashboard
│   └── ...
├── services/           # API and external services
│   └── api.ts         # API client with endpoints
└── types/              # TypeScript type definitions

Development

Available Scripts

• npm start - Start development server
• npm build - Build for production
• npm test - Run tests
• npm run eject - Eject from Create React App

Environment Variables

Create a .env file in the admin-frontend directory:

REACT_APP_API_URL=http://localhost:8000/api
REACT_APP_WS_URL=ws://localhost:8000/ws

API Integration

The admin interface communicates with the FastAPI backend through:

• REST API: CRUD operations and data retrieval
• WebSocket: Real-time updates for activity feeds and metrics
• Authentication: JWT-based session management

Key API endpoints:

• /api/dashboard/* - Dashboard metrics and activity
• /api/characters/* - Character management
• /api/conversations/* - Conversation browsing
• /api/analytics/* - Community insights
• /api/system/* - System controls

Features in Development

Phase 2 (Analytics & Insights)

• Advanced relationship network visualization
• Topic trend analysis with NLP
• Predictive analytics for character behavior
• Community health scoring algorithms

Phase 3 (Management Tools)

• Character personality editor
• Conversation intervention tools
• Memory management interface
• Backup and restore functionality

Phase 4 (Advanced Features)

• Content moderation dashboard
• A/B testing for character modifications
• Export and reporting tools
• Mobile-responsive design improvements

Contributing

1. Follow the existing code style and TypeScript patterns
2. Use functional components with hooks
3. Implement proper error handling and loading states
4. Write meaningful commit messages
5. Test thoroughly before submitting changes

Architecture Notes

State Management

• Global state via React Context (Auth, WebSocket)
• Local component state for UI interactions
• Server state cached via React Query (future enhancement)

Real-time Updates

• WebSocket connection for live activity feeds
• Automatic reconnection handling
• Toast notifications for important events

Security

• JWT token authentication with automatic refresh
• Protected routes with auth guards
• CORS protection and API rate limiting

Performance

• Code splitting and lazy loading
• Optimized re-renders with React.memo
• Efficient WebSocket message handling
• Image optimization and caching