Archive/documentation/ADMIN_PANEL.md

# Admin Panel Documentation

**Admin Panel** is a centralized management interface for all Habbo emulators and services running in the Habland environment. It provides unified control over multiple emulator instances, databases, and associated services.

## 🎯 Overview

The Admin Panel is a Next.js-based web application that integrates with Docker containers to provide real-time monitoring and management capabilities for:

- **Havana** (v31+ Transition Era emulator)
- **Kepler** (v14 Classic Shockwave emulator)
- **Roseau** (v1 Goldfish era emulator)
- **Arcturus Morningstar** (Modern emulator with extensive features)

## 🚀 Quick Start

### Accessing the Admin Panel

- **URL**: `http://localhost:3000` (or configured port)
- **Default Theme**: Orange (customizable via Settings)
- **Auto-Refresh**: Container status updates every 2 seconds

### Navigation

The sidebar provides access to all major sections:

- **Dashboard** - Container management and monitoring
- **Users** - User account management
- **Furni** - Furniture catalog management
- **Catalog** - In-game catalog configuration
- **Clothing** - Avatar clothing editor
- **Documentation** - Browse emulator documentation
- **Settings** - Theme and configuration
- **Health** - System health monitoring
- **Debug** - Development and debugging tools
- **Bulk Ops** - Bulk operations for data management
- **Backups** - Database backup and restore

---

## 📊 Dashboard (Container Manager)

The main page provides comprehensive container orchestration and monitoring.

### Features

#### Emulator Filter Buttons

Filter containers by emulator type and their dependencies:

- **All Containers** - Shows all running containers
- **Havana** - Havana server, Havana web client, unified-db, asset-server
- **Kepler** - Kepler server, Kepler client, unified-db, asset-server
- **Roseau** - Roseau server, Roseau client, unified-db, asset-server
- **Arcturus** - Arcturus emulator, AtomCMS, Nitro React, Cool UI, Redis, unified-db, asset-server

#### Start All Button

When an emulator filter is selected, a green "Start All" button appears that:
- Starts all stopped containers for that emulator group
- Executes starts sequentially with 500ms delay between each
- Shows "Starting..." state during operation
- Useful for quickly spinning up a complete emulator environment

#### Container Cards

Each container displays:

- **Status Badge** - Running (green) or Exited (red) with animated pulse
- **Container Image** - Visual representation of the service
- **Container Name** - Docker container identifier
- **Description** - Brief explanation of the container's purpose
- **Online Count** - Live player count for emulator servers (Havana, Kepler, Roseau)
- **Action Buttons**:
  - **Start** - Launch stopped container
  - **Restart** - Reboot running container
  - **Stop** - Shutdown running container
- **Press to view** - Click anywhere on the card to open detailed modal

#### Container Modal

Click any container card to open the detailed management modal with tabs:

##### Links Tab
- Quick access links to web interfaces
- Service-specific URLs (phpMyAdmin, Redis Commander, etc.)
- Documentation references

##### Notes Tab
- Add custom notes for each container
- Useful for configuration details, deployment notes, or troubleshooting tips
- Persisted across sessions

##### Secrets Tab
- Securely manage environment variables
- Store API keys, passwords, and configuration secrets
- **Warning**: Handle sensitive data carefully

##### Docs Tab
- Container-specific documentation
- For emulators: Full markdown documentation (Havana, Kepler, Roseau, Arcturus)
- External resource links (GitHub repos, official docs, wikis)

##### Controls Tab
- Advanced container operations
- Force restart, rebuild, update actions
- Container-specific management tools

##### Status Tab
- Detailed container status information
- Resource usage (CPU, memory, network)
- Container health checks
- Uptime statistics

##### Logs Tab
- Real-time container logs
- Last 100 log lines with auto-refresh
- Color-coded log levels
- Search and filter capabilities

### Online Stats Bar

Displays live player counts across all emulators:
- **Havana Online**: Current players on Havana server
- **Kepler Online**: Current players on Kepler server
- **Roseau Online**: Current players on Roseau server

---

## 👥 Users Management

Manage user accounts across all emulator databases.

### Features

#### Emulator Selection

Switch between emulator databases:
- **Havana** - Havana user database
- **Kepler** - Kepler user database
- **Roseau** - Roseau user database
- **Retro** (Arcturus) - Arcturus user database

#### User Table

Displays comprehensive user information:
- **Username** - User account name
- **Email** - Registered email address
- **Rank** - User permission level (1=User, 5=Moderator, 7=Admin)
- **Credits** - In-game currency balance
- **Last Online** - Timestamp of last login
- **Actions** - Edit, delete, manage user

#### Search & Filters

- **Search Bar** - Find users by username or email
- **Rank Filter** - Filter by permission level
- **Sort Options** - Sort by username, credits, last online
- **Pagination** - Navigate large user lists efficiently

#### User Actions

- **Add User** - Create new accounts with custom settings
- **Edit User** - Modify username, email, rank, credits
- **Delete User** - Remove user accounts (with confirmation)
- **Reset Password** - Generate new passwords for users
- **Grant Badges** - Award achievement badges
- **Manage Credits** - Add or remove in-game currency

---

## 🪑 Furni Management

Manage furniture items in the catalog across emulators.

### Features

#### Emulator Database Selection

Choose which emulator's furniture catalog to manage:
- **Havana** - Havana furniture database
- **Kepler** - Kepler furniture database
- **Roseau** - Roseau furniture database
- **Retro** - Arcturus furniture database

#### Furniture Table

Displays all furniture items with:
- **Item Name** - Furniture identifier
- **Public Name** - Display name shown to users
- **Type** - Floor item, wall item, effect, badge
- **Width/Length** - Furniture dimensions
- **Stack Height** - Stacking properties
- **Can Sit/Lay** - Interaction capabilities
- **Sprite ID** - Asset reference number

#### Furniture Operations

- **Add Furniture** - Import new items from catalog
- **Edit Item** - Modify properties (name, type, dimensions, interactions)
- **Delete Item** - Remove furniture from catalog
- **Bulk Import** - Upload CSV of furniture items
- **Export Catalog** - Download furniture database as CSV

#### Search & Filters

- **Search** - Find items by name or sprite ID
- **Type Filter** - Filter by furniture type
- **Interaction Filter** - Show only sittable/layable items
- **Category Filter** - Browse by catalog category

---

## 📦 Catalog Management

Configure in-game catalog pages and items.

### Features

#### Catalog Pages

Manage the hierarchical catalog structure:
- **Page Name** - Display name in catalog
- **Parent Page** - Nested catalog organization
- **Icon** - Catalog page icon
- **Visibility** - Public, VIP, or rank-restricted
- **Order** - Page display order

#### Catalog Items

Configure purchasable items:
- **Item Name** - Product name
- **Description** - Item description shown to users
- **Furniture Association** - Link to furniture database
- **Cost** - Credit price
- **Points Cost** - Alternative currency (diamonds, duckets)
- **Limit** - Purchase limits per user

#### Catalog Operations

- **Add Page** - Create new catalog category
- **Edit Page** - Modify page properties
- **Add Item** - Add products to catalog
- **Edit Item** - Update pricing and availability
- **Reorder** - Drag-and-drop page reorganization
- **Clone Page** - Duplicate catalog structure

---

## 👔 Clothing Editor

Manage avatar clothing and figure data.

### Features

#### Clothing Database

Browse and edit available clothing items:
- **Part Type** - Hair, shirt, pants, shoes, accessories
- **Figure ID** - Clothing identifier
- **Gender** - Male, female, or unisex
- **Club Level** - Free, VIP, or HC only
- **Color Palette** - Available color options

#### Figure Editor

Visual avatar builder:
- **Interactive Preview** - Real-time avatar rendering
- **Part Selection** - Choose clothing parts
- **Color Picker** - Customize colors
- **Figure String** - Generated figure code
- **Save Presets** - Store common outfits

#### Clothing Operations

- **Add Clothing** - Import new clothing items
- **Edit Item** - Modify properties and availability
- **Delete Item** - Remove from catalog
- **Bulk Import** - Upload clothing data
- **Export Database** - Download clothing catalog

---

## 📚 Documentation

Browse comprehensive documentation for all emulators and services.

### Features

#### Documentation Browser

Two-panel interface for efficient browsing:
- **Left Sidebar** - List of available documentation
- **Right Panel** - Rendered markdown content with syntax highlighting

#### Available Documentation

- **Havana Emulator** - v31+ Transition Era documentation
- **Kepler Emulator** - v14 Classic Shockwave documentation
- **Roseau Emulator** - v1 Goldfish era documentation
- **Arcturus Morningstar** - Modern emulator documentation
- **Admin Panel** - This documentation

#### Search Functionality

- **Real-time Search** - Filter docs by title, description, or content
- **Keyword Highlighting** - Search terms highlighted in results
- **Content Indexing** - Search within markdown content

#### Documentation Features

- **Markdown Rendering** - Full CommonMark support
- **Syntax Highlighting** - Code blocks with language detection
- **Table Support** - Formatted tables
- **Link Navigation** - Internal and external links
- **Responsive Design** - Mobile-friendly layout

---

## ⚙️ Settings

Customize the admin panel appearance and behavior.

### Theme Customization

#### Color Schemes

Choose from preset themes or create custom:
- **Orange** (Default) - Vibrant orange gradient
- **Purple** - Royal purple tones
- **Blue** - Cool blue palette
- **Green** - Fresh green theme
- **Pink** - Soft pink accents
- **Custom** - Define your own colors

#### Theme Settings

- **Primary Color** - Main accent color for buttons and highlights
- **Secondary Color** - Supporting color for UI elements
- **Accent Color** - Hover states and active elements
- **Gradient Start/End** - Gradient color definitions

#### Live Preview

- Real-time preview of theme changes
- Apply instantly without page reload
- CSS variable injection for smooth transitions

### Configuration Options

- **Auto-Refresh Interval** - Container status update frequency (default: 2s)
- **Log Tail Lines** - Number of log lines to display (default: 100)
- **Notification Preferences** - Container event notifications
- **Default Emulator** - Preferred emulator for multi-select pages

---

## 🏥 Health Monitoring

System health dashboard for monitoring infrastructure.

### Features

#### Container Health

Monitor the health of all Docker containers:
- **Health Status** - Healthy, unhealthy, or starting
- **Health Checks** - Last check timestamp and result
- **Restart Count** - Number of container restarts
- **Uptime** - Container running duration

#### Database Health

Monitor database connections and performance:
- **Connection Status** - Connected or disconnected
- **Active Connections** - Current database connections
- **Query Performance** - Average query execution time
- **Database Size** - Storage usage

#### System Resources

Overall system resource monitoring:
- **CPU Usage** - System and per-container CPU utilization
- **Memory Usage** - RAM consumption and available memory
- **Disk Usage** - Storage space utilization
- **Network I/O** - Bandwidth usage statistics

#### Alerts & Warnings

Automated health monitoring alerts:
- **Container Crashes** - Immediate notification of container failures
- **Resource Limits** - Warnings when approaching capacity
- **Database Issues** - Connection failures or slow queries
- **Service Degradation** - Performance below threshold

---

## 🔧 Debug Tools

Development and troubleshooting utilities.

### Features

#### Container Inspector

Deep dive into container internals:
- **Environment Variables** - View all container env vars
- **Volume Mounts** - Mounted directories and files
- **Network Settings** - IP addresses, ports, DNS
- **Running Processes** - Active processes inside container

#### Database Query Tool

Execute SQL queries against emulator databases:
- **Query Editor** - SQL syntax highlighting
- **Multi-Database** - Connect to any emulator database
- **Result Display** - Formatted table output
- **Export Results** - CSV, JSON export options
- **Query History** - Recent queries

#### API Testing

Test API endpoints:
- **Endpoint List** - All available API routes
- **Request Builder** - Construct API requests
- **Response Viewer** - Formatted JSON/XML responses
- **Authentication** - Test with auth tokens

#### Log Aggregation

Centralized log viewing:
- **All Containers** - Aggregated logs from all services
- **Filter by Level** - Error, warning, info, debug
- **Time Range** - Filter logs by timestamp
- **Export Logs** - Download log archives

---

## ⚡ Bulk Operations

Perform batch operations on data across emulators.

### Features

#### Emulator Selection

Choose target emulator database:
- **Havana** - Havana database
- **Kepler** - Kepler database
- **Roseau** - Roseau database
- **Retro** - Arcturus database

#### Operation Types

##### User Operations

- **Mass User Creation** - Bulk import users from CSV
- **Rank Updates** - Batch modify user ranks
- **Credit Distribution** - Add credits to multiple users
- **Badge Awards** - Grant badges to user groups
- **Account Deletion** - Bulk remove users

##### Furniture Operations

- **Catalog Import** - Bulk import furniture items
- **Price Updates** - Update pricing across catalog
- **Item Deletion** - Remove multiple items
- **Category Assignment** - Batch categorize items

##### Catalog Operations

- **Page Creation** - Generate multiple catalog pages
- **Item Association** - Link items to pages in bulk
- **Visibility Updates** - Modify page access in batch

#### Import/Export

- **CSV Import** - Upload structured data files
- **Excel Support** - Import .xlsx files
- **JSON Import** - Structured data import
- **Export Options** - Download data in multiple formats
- **Template Download** - Get import templates

#### Validation & Preview

- **Data Validation** - Check import data before commit
- **Preview Changes** - Review operations before execution
- **Error Reporting** - Detailed error messages
- **Rollback Support** - Undo bulk operations

---

## 💾 Backups

Database backup and restore functionality.

### Features

#### Backup Creation

Create database backups:
- **Select Database** - Choose emulator database to backup
- **Backup Name** - Custom backup identifier
- **Compression** - Gzip compression for storage efficiency
- **Scheduling** - Automated backup schedules

#### Backup Management

Manage existing backups:
- **Backup List** - All available backups with metadata
- **Backup Size** - Storage space used
- **Creation Date** - Backup timestamp
- **Database Version** - Schema version information

#### Restore Operations

Restore from backups:
- **Select Backup** - Choose backup to restore
- **Preview** - Review backup contents before restore
- **Restore Options** - Full or partial restore
- **Confirmation** - Multi-step confirmation for safety

#### Backup Features

- **Download Backup** - Export backup files locally
- **Delete Backup** - Remove old backups
- **Backup Verification** - Test backup integrity
- **Automated Retention** - Auto-delete old backups (configurable)

---

## 🔐 Security & Best Practices

### Access Control

- **Authentication** - Secure admin panel access (configure via environment)
- **Session Management** - Auto-logout after inactivity
- **Permission Levels** - Role-based access control

### Data Safety

- **Confirmation Dialogs** - Required for destructive operations
- **Backup Before Changes** - Automatic backups before bulk operations
- **Audit Logging** - Track all administrative actions
- **Version Control** - Database schema versioning

### Performance Optimization

- **Lazy Loading** - Components load on demand
- **Pagination** - Efficient data display for large datasets
- **Caching** - Smart caching to reduce database queries
- **Auto-Refresh** - Configurable intervals to balance freshness and load

---

## 🛠 Troubleshooting

### Common Issues

#### Container Won't Start

**Symptoms**: Container shows "Exited" status immediately after start attempt

**Solutions**:
1. Check container logs via the Logs tab in container modal
2. Verify database is running (unified-db container)
3. Check for port conflicts with other services
4. Review environment variables in Debug section

#### No Online Stats Showing

**Symptoms**: Online player counts show "—" instead of numbers

**Solutions**:
1. Verify emulator server is running
2. Check API endpoint `/api/stats` in Debug tools
3. Ensure database connection is healthy
4. Verify emulator is writing online user data

#### Bulk Operations Failing

**Symptoms**: CSV imports return errors or no data imported

**Solutions**:
1. Download CSV template from Bulk Ops page
2. Verify CSV format matches template exactly
3. Check for special characters or encoding issues
4. Review error messages for specific field issues

#### Theme Not Applying

**Symptoms**: Color changes in Settings don't take effect

**Solutions**:
1. Click "Save Theme" button after making changes
2. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
3. Clear browser cache
4. Check browser console for JavaScript errors

### Getting Help

- **Documentation Tab** - Search for specific topics
- **Container Logs** - Debug container-specific issues
- **Health Dashboard** - Check overall system health
- **Debug Tools** - Advanced troubleshooting utilities

---

## 📡 API Reference

The Admin Panel exposes several API endpoints for programmatic access:

### Container Management

- `GET /api/containers` - List all containers
- `POST /api/control` - Start/stop/restart containers
- `GET /api/containers/:id/logs` - Fetch container logs
- `GET /api/containers/:id/stats` - Container resource usage

### User Management

- `GET /api/users?emulator={name}` - List users
- `POST /api/users` - Create user
- `PUT /api/users/:id` - Update user
- `DELETE /api/users/:id` - Delete user

### Furniture & Catalog

- `GET /api/furni?emulator={name}` - List furniture
- `GET /api/catalog/items?emulator={name}` - Catalog items
- `GET /api/catalog/pages?emulator={name}` - Catalog pages

### System

- `GET /api/stats` - Online player statistics
- `GET /api/health` - System health status
- `GET /api/config` - Configuration settings
- `POST /api/settings` - Update settings

### Backups

- `GET /api/backups` - List backups
- `POST /api/backups` - Create backup
- `POST /api/backups/restore` - Restore backup
- `DELETE /api/backups/:id` - Delete backup

---

## 🚀 Advanced Features

### Docker Compose Integration

The Admin Panel integrates directly with Docker Compose:
- Real-time status monitoring via Docker API
- Container lifecycle management (start/stop/restart)
- Log streaming from containers
- Resource usage monitoring

### Multi-Database Support

Seamlessly switch between emulator databases:
- Unified connection pooling
- Database-specific optimizations
- Safe multi-tenant operations
- Isolated data management

### Theme System

Advanced theming with CSS variables:
- Live theme preview
- Persistent theme storage
- CSS variable injection
- Gradient customization

---

## 📝 Version Information

- **Admin Panel Version**: 1.1.0
- **Next.js Version**: 16.0.7
- **Node Version**: 20 LTS
- **Docker Integration**: Docker Engine API v1.41+

---

## 🤝 Support & Contribution

### Reporting Issues

Found a bug or have a feature request?
1. Check existing issues first
2. Provide detailed reproduction steps
3. Include browser/environment information
4. Attach relevant logs from Debug section

### Feature Requests

Suggest new features:
1. Describe the use case
2. Explain expected behavior
3. Provide mockups or examples if applicable

---

## 📚 Additional Resources

- **Havana Documentation**: See HAVANA.md
- **Kepler Documentation**: See KEPLER.md
- **Roseau Documentation**: See ROSEAU.md
- **Arcturus Documentation**: See ARCTURUS_RETRO.md
- **Docker Documentation**: https://docs.docker.com
- **Next.js Documentation**: https://nextjs.org/docs

---

**Last Updated**: December 2024
**Maintained By**: Habland Development Team