World of Warcraft Guild Management Application

A modern, responsive web application for managing and displaying World of Warcraft guild information, raid progression, and player statistics.

Version 3.2 — Enrichment UI, Admin SEO & Dashboard Command Center 🆕

Database-managed guild ranks

Guild rank labels (GUILLD_RANKS) are read from AppSettings via /api/config across audit tables, top-player lists, and the API now returns guildRankLabel on each character
Settings panel: edit rank names by Battle.net index (one name per line)

Admin SEO & page titles

New Site & SEO section in Settings: site name, short name, meta description, keywords, OG/Twitter image URLs
Root layout loads metadata dynamically from the database (generateMetadata + buildMetadataFromConfig)
Character pages use configurable site name in titles

Audit workspace tabs

Top-level tabs: Analytics, All Players, Missing Enchants, Lockouts (with Normal/Heroic/Mythic sub-tabs)
Shared filter bar across all audit views

Dashboard command center

Animated metric cards, role composition pulse chart, and Spotlight character cards with full-body Battle.net renders
Guild Conquest rankings integrated; no longer a duplicate of the audit roster

Mythic+ & rankings data

Raider.io Rankings tab powered by /api/rankings enrichment (works when seasonal cache is empty)
Statistics tab from live roster + Battle.net M+ data
Optional Season Cache tab when legacy seasonal stats exist

Character profiles

Full-width hero banner with main-raw character render, inset portrait, enrichment scores, and quick stat grid

Version 3.1 — Midnight Expansion & Setup Overhaul 🆕

Multi-Raid Lockout Tracking

The frontend now fully supports tracking multiple raids within the current expansion simultaneously. All data is pulled dynamically from the new lockStatus.raids structure returned by the API.

Audit Table — "Raid Locks" Column

The old single-string "locked" column is replaced with colour-coded difficulty badges per raid instance (e.g. N 6/6, H 4/6 in Normal green / Heroic blue / Mythic purple)
Hovering a badge reveals a tooltip listing every locked boss name for that raid and difficulty
Falls back gracefully to the legacy lockStatus.lockedTo string for characters that haven't been re-synced yet

Audit Analytics Dashboard

"Raid Lockout Status" section now shows a per-raid breakdown below the donut chart
Each active raid (Voidspire, Dreamrift, etc.) gets its own card with a total locked count and per-difficulty mini-bars
Fully dynamic — no raid names are hardcoded

Member Profile — Raid Overview Card

New "[Expansion] — Raid Progress" card on the character detail page
Shows every raid in the current expansion with progress bars for LFR / Normal / Heroic / Mythic
Colour-coded fills (green → Normal, blue → Heroic, purple → Mythic, grey → LFR)
Hover a progress bar to see the list of killed bosses

Upgrade Page (`/upgrade`)

New admin-only UI for running database migrations after an update:

Admin login form (Basic Auth stored in sessionStorage)
Migration status overview — total, pending, and up-to-date counts
Per-migration cards with name, description, status badge, and a Run button
Run All Pending button for one-click bulk migration
Real-time result output per migration with success / failure messaging
Link to the install page for monitoring background jobs

Setup Wizard Redesign (`/install`)

The install page has been completely redesigned to match the application's dark card-based design system:

Loading screen — centred logo + subtle spinner instead of a bare spinner
Login gate — isolated full-page layout with a centred card, logo lockup, and "Reset the database" inline link
Step indicator — numbered circles above step labels connected by animated lines; completed steps show a check icon with a primary glow
Sectioned settings form — settings are now grouped into logical cards (API Access, Guild Identity, Season & Content, Item Level Requirements, Roles & Gear Checks, Guild Ranks) each with a header band and description
Fetch step — clean card with a labelled progress bar and compact 5-character preview strip; the "Start Guild Sync" state uses a proper call-to-action card
Admin step — tighter inline password validation with a collapsible requirements list
All dialogs (overwrite, reset) restyled to match the app's rounded-xl border-border/50 bg-card aesthetic

Config Key Migration

CURRENT_RAID renamed to CURRENT_EXPANSION in app.config.js and all UI forms
Settings page falls back to settings.CURRENT_RAID for existing installations without requiring a forced upgrade

Version 3.0 — The Visual Overhaul 🆕

Version 3.0 is a complete redesign of the entire application. Every screen, component, and interaction has been revisited with a focus on clarity, consistency, and character. The application now feels like a proper dashboard product rather than a stitched-together set of pages.

The Big Picture

Full Midnight expansion support — data, UI, and configuration are all updated to reflect the current WoW season
Brand new design system — replaced the old MUI component library with shadcn/ui, giving the application a clean, unified dark theme that actually looks good
Charts and analytics everywhere — key screens now visualise data with proper interactive charts rather than raw numbers in tables
Character names always capitalised and class-coloured — every character name across every screen now follows WoW conventions: Knories in Paladin pink, Addnio in Warrior tan, etc.
No more hardcoded colours — every colour token is now drawn from the design system, so it all adapts consistently

What Changed Per Screen

Navigation

Completely rebuilt sidebar — tighter spacing, uppercase section labels, proper active/hover states with distinct visual weight
Slim sticky header bar replaces the old tall toolbar
Settings login dialog polished to match the rest of the UI

Dashboard

Stat cards now have subtle inner gradients and icon badges with coloured backgrounds
Top Players tables show capitalised, class-coloured names consistently
Layout cleaned up with proper spacing and section headings

Audit

Filters redesigned as a clean 4-column grid (item level slider, rank, role, class badges)
New analytics panel added above the roster table showing live charts that update as you filter:
- Role distribution (tanks / healers / DPS) — donut chart with progress bars
- Enchant readiness — how many players are fully enchanted vs. missing enchants
- Raid lockout status — available vs. locked, broken down visually
- Class distribution — bar chart in WoW class colours with a pill grid below
- Raid buff coverage — compact grid showing which buffs you have and which are missing
Tab bar redesigned — no longer stretches full width with an ugly scrollbar
Table header typography cleaned up

Mythic+

Fixed a crash on the M+ screen (missing import)
Screen wrapper markup cleaned up — removed legacy class-based divs
Tabs now use the new compact pill style

Member Profile

Fully redesigned — hero card shows avatar with class-coloured border, stat pills, and an equipment status strip (enchants / tier set / active)
Most Played With section shows clean compact cards
Dungeon Performance table uses proper muted colour tokens

Seasons / Sign-Up

Header repositioned with the sign-up button inline on desktop
New stats dashboard above the roster table:
- Season Goals — donut chart showing CE / AOTC / Social split with progress bars
- Role Distribution — donut chart + per-role progress bars with backup counts
- Class Distribution — bar chart in class colours + compact class pill grid
- Mythic+ Interest — who wants to push keys vs. who doesn't, with visual progress bars
- Raid Buffs — which buffs the signed-up roster covers, which are missing
Roster table redesigned with role badges (green/blue/red), goal badges (CE=gold, AOTC=purple), and class-coloured names
Sign-up success toast replaced the old ugly alert box

Recruitment / Join

Hero section redesigned with a soft gradient background and coloured badge pills
Content cards now have accent-coloured borders and icon badges matching the card type (requirements=amber, benefits=yellow, schedule=purple, contact=primary)
List items use arrow icons in the accent colour instead of plain text bullets
Removed hardcoded glassmorphism effects that didn't fit the design system

Roster Display

Role section headers now have coloured icon badges (emerald for tanks, blue for healers, red for DPS, etc.)
Wider grid, total player count shown in the subtitle
Error state uses proper styled card

Character Cards

Shows spec + class together, not just class
Cleaner hover transition
Better text truncation on narrow cards

Global Improvements

Thin custom scrollbar across the whole app — replaces the browser default with a 5px scrollbar that suits the dark theme
Tighter base font size — dropped from 16px to 15px for a more refined feel
All headings get tracking-tight by default
All #111111, #B0C4DE, #FFD700 hardcoded hex colours replaced with proper design tokens

Version 2.2 Changelog

Roster Builder Admin System

Admin-Based Roster Management: Roster builder is now restricted to admin users only
New Admin Roster Builder Page:
- Located at /settings/roster-builder (admin-only, requires authentication)
- 3-column layout with drag-and-drop functionality
- Search functionality to find characters
- Real-time roster buff calculations
- Character cards with role-based organization
Public Roster Display:
- /roster page remains public (read-only)
- Displays saved roster configurations
- Shows character details and raid composition
Enhanced Roster Features:
- Drag and drop characters between roles (Tanks, Healers, DPS, Substitutes, Socials)
- Remove characters from roster
- Save roster configurations to database
- Buff summary calculations
- Character filtering and search
Security Improvements:
- Admin authentication required for roster modifications
- Protected routes for roster builder
- Secure API endpoints for saving/deleting roster data

New Pages & Routes

/settings/roster-builder - Admin roster builder page (admin only)
- Full drag-and-drop roster management
- Character search and filtering
- Buff calculations and summaries
- Save/load roster configurations

API Routes

GET /api/roster - Get current roster (public, read-only)
POST /api/roster - Save roster configuration (admin only, requires Basic Auth)
DELETE /api/roster/:characterId - Remove character from roster (admin only, requires Basic Auth)

Version 2.1 Changelog 🆕

Season Signup System Improvements

Renamed Routes: Updated all routes from /season3 to /seasons for better generic naming
Dynamic Season Management:
- Season title now configurable in admin settings (SEASON_TITLE)
- All season-related text is editable from admin panel
- Season alert popup is fully configurable (toggle, title, message)
Test/Demo Character Filtering: Added validation to prevent test/demo characters from being submitted
- Form validation before submission
- API route validation
- Backend validation (three-layer protection)
Component Renaming:
- Season3Stats → SeasonsStats
- Season3SignUp → SeasonsSignUp
- Season3GoalsSection → SeasonsGoalsSection
- Season3RosterTable → SeasonsRosterTable
Field Name Updates: Support for both old (season3CharacterName, season3Goal) and new (seasonCharacterName, seasonGoal) field names
Data Flow Improvements:
- Removed caching to ensure live data display
- Auto-refresh after successful signup
- Improved data retrieval from backend

New Settings Options

Season Page Settings:
- SEASON_PAGE_TITLE - Main title on seasons page
- SEASON_PAGE_DESCRIPTION - Description text (with show/hide toggle)
- SEASON_PAGE_DESCRIPTION_ENABLED - Toggle to show/hide description
- SEASON_SIGNUP_BUTTON_TEXT - Text on signup button
- SEASON_SIGNUP_SUCCESS_MESSAGE - Success message after signup
- SEASON_ROSTER_TABLE_TITLE - Roster table title
- SEASON_ROSTER_TABLE_DESCRIPTION - Roster table description
Season Alert Settings (existing, enhanced):
- SEASON_ALERT_ENABLED - Toggle to show/hide alert
- SEASON_ALERT_TITLE - Alert popup title
- SEASON_ALERT_MESSAGE - Alert popup message

New Pages & Routes

/seasons - Season signup page (renamed from /season3)
/settings/season-signups - Admin panel for managing season signups
- View all signups in a table
- Search functionality
- Delete signups
- Displays both old and new field names

API Routes

GET /api/seasons/data - Fetch season signups (renamed from /api/season3/data)
POST /api/seasons/signup - Submit season signup (renamed from /api/season3/signup)
GET /api/season-signups - Get all signups for admin (existing)
DELETE /api/season-signups/:id - Delete a signup (existing)

Version 2.0 Changelog

Major Features

Dynamic Recruitment/Join Page System: Fully customizable guild recruitment page with block-based content management
Admin Settings Management: New protected /settings route for comprehensive app configuration
Admin Authentication System: Secure authentication required for install and settings pages
Database Reset Functionality: Ability to reset database collections while preserving critical settings
Enhanced Security: Protected routes with admin-only access for sensitive operations

New Pages & Routes

/join - Public guild recruitment page
- Dynamic hero section with customizable title, subtitle, and badges
- Flexible section-based layout with block components
- Responsive design with modern glassmorphism effects
- Real-time content updates from database
/settings - Admin settings management page (protected)
- View and edit app configuration
- Protected fields (Guild Name, Realm, API Key) - view only or hidden
- Editable fields for all other settings
- Database reset functionality
/settings/join - Join page content editor (protected)
- Edit hero section (title, subtitle, badges)
- Manage content sections with drag-and-drop ordering
- Add/edit/remove content blocks (text, list, contact)
- Real-time preview of changes
- Seed database with example content
/settings/errors - Error management (moved from /errors, now protected)
- All error management features now require admin authentication
- Same functionality as before, but secured behind admin login

Installation & Setup Improvements

Guided Installation Process: Step-by-step installation wizard at /install
- App Settings configuration with Battle.net API validation
- Automatic guild data fetching with real-time progress
- Admin account creation with password strength requirements
Protected Install Page: Once admin account exists, install page requires authentication
Settings Management: Post-installation configuration changes through protected settings page

New API Routes

GET /api/jointext - Get join page content (public)
PUT /api/jointext - Update join page content (admin only)
POST /api/jointext/seed - Seed database with example join content (admin only)
POST /api/install/login - Admin authentication for protected routes
GET /api/settings - Get app settings (admin only, includes sensitive data)
PUT /api/settings - Update app settings (admin only, protected fields excluded)
POST /api/reset - Reset database collections (admin only)
GET /api/reset/info - Get information about what will be reset

Security Enhancements

Session-based Authentication: Secure admin authentication using sessionStorage
Protected Routes: All settings and error management routes require admin login
Field Protection: Critical settings (Guild Name, Realm, API Key) cannot be changed after initial setup
Audit Logging: Admin actions logged for security monitoring

Configuration Management

Centralized Settings: All app configuration managed through database
Protected Fields: Guild name, realm, and API credentials protected from modification
Flexible Updates: Most settings can be updated without full reinstallation
Settings Validation: Real-time validation of Battle.net API credentials

Dynamic Recruitment System

Hero Section Customization: Edit title, subtitle, and colored badges from admin panel
Section-Based Layout: Organize content into logical sections with flexible block positioning
Block Types:
- Text Blocks: Rich text content with title
- List Blocks: Bullet-pointed lists for requirements, benefits, schedules
- Contact Blocks: Discord and email contact information with clickable links
Layout Options: Each block can be positioned as full-width, left-half, or right-half
Visual Design:
- Modern glassmorphism effects with backdrop blur
- Card-based layout with colored left borders (requirements=red, benefits=green, etc.)
- Icon badges for each card type
- Hover animations and glow effects
- Responsive design for mobile, tablet, and desktop
Content Management:
- Add/remove/reorder sections and blocks
- Real-time preview in admin panel
- Database seeding with example content
- No-cache fetching ensures fresh content
Database Structure: All content stored in MongoDB jointext collection with section/block hierarchy

Version 1.5.0 Changelog

New Features

Comprehensive Seasonal Statistics System: Complete Mythic+ seasonal data processing and analysis
Individual Character Profiles: New detailed character pages with seasonal statistics and performance tracking
Enhanced Mythic+ Overview: Redesigned with tabbed interface including Weekly Recap, Leaderboard, and Statistics
Seasonal Leaderboards: Player, dungeon, and role-based rankings with real-time data
Character Detail Pages: Individual character profiles with seasonal performance, team play history, and dungeon statistics
Advanced Data Visualization: Enhanced charts and statistics for better guild insights

New Pages & Components

Individual Character Pages: /member/[realm]/[character] - Detailed character profiles with seasonal statistics
Enhanced Mythic+ Page: Redesigned with three tabs (Weekly Recap, Leaderboard, Statistics)
SeasonalStatistics Component: Comprehensive seasonal data visualization
SeasonalLeaderboard Component: Interactive leaderboards with filtering and sorting
MemberDetail Screen: Complete character profile with gear, stats, and seasonal performance

New API Routes

GET /api/seasonal-stats - Fetch latest seasonal statistics
GET /api/seasonal-stats/character/[realm]/[character] - Get character seasonal statistics
GET /api/seasonal-stats/leaderboard - Get seasonal leaderboards (players, dungeons, roles)

Enhanced Data Features

Seasonal Performance Tracking: Detailed analysis of Mythic+ runs, completion rates, and team compositions
Character Activity Detection: Smart detection of character activity since season start
Team Play Analysis: Track which players run together most frequently
Dungeon Performance: Individual dungeon statistics with highest keys and completion rates
Role-Based Statistics: Tank, healer, and DPS performance analysis

📄 License

This project is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0).

What this means:

✅ You can share and redistribute the material in any medium or format
✅ You must give appropriate credit to the original author
❌ You may not use the material for commercial purposes
❌ You may not distribute modified versions of the material

For full license details, visit: https://creativecommons.org/licenses/by-nc-nd/4.0/

🖼️ Screenshots

Version 2.0 Screenshots 🆕

The new Admin Settings page allows comprehensive configuration management with protected fields and database reset functionality.

The guided installation process walks you through app configuration, guild data fetching, and admin account creation.

Real-time progress updates during guild data fetching with character cards and detailed statistics.

Previous Versions

Dashboard

The Dashboard provides a comprehensive overview of your guild, including member statistics, top PvE and PvP performers, role distribution charts, missing enchants, and recent activity. It serves as the main landing page for quick insights into guild health and progression.

Roster Builder

The admin roster builder interface with drag-and-drop functionality for organizing raid compositions.

The public roster display page showing the saved roster configuration in read-only mode.

The Roster Builder is an interactive admin tool for planning raid compositions. Located at /settings/roster-builder (admin only), it allows raid leaders to drag and drop characters into raid slots, filter by role or class, and optimize their team for upcoming encounters. The public /roster page displays the saved roster configuration in read-only mode. This tool helps raid leaders organize and balance their groups efficiently.

Audit

The Audit page offers detailed analysis of each guild member's character, including gear, missing enchants, item level, and raid lockout status. Use this section to identify areas for improvement and ensure your team is raid-ready.

Mythic+ Overview

The Mythic+ Overview has been completely redesigned with a tabbed interface featuring three main sections:

Weekly Recap Tab

Displays current guild M+ activity, player scores, and recent achievements. Shows top performers and tracks overall Mythic+ activity.

Leaderboard Tab

Interactive leaderboards with multiple ranking types:

Player Rankings: Based on completion rate, total score, and highest key
Dungeon Rankings: Performance across different dungeons
Role Rankings: Tank, healer, and DPS performance comparisons

Statistics Tab

Comprehensive seasonal statistics including:

Guild participation rates
Total runs and completion statistics
Key achievements and milestones
Role distribution and performance metrics

Individual Character Profiles

New detailed character profile pages (/member/[realm]/[character]) featuring:

Character Overview

Character avatar and basic information
Current Mythic+ rating and item level
Class, spec, and realm information
Equipment status and readiness indicators

Seasonal Performance

Detailed seasonal statistics
Highest timed and overall keys
Total runs and completion rates
Team play history and most-played-with members

Dungeon Performance

Individual dungeon statistics
Highest keys per dungeon
Completion rates and average ratings
Performance trends and improvements

Equipment Analysis

Gear status and enchantment tracking
Tier set detection
Raid readiness indicators
Missing enchantments and improvements

Season 3 Signup

The Season 3 Signup page allows members to register their interest and goals for the upcoming season. Collect information on returning players, preferred roles, and personal objectives to streamline roster planning.

The errors screen allows you to gather insight on what is happening in the application, for example if you hit rate limits, characters are not found or the service goes down.

UI/Design Example

🔧 Environment Variables

Create a .env.local file in the root directory with the following variables:

# Backend API Configuration
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_CLIENT_BACKEND_URL=http://localhost:8000

# Guild Information
NEXT_PUBLIC_GUILD_NAME=Your Guild Name
NEXT_PUBLIC_GUILD_REALM=Your Realm Name

# Application URLs
NEXT_PUBLIC_BASE_URL=https://your-domain.com
NEXT_PUBLIC_APP_URL=https://your-domain.com

Environment Variables Explained

Variable	Description	Required
`NEXT_PUBLIC_BACKEND_URL`	URL of your backend API server	✅
`NEXT_PUBLIC_CLIENT_BACKEND_URL`	Client-side backend URL (fallback)	✅
`NEXT_PUBLIC_GUILD_NAME`	Your guild's name for display	✅
`NEXT_PUBLIC_GUILD_REALM`	Your guild's realm name	✅
`NEXT_PUBLIC_BASE_URL`	Your application's base URL for SEO	✅
`NEXT_PUBLIC_APP_URL`	Your application's URL for API calls	✅

⚙️ Application Configuration

Installation-Based Configuration (v2.0+)

Starting with version 2.0, application configuration is primarily managed through the database via the installation wizard. The app.config.js file serves as a fallback and default values source.

Configuration Flow:

Initial Setup: Use /install page to configure all settings
Database Storage: Settings are saved to MongoDB AppSettings collection
Runtime Loading: Application loads settings from database at runtime
Fallback: If database settings don't exist, falls back to app.config.js defaults

Updating Configuration:

Most Settings: Update via /settings page (admin login required)
Protected Settings: Guild Name, Realm, API Key can only be changed via /install page
Database Reset: Use /settings → Reset Database to start fresh

Legacy Configuration (app.config.js)

The app.config.js file still exists for reference and fallback purposes:

Guild Settings

{
  "GUILD_NAME": "Your Guild Name",
  "GUILD_REALM": "Your Realm",
  "REGION": "eu",
  "LEVEL_REQUIREMENT": 80,
  "ITEM_LEVEL_REQUIREMENT": 450,
  "MIN_CHECK_CAP": 450,
  "MAX_CHECK_CAP": 720,
  "MIN_TIER_ITEMLEVEL": 640
}

Role Definitions

{
  "TANKS": ["Blood", "Vengeance", "Guardian", "Brewmaster", "Protection"],
  "HEALERS": ["Preservation", "Mistweaver", "Holy", "Discipline", "Restoration"],
  "MAIN_RANKS": [0,1,2,3,4,5,6,7],
  "ALT_RANKS": [8,9,10]
}

Guild Ranks

{
  "GUILLD_RANKS": [
    "Guild Lead",
    "Officer", 
    "Officer Alt",
    "Raider",
    "Trial Raider",
    "Member",
    "Alt",
    "New Recruit"
  ]
}

Navigation Configuration

{
  "NAVIGATION": {
    "OVERVIEW": {
      "label": "OVERVIEW",
      "items": [
        {
          "label": "DASHBOARD",
          "path": "/",
          "icon": "DashboardIcon"
        },
        {
          "label": "RECRUITMENT",
          "path": "/join",
          "icon": "HowToRegIcon"
        },
        {
          "label": "AUDIT",
          "path": "/audit",
          "icon": "AssessmentIcon"
        },
        {
          "label": "ERRORS",
          "path": "/errors",
          "icon": "BugReportIcon"
        }
      ]
    },
    "SEASON3": {
      "label": "SEASON 3",
      "items": [
        {
          "label": "MYTHIC PLUS",
          "path": "/mythic-plus",
          "icon": "StarIcon"
        },
        {
          "label": "PVP",
          "path": "/rated-pvp",
          "icon": "EmojiEventsIcon"
        },
        {
          "label": "SIGN UP",
          "path": "/season3",
          "icon": "HowToRegIcon"
        }
      ]
    },
    "TOOLS": {
      "label": "TOOLS",
      "items": [
        {
          "label": "ROSTER BUILDER",
          "path": "/roster",
          "icon": "GroupAddIcon"
        }
      ]
    }
  }
}

Available Icons

The following Material-UI icons are available for navigation items:

DashboardIcon - Dashboard/home icon
AssessmentIcon - Assessment/audit icon
StarIcon - Star icon for Mythic+ features
EmojiEventsIcon - Trophy icon for PvP features
GroupAddIcon - Group/add icon for roster tools
HowToRegIcon - Registration/signup icon
BugReportIcon - Bug report icon for error management
PrecisionManufacturingIcon - Tools/manufacturing icon

🚀 Key Features

Real-time Data Updates

10-minute cache revalidation
Server-side data fetching
Optimistic UI updates

Responsive Design

Mobile-first approach
Material-UI components
Custom SCSS styling

Performance Optimizations

Next.js App Router
Server-side rendering
Image optimization
Code splitting

Accessibility

ARIA labels
Keyboard navigation
Screen reader support
High contrast mode

Theme & Screen System

Flexible theme system with direct imports for optimal performance
Easy customization without lazy loading overhead
Theme-aware component selection
Consistent patterns across themes

🏗️ Architecture Overview

This is a Next.js 14 frontend application that serves as a comprehensive guild management dashboard. It connects to a separate backend API to fetch guild data, player statistics, and raid progression information.

Backend API

The backend API server for this application can be found at: https://github.com/thedanzor/world-of-warcraft-api

The backend is an Express.js API server that:

Fetches guild data from the Battle.net API
Processes character information, gear, and statistics
Provides real-time data updates via WebSocket
Manages MongoDB data storage
Handles authentication and rate limiting
Supports both Retail and Classic WoW guilds

Tech Stack

Framework: Next.js 14 (App Router)
UI Library: Material-UI (MUI) v5
Styling: SCSS + Tailwind CSS
State Management: React Hooks
Charts: Recharts
Drag & Drop: React DnD
Fonts: Google Fonts (Poppins, Public Sans)

🗂️ Routes & Features

Main Pages

`/` - Dashboard

Purpose: Main guild overview and statistics
Features:
- Guild member overview
- Top players (PvE/PvP)
- Role distribution charts
- Missing enchants statistics
- Recent activity feed
Data: Fetches comprehensive guild data with statistics

`/roster` - Roster Display

Purpose: Public view of saved raid roster (read-only)
Features:
- Display saved roster configurations
- View character assignments by role
- See raid composition and buff summaries
- Character details and statistics
Data: Saved roster from database with full guild member details
Note: Roster editing is now available at /settings/roster-builder (admin only)

`/settings/roster-builder` - Roster Builder (Admin Only) 🆕 NEW v2.2

Purpose: Interactive raid roster planning and management
Features:
- Drag & drop character assignment between roles
- Role-based filtering (Tanks, Healers, DPS, Substitutes, Socials)
- Character search functionality
- Raid composition optimization
- Real-time buff calculations
- Save/load roster configurations to database
- Remove characters from roster
Data: Full guild member list with roles and specs
Access: Requires admin authentication

`/audit` - Guild Audit

Purpose: Detailed guild member analysis
Features:
- Character gear analysis
- Missing enchants tracking
- Item level requirements
- Raid lockout status
- Performance metrics
Data: Detailed character data with gear analysis

`/mythic-plus` - Mythic+ Overview

Purpose: Comprehensive Mythic+ dungeon progression tracking with seasonal statistics
Features:
- Weekly Recap Tab: Current guild M+ activity and player scores
- Leaderboard Tab: Interactive rankings for players, dungeons, and roles
- Statistics Tab: Comprehensive seasonal statistics and achievements
- Player M+ scores and progression tracking
- Seasonal performance analysis
Data: M+ specific data with seasonal statistics and leaderboards

`/rated-pvp` - PvP Overview

Purpose: Rated PvP player tracking
Features:
- Arena ratings
- RBG ratings
- Top PvP performers
- Season progression
Data: PvP specific data filtered from guild roster

`/season3` - Season 3 Planning

Purpose: Season 3 preparation and signup
Features:
- Season 3 signup forms
- Character planning tools
- Goal setting
- Returning player tracking
Data: Season 3 specific data and signups

`/mrt` - MRT Integration

Purpose: Method Raid Tools integration
Features:
- MRT note import/export
- Raid composition tools
- Character note management
Data: MRT compatible data structures

`/member/[realm]/[character]` - Individual Character Profiles 🆕 NEW v1.5.0

Purpose: Detailed character profiles with seasonal statistics and performance tracking
Features:
- Character Overview: Avatar, basic info, current rating, and equipment status
- Seasonal Performance: Detailed M+ statistics, highest keys, and completion rates
- Team Play Analysis: Most-played-with members and team composition history
- Dungeon Performance: Individual dungeon statistics and performance trends
- Equipment Analysis: Gear status, enchantments, tier sets, and raid readiness
- Activity Tracking: Season activity detection and performance metrics
Data: Complete character data with seasonal statistics and team play analysis

`/join` - Guild Recruitment 🆕 ENHANCED in v2.0

Purpose: Dynamic, fully customizable guild recruitment page
Features:
- Customizable Hero Section: Editable title, subtitle, and colored badges (gold/blue/green)
- Section-Based Layout: Organize content into logical sections
- Flexible Block System: Three block types for different content needs
  - Text Blocks: Rich text content with titles
  - List Blocks: Bullet-pointed lists for requirements, benefits, schedules
  - Contact Blocks: Discord and email links with clickable buttons
- Layout Control: Position each block as full-width, left-half, or right-half
- Modern Design: Glassmorphism effects, hover animations, colored borders by type
- Responsive: Fully responsive design for mobile, tablet, and desktop
- Icon Badges: Automatic icon assignment based on content type (requirements, benefits, etc.)
Data: Dynamic content from MongoDB jointext collection
Admin Panel: Content fully editable via /settings/join (admin only)
Example Content: Includes seeded example content on installation

`/settings` - Admin Settings Management 🆕 NEW v2.0

Purpose: Comprehensive app configuration and management (admin only)
Features:
- View and edit app settings (most fields editable)
- Protected fields: Guild Name, Realm, API Key (view only or hidden)
- Database reset functionality
- Real-time settings validation
- Secure admin authentication required
Data: App configuration from database
Access: Requires admin login

`/settings/errors` - Error Management 🆕 MOVED in v2.0

Purpose: Monitor and manage application errors (admin only)
Features:
- Error statistics dashboard
- Advanced filtering (type, endpoint, severity, resolution status)
- Error resolution tracking
- Bulk error deletion
- Detailed error views with stack traces
- Real-time error monitoring
Data: Error logs and statistics from backend API
Access: Requires admin login (moved from /errors)

API Routes

Data Endpoints

GET /api/data - Filtered and paginated guild data
GET /api/health - Backend health check
GET /api/status - Backend status information

Statistics Endpoints

GET /api/stats/missing-enchants - Missing enchants statistics
GET /api/stats/top-pvp - Top PvP players
GET /api/stats/top-pve - Top PvE players
GET /api/stats/role-counts - Role distribution counts

Seasonal Statistics Endpoints 🆕 NEW v1.5.0

GET /api/seasonal-stats - Fetch latest seasonal statistics
GET /api/seasonal-stats/character/[realm]/[character] - Get character seasonal statistics
GET /api/seasonal-stats/leaderboard - Get seasonal leaderboards (players, dungeons, roles)

Season 3 Endpoints

GET /api/season3/data - Season 3 data
POST /api/season3/signup - Season 3 signup
GET /api/season3/test - Season 3 endpoint testing

Error Management Endpoints

GET /api/errors - Fetch errors with filtering options
GET /api/errors/stats - Get error statistics
GET /api/errors/[id] - Get specific error details
PUT /api/errors/[id]/resolve - Mark error as resolved
DELETE /api/errors/[id] - Delete specific error
DELETE /api/errors - Bulk delete errors (with filters)

Join/Recruitment Content Endpoints 🆕 NEW v2.0

GET /api/jointext - Get join page content (public)
PUT /api/jointext - Update join page content (admin only)
POST /api/jointext/seed - Seed database with example join content (admin only)

Admin & Settings Endpoints 🆕 NEW v2.0

POST /api/install/login - Admin authentication
GET /api/settings - Get app settings (admin only)
PUT /api/settings - Update app settings (admin only)
POST /api/reset - Reset database collections (admin only)
GET /api/reset/info - Get reset information

Roster Management Endpoints 🆕 NEW v2.2

GET /api/roster - Get current roster (public, read-only)
POST /api/roster - Save roster configuration (admin only, requires Basic Auth)
DELETE /api/roster/:characterId - Remove character from roster (admin only, requires Basic Auth)

Installation Endpoints 🆕 NEW v2.0

GET /api/install - Check installation status
POST /api/install - Save app settings (with validation)
POST /api/install/admin - Create admin account

Utility Endpoints

GET /api/test-connection - Backend connectivity testing
POST /api/update - Trigger data updates

🎨 Theme & Screen System

The application uses a flexible theme and screen system that allows for easy customization while maintaining clean separation of concerns. This system makes it simple to create multiple visual themes and track changes across different versions of the application.

System Overview

The theme system consists of two main parts:

Themes - Visual styling and layout configurations
Screens - Page-specific components that adapt to the current theme

Directory Structure

core/
├── themes/                    # Theme definitions
│   ├── default/              # Default theme (currently active)
│   │   ├── index.jsx         # Theme provider and configuration
│   │   ├── base.scss         # Base styling variables
│   │   └── config.js         # Theme configuration
│   └── _add_your_own_/       # Template for custom themes
├── screens/                   # Screen components
│   ├── default/              # Default screen implementations
│   │   ├── dashboard.jsx     # Dashboard screen
│   │   ├── audit.jsx         # Audit screen
│   │   ├── rosterBuilder.jsx # Roster builder screen
│   │   ├── recruitment.jsx   # Recruitment screen
│   │   ├── pvp.jsx           # PvP screen
│   │   ├── mythicPlus.jsx    # Mythic+ screen
│   │   ├── season3.jsx       # Season 3 screen
│   │   ├── error.jsx         # Error screen
│   │   └── not-found.jsx     # Not found screen
│   └── _add_your_own_/       # Template for custom screens
└── components/                # Shared components (theme-agnostic)

Theme Configuration

Themes are configured in app.config.js:

const data = {
    "THEME": "default",  // Current active theme
    // ... other configuration
}

How It Works

1. Direct Imports with Theme Selection

The system uses direct imports for optimal performance, with theme-aware component selection:

import DynamicScreenLoader from '@/core/dynamicScreenLoader'
import DynamicThemeLoader from '@/core/dynamicThemeLoader'

// Usage with automatic theme selection
<DynamicThemeLoader>
    <DynamicScreenLoader 
        screenName="dashboard"
        props={{ guildData }}
    />
</DynamicThemeLoader>

// Usage with theme override
<DynamicThemeLoader theme="custom">
    <DynamicScreenLoader 
        screenName="dashboard"
        props={{ guildData }}
        theme="custom"
    />
</DynamicThemeLoader>

2. Theme Provider System

Themes provide styling and configuration through a provider pattern:

// core/themes/default/index.jsx
import { ThemeProvider as MuiThemeProvider } from '@mui/material/styles'
import { createTheme } from '@mui/material/styles'
import baseStyles from './base.scss'

const theme = createTheme({
    palette: {
        primary: { main: '#8dd52b' },
        secondary: { main: '#d38a2a' },
        // ... theme-specific colors
    },
    // ... other theme configuration
})

export default function ThemeProvider({ children }) {
    return (
        <MuiThemeProvider theme={theme}>
            {children}
        </MuiThemeProvider>
    )
}

3. Screen Component Structure

Each screen component follows a consistent pattern:

// core/screens/default/dashboard.jsx
import { Box, Grid } from '@mui/material'
import { MultiColorHeadingH1 } from '@/core/components/typography'
import '@/core/screens/default/scss/dashboard.scss'

const Dashboard = ({ guildData }) => {
    return (
        <section className="dashboard">
            <Box sx={{ p: 3 }}>
                <MultiColorHeadingH1>Dashboard</MultiColorHeadingH1>
                {/* Screen-specific content */}
            </Box>
        </section>
    )
}

export default Dashboard

Creating Custom Themes

Step 1: Create Theme Directory

mkdir core/themes/my-custom-theme

Step 2: Create Theme Files

// core/themes/my-custom-theme/index.jsx
import { ThemeProvider as MuiThemeProvider } from '@mui/material/styles'
import { createTheme } from '@mui/material/styles'
import './base.scss'

const theme = createTheme({
    palette: {
        primary: { main: '#ff6b6b' },    // Custom primary color
        secondary: { main: '#4ecdc4' },  // Custom secondary color
        background: { 
            default: '#2c3e50',
            paper: '#34495e'
        }
    },
    typography: {
        fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
        h1: { fontSize: '2.5rem', fontWeight: 700 },
        h2: { fontSize: '2rem', fontWeight: 600 }
    }
})

export default function ThemeProvider({ children }) {
    return (
        <MuiThemeProvider theme={theme}>
            {children}
        </MuiThemeProvider>
    )
}

Step 3: Create Theme Styles

// core/themes/my-custom-theme/base.scss
:root {
    --primary-color: #ff6b6b;
    --secondary-color: #4ecdc4;
    --background-color: #2c3e50;
    --text-color: #ecf0f1;
    --accent-color: #f39c12;
}

// Theme-specific global styles
body {
    background-color: var(--background-color);
    color: var(--text-color);
}

// Custom component overrides
.MuiButton-primary {
    background-color: var(--primary-color);
    &:hover {
        background-color: darken(#ff6b6b, 10%);
    }
}

Step 4: Create Custom Screens (Optional)

If you want to completely customize a screen:

// core/screens/my-custom-theme/dashboard.jsx
import { Box, Card, Typography } from '@mui/material'
import '@/core/screens/my-custom-theme/scss/dashboard.scss'

const Dashboard = ({ guildData }) => {
    return (
        <section className="custom-dashboard">
            <Box sx={{ p: 4 }}>
                <Typography variant="h1" sx={{ color: 'primary.main' }}>
                    My Custom Dashboard
                </Typography>
                {/* Completely custom layout and components */}
            </Box>
        </section>
    )
}

export default Dashboard

Step 5: Register Custom Theme

Add your custom theme to the dynamic screen loader:

// core/dynamicScreenLoader.jsx
import CustomDashboard from './screens/my-custom-theme/dashboard';
import CustomRosterBuilder from './screens/my-custom-theme/rosterBuilder';
// ... import other custom screens

const screenComponents = {
  default: {
    // ... existing default screens
  },
  'my-custom-theme': {
    dashboard: CustomDashboard,
    rosterBuilder: CustomRosterBuilder,
    // ... other custom screens
  }
};

Step 6: Activate Custom Theme

Update app.config.js:

const data = {
    "THEME": "my-custom-theme",  // Switch to custom theme
    // ... other configuration
}

Creating Custom Screens

Step 1: Create Screen Directory

mkdir core/screens/my-custom-theme
mkdir core/screens/my-custom-theme/scss

Step 2: Create Screen Component

// core/screens/my-custom-theme/customPage.jsx
import { Box, Typography } from '@mui/material'
import '@/core/screens/my-custom-theme/scss/customPage.scss'

const CustomPage = ({ data }) => {
    return (
        <section className="custom-page">
            <Box sx={{ p: 3 }}>
                <Typography variant="h1">Custom Page</Typography>
                {/* Custom content */}
            </Box>
        </section>
    )
}

export default CustomPage

Step 3: Create Screen Styles

// core/screens/my-custom-theme/scss/customPage.scss
.custom-page {
    background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
    min-height: 100vh;
    
    h1 {
        color: white;
        text-shadow: 2px 2px 4px rgba(0,0,0,0.5);
    }
}

Step 4: Register Screen with Theme

Add your custom screen to the dynamic screen loader:

// core/dynamicScreenLoader.jsx
import CustomPage from './screens/my-custom-theme/customPage';

const screenComponents = {
  default: {
    // ... existing screens
  },
  'my-custom-theme': {
    // ... existing custom screens
    customPage: CustomPage,
  }
};

Step 5: Use Custom Screen

// In any page file
import DynamicScreenLoader from '@/core/dynamicScreenLoader'

// Usage
<DynamicScreenLoader 
    screenName="customPage"
    props={{ data: pageData }}
    theme="my-custom-theme"
/>

Benefits of This System

🎯 Easy Customization

Change entire visual themes by updating one configuration value
Create custom screen implementations without affecting other themes
Maintain consistent component structure across themes

📊 Change Tracking

Clear separation between theme-specific and shared code
Easy to compare changes between different theme versions
Git-friendly structure for tracking modifications

🔧 Maintainability

Shared components remain consistent across themes
Theme-specific code is isolated and easy to manage
Clear patterns for developers to follow

🚀 Performance

Direct imports ensure optimal build-time and runtime performance
No lazy loading overhead or Suspense boundaries
All components are available immediately
Better tree-shaking and code optimization by Next.js

Best Practices

1. Keep Shared Components Theme-Agnostic

// ✅ Good - Component adapts to theme
const Button = ({ children, variant = 'primary' }) => (
    <MuiButton variant={variant} className={`theme-button ${variant}`}>
        {children}
    </MuiButton>
)

// ❌ Avoid - Hard-coded theme-specific styling
const Button = ({ children }) => (
    <button style={{ backgroundColor: '#8dd52b' }}>
        {children}
    </button>
)

2. Use CSS Variables for Theme Values

// ✅ Good - Theme-agnostic
.button {
    background-color: var(--primary-color);
    color: var(--text-color);
}

// ❌ Avoid - Hard-coded values
.button {
    background-color: #8dd52b;
    color: white;
}

3. Maintain Consistent File Structure

core/
├── themes/
│   └── theme-name/
│       ├── index.jsx          # Theme provider
│       ├── base.scss          # Base styles
│       └── config.js          # Configuration
└── screens/
    └── theme-name/
        ├── screenName.jsx     # Screen component
        └── scss/
            └── screenName.scss # Screen styles

4. Document Theme Dependencies

// core/themes/my-theme/README.md
# My Custom Theme

## Dependencies
- Requires Material-UI v5
- Compatible with Next.js 14
- Uses custom color palette

## Customization Options
- Primary color: #ff6b6b
- Secondary color: #4ecdc4
- Background: Dark theme
- Typography: Roboto font family

## Usage
Set `THEME: "my-theme"` in app.config.js

Migration Guide

If you're upgrading from the old lazy loading system:

Before (Old Lazy Loading System)

import { lazy, Suspense } from 'react'
import config from '@/app.config.js'

// Theme provider
const ThemeProvider = lazy(() => import(`@/core/themes/${config.THEME}`))

// Screen component
const Dashboard = lazy(() => import(`@/core/screens/${config.THEME}/dashboard`))

// Wrap in Suspense
<Suspense fallback={<div>Loading...</div>}>
    <ThemeProvider>
        <Suspense fallback={<div>Loading Dashboard...</div>}>
            <Dashboard guildData={guildData} />
        </Suspense>
    </ThemeProvider>
</Suspense>

After (New Direct Import System)

import DynamicScreenLoader from '@/core/dynamicScreenLoader'
import DynamicThemeLoader from '@/core/dynamicThemeLoader'

// Simple, direct usage
<DynamicThemeLoader>
    <DynamicScreenLoader 
        screenName="dashboard"
        props={{ guildData }}
    />
</DynamicThemeLoader>

Troubleshooting

Common Issues

Component Not Loading
- Check that the theme directory exists in core/themes/
- Verify the screen component file exists in core/screens/{theme}/
- Ensure the screen is properly registered in dynamicScreenLoader.jsx
- Check browser console for error messages
Styling Not Applied
- Check that theme SCSS files are imported in the screen component
- Verify CSS variables are defined in the theme's base.scss
- Ensure theme provider is wrapping the component tree in layout.jsx
Build Errors
- Check for typos in import statements in dynamicScreenLoader.jsx
- Verify all theme files exist and are properly exported
- Ensure proper export statements in theme files
Theme Not Switching
- Verify THEME is set correctly in app.config.js
- Check that the theme is registered in screenComponents object
- Ensure theme directory structure matches expected pattern

Debug Mode

Enable debug logging by adding to your theme:

// core/themes/my-theme/index.jsx
console.log('Loading theme:', config.THEME)
console.log('Theme path:', `@/core/themes/${config.THEME}`)

You can also use the helper functions to debug available themes:

import { getAvailableThemes, getAvailableScreens } from '@/core/dynamicScreenLoader'

console.log('Available themes:', getAvailableThemes())
console.log('Available screens for default theme:', getAvailableScreens('default'))

This theme and screen system provides a robust foundation for customization while maintaining clean code organization and easy change tracking. Whether you're creating a simple color scheme change or a complete visual overhaul, the system scales to meet your needs.

Helper Functions

The dynamic screen loader and theme loader provide several helper functions for theme management:

Screen Loader Helpers

`registerTheme(themeName, screens)`

Register a new theme with its screen components:

import { registerTheme } from '@/core/dynamicScreenLoader'
import CustomDashboard from './screens/my-theme/dashboard'
import CustomRoster from './screens/my-theme/rosterBuilder'

registerTheme('my-theme', {
  dashboard: CustomDashboard,
  rosterBuilder: CustomRoster,
  // ... other screens
})

`getAvailableThemes()`

Get a list of all available themes:

import { getAvailableThemes } from '@/core/dynamicScreenLoader'

const themes = getAvailableThemes()
console.log('Available themes:', themes) // ['default', 'my-theme']

`getAvailableScreens(themeName)`

Get a list of available screens for a specific theme:

import { getAvailableScreens } from '@/core/dynamicScreenLoader'

const screens = getAvailableScreens('default')
console.log('Default theme screens:', screens) // ['dashboard', 'rosterBuilder', ...]

Theme Loader Helpers

`registerThemeProvider(themeName, themeProvider)`

Register a new theme provider:

import { registerThemeProvider } from '@/core/dynamicThemeLoader'
import CustomThemeProvider from './themes/my-theme'

registerThemeProvider('my-theme', CustomThemeProvider)

`getAvailableThemeProviders()`

Get a list of all available theme providers:

import { getAvailableThemeProviders } from '@/core/dynamicThemeLoader'

const themeProviders = getAvailableThemeProviders()
console.log('Available theme providers:', themeProviders) // ['default', 'my-theme']

📊 Data Structure

Character Data Structure

{
  "name": "CharacterName",
  "realm": "RealmName",
  "level": 80,
  "itemLevel": 645,
  "class": "Warrior",
  "spec": "Arms",
  "rank": 0,
  "rankName": "Guild Lead",
  "isMain": true,
  "missingEnchants": ["WRIST", "LEGS"],
  "raidLockouts": {
    "instance1": "2024-01-15T10:00:00Z"
  },
  "mythicPlus": {
    "score": 2500,
    "bestKeys": [...]
  },
  "pvp": {
    "arenaRating": 1800,
    "rbgRating": 1600
  },
  "seasonalStats": {
    "highestTimedKey": 24,
    "highestKeyOverall": 25,
    "totalRuns": 150,
    "completedRuns": 128,
    "averageRating": 2850,
    "completionRate": 85.3,
    "topPlayedMembers": [
      {
        "name": "Player1",
        "spec": "Protection",
        "server": "sylvanas",
        "count": 45
      }
    ],
    "dungeonStats": {
      "Dungeon Name": {
        "totalRuns": 25,
        "timedRuns": 22,
        "highestKey": 25,
        "averageRating": 2800
      }
    },
    "affixStats": {
      "Fortified": { "runs": 75, "averageRating": 2800 },
      "Tyrannical": { "runs": 75, "averageRating": 2900 }
    },
    "roleStats": {
      "TANK": { "runs": 30, "averageRating": 2750 },
      "HEALER": { "runs": 120, "averageRating": 2850 }
    },
    "totalPlaytime": 45000
  }
}

Statistics Data Structure

{
  "statistics": {
    "totalMembers": 150,
    "activeMembers": 120,
    "averageItemLevel": 645,
    "roleDistribution": {
      "tanks": 8,
      "healers": 12,
      "dps": 130
    }
  },
  "missingEnchants": {
    "all": 45,
    "mains": 12,
    "alts": 33
  },
  "topPvp": [...],
  "topPve": [...]
}

Seasonal Statistics Data Structure 🆕 NEW v1.5.0

{
  "season": 15,
  "lastUpdated": "2024-01-01T00:00:00.000Z",
  "totalCharacters": 150,
  "charactersWithMplus": 120,
  "totalRuns": 2500,
  "totalTimedRuns": 2100,
  "topPlayers": [
    {
      "name": "Player1",
      "server": "sylvanas",
      "highestKey": 25,
      "highestTimedKey": 24,
      "totalRuns": 150,
      "completionRate": 85.5,
      "averageRating": 2850
    }
  ],
  "dungeonLeaderboard": {
    "Dungeon Name": {
      "highestKey": 25,
      "totalRuns": 45,
      "averageRating": 2800
    }
  },
  "roleStats": {
    "TANK": { "averageRating": 2700, "totalPlayers": 5 },
    "HEALER": { "averageRating": 2750, "totalPlayers": 8 },
    "DPS": { "averageRating": 2800, "totalPlayers": 17 }
  }
}

🚀 Getting Started

Prerequisites

Node.js 18+
Yarn or npm
Backend API server running
MongoDB database
Battle.net API credentials (Client ID and Secret)

Installation

Clone the repository
```
git clone <repository-url>
cd repo-name
```
Install dependencies
```
yarn install
# or
npm install
```

Set up environment variables

cp .env.example .env.local
# Edit .env.local with your configuration

Required environment variables:

NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_CLIENT_BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_GUILD_NAME=Your Guild Name
NEXT_PUBLIC_GUILD_REALM=Your Realm Name
NEXT_PUBLIC_BASE_URL=https://your-domain.com
NEXT_PUBLIC_APP_URL=https://your-domain.com

Start the backend API server

cd ../world-of-warcraft-api
yarn install
# Configure backend .env file with MongoDB connection and Battle.net API credentials
yarn dev

Start the frontend development server

cd ../world-of-warcraft-frontend
yarn dev
# or
npm run dev

Run the installation wizard
- Navigate to http://localhost:3000/install
- Follow the guided installation process:
  
  Step 1: App Settings
  - Enter your Battle.net API Client ID and Secret
  - Configure guild name and realm (use slugs, e.g., time-and-tide for "Time and Tide")
  - Set region (EU, US, KR, TW)
  - Configure guild requirements (level, item level, ranks, etc.)
  - Settings are validated against Battle.net API before saving
  Step 2: Fetch Guild Data
  - Automatically fetches all guild member data
  - Real-time progress updates via WebSocket
  - Can be skipped and run later
  Step 3: Create Admin Account
  - Create your admin username and password
  - Password must meet strength requirements:
    - Minimum 12 characters
    - At least one uppercase letter
    - At least one lowercase letter
    - At least one number
    - At least one special character
  - After creating admin account, installation is complete
Access the application
- After installation, navigate to http://localhost:3000
- The dashboard will display your guild data
- Access settings at /settings (requires admin login)
- View errors at /settings/errors (requires admin login)

Post-Installation Configuration

Updating App Settings

Navigate to /settings (requires admin login)
Edit any editable settings (most fields can be changed)
Protected fields (Guild Name, Realm, API Key) cannot be modified
Click "Save Changes" to update

Resetting the Database

Navigate to /settings
Scroll to "Danger Zone"
Click "Reset Database"
Confirm with admin credentials
This will delete all data collections but preserve app settings
You'll need to recreate your admin account and re-fetch guild data

Changing Protected Settings

To change Guild Name, Realm, or API credentials:

Navigate to /install (requires admin login if admin exists)
Enter admin credentials to access
Update settings and save (will overwrite existing configuration)
Re-fetch guild data if needed

Managing Join/Recruitment Page Content

Customize your guild's recruitment page to attract new members:

Access the Join Page Editor
- Navigate to /settings/join (requires admin login)
- View real-time preview of your changes
Edit Hero Section
- Update the main title and subtitle
- Add/remove/edit badges with color selection (gold, blue, green)
- Perfect for highlighting guild focus (Mythic Raiding, PvP, M+)
Manage Content Sections
- Add Sections: Click "Add Section" to create new content areas
- Add Blocks: Within each section, add different block types:
  - Text Blocks: For welcome messages, guild descriptions, or detailed information
  - List Blocks: For requirements, benefits, raid schedules, or application steps
  - Contact Blocks: For Discord invites and email contact information
- Layout Options: Choose full-width, left-half, or right-half for each block
- Reorder: Use Move Up/Down buttons to organize sections and blocks
Seed Example Content
- Click "Seed Join Data" to populate with example recruitment content
- Includes pre-formatted sections for requirements, benefits, schedule, and contact
- Great starting point for customization
Save Changes
- Click "Save Join Text" to publish your changes
- Changes appear immediately on /join page
- No cache issues - content updates in real-time

Example Content Structure:

Hero Section
  ├─ Title: "Join Our Guild"
  ├─ Subtitle: "Epic adventures await..."
  └─ Badges: [Mythic Raiding, PvP, M+]

Section 1: Welcome
  └─ Text Block (Full Width): Guild introduction

Section 2: Requirements & Benefits
  ├─ List Block (Left): Mythic Raiding Requirements
  └─ List Block (Right): Guild Benefits

Section 3: Application & Current Needs
  ├─ List Block (Left): Application Process
  └─ List Block (Right): Current Needs

Section 4: Raid Schedule
  └─ List Block (Full Width): Raid times and dates

Section 5: Contact
  └─ Contact Block (Full Width): Discord + Email links

Production Build

Build the application
```
yarn build
# or
npm run build
```
Start the production server
```
yarn start
# or
npm start
```

🔧 Development

Project Structure

repo-name/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes
│   │   ├── seasonal-stats/ # Seasonal statistics endpoints
│   │   └── member/         # Character profile endpoints
│   ├── audit/             # Audit page
│   ├── mythic-plus/       # M+ page with tabs
│   ├── member/            # Individual character profiles
│   ├── rated-pvp/         # PvP page
│   ├── roster/            # Roster page
│   ├── season3/           # Season 3 page
│   └── mrt/               # MRT page
├── core/                   # Core application code
│   ├── components/         # Reusable components
│   │   └── Season3Stats/   # Season 3 statistics components
│   ├── hooks/             # Custom React hooks
│   ├── modules/           # Feature modules
│   │   ├── SeasonalStatistics.jsx    # Seasonal stats display
│   │   └── SeasonalLeaderboard.jsx   # Leaderboard display
│   ├── screens/           # Screen components
│   │   └── default/       # Default screen implementations
│   │       ├── memberDetail.jsx      # Character profile screen
│   │       └── mythicPlus.jsx       # Enhanced M+ screen
│   └── utils/             # Utility functions
├── lib/                    # Library code
│   ├── api.js             # API client
│   └── clientApi.js       # Client-side API
└── public/                 # Static assets

Key Features

Real-time Data Updates

10-minute cache revalidation
Server-side data fetching
Optimistic UI updates

Responsive Design

Mobile-first approach
Material-UI components
Custom SCSS styling

Performance Optimizations

Next.js App Router
Server-side rendering
Image optimization
Code splitting

Accessibility

ARIA labels
Keyboard navigation
Screen reader support
High contrast mode

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0).

⚠️ Warning

This project is currently being refactored to be brought to the open source community. There's still some messy code here that needs to be cleaned up. Please be aware that:

Some components may have inconsistent coding patterns
Documentation may be incomplete in certain areas
Error handling may need improvement
Code organization is still being optimized

I'm actively working on improving code quality and documentation.

📋 Open Todos

High Priority

Rebuild the MRT tool - The Method Raid Tools integration needs a complete overhaul

Medium Priority

Clean up inconsistent code patterns
Improve error handling across all components
Improve the UI / Design

Low Priority

Add more customization options for guild requirements
Improve accessibility features

🆘 Support

For support, please contact me create an issue in the repository.

Note: This application requires a compatible backend API server to function properly. Ensure your backend is running and accessible before starting the frontend application.

Name		Name	Last commit message	Last commit date
.vscode		.vscode
_screenshots		_screenshots
app		app
components/ui		components/ui
core		core
hooks		hooks
lib		lib
public		public
tools		tools
.env_example		.env_example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
app.config.js		app.config.js
components.json		components.json
components.json.bak		components.json.bak
menu.config.js		menu.config.js
middleware.js		middleware.js
next.config.js		next.config.js
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
update-install.js		update-install.js
yarn.lock		yarn.lock

Latest commit

History

Folders and files

Repository files navigation

World of Warcraft Guild Management Application

Version 3.2 — Enrichment UI, Admin SEO & Dashboard Command Center 🆕

Database-managed guild ranks

Admin SEO & page titles

Audit workspace tabs

Dashboard command center

Mythic+ & rankings data

Character profiles

Version 3.1 — Midnight Expansion & Setup Overhaul 🆕

Multi-Raid Lockout Tracking

Audit Table — "Raid Locks" Column

Audit Analytics Dashboard

Member Profile — Raid Overview Card

Upgrade Page (/upgrade)

Setup Wizard Redesign (/install)

Config Key Migration

Version 3.0 — The Visual Overhaul 🆕

The Big Picture

What Changed Per Screen

Navigation

Dashboard

Audit

Mythic+

Member Profile

Seasons / Sign-Up

Recruitment / Join

Roster Display

Character Cards

Global Improvements

Version 2.2 Changelog

Roster Builder Admin System

New Pages & Routes

API Routes

Version 2.1 Changelog 🆕

Season Signup System Improvements

New Settings Options

New Pages & Routes

API Routes

Version 2.0 Changelog

Major Features

New Pages & Routes

Installation & Setup Improvements

New API Routes

Security Enhancements

Configuration Management

Dynamic Recruitment System

Version 1.5.0 Changelog

New Features

New Pages & Components

New API Routes

Enhanced Data Features

📄 License

🖼️ Screenshots

Version 2.0 Screenshots 🆕

Previous Versions

Dashboard

Roster Builder

Audit

Mythic+ Overview

Weekly Recap Tab

Leaderboard Tab

Statistics Tab

Individual Character Profiles

Character Overview

Seasonal Performance

Dungeon Performance

Equipment Analysis

Season 3 Signup

UI/Design Example

🔧 Environment Variables

Environment Variables Explained

⚙️ Application Configuration

Installation-Based Configuration (v2.0+)

Legacy Configuration (app.config.js)

Guild Settings

Role Definitions

Upgrade Page (`/upgrade`)

Setup Wizard Redesign (`/install`)

`/` - Dashboard

`/roster` - Roster Display

`/settings/roster-builder` - Roster Builder (Admin Only) 🆕 NEW v2.2

`/audit` - Guild Audit

`/mythic-plus` - Mythic+ Overview

`/rated-pvp` - PvP Overview

`/season3` - Season 3 Planning

`/mrt` - MRT Integration

`/member/[realm]/[character]` - Individual Character Profiles 🆕 NEW v1.5.0

`/join` - Guild Recruitment 🆕 ENHANCED in v2.0

`/settings` - Admin Settings Management 🆕 NEW v2.0

`/settings/errors` - Error Management 🆕 MOVED in v2.0