# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

BLU (Better Level-Up!) is a World of Warcraft addon that replaces default sounds with iconic audio from 50+ games. Currently in v5.3.6 with a complete professional reorganization.

**Key Points:**
- Ace3 library dependencies
- Professional folder structure with proper capitalization
- Modular architecture for performance
- RGX Mods branding (RealmGX Community Project)

## Current Directory Structure

```
BLU/
├── data/               # Core Systems and Modules
│   ├── battlepets.lua
│   ├── core.lua
│   ├── initialization.lua
│   ├── localization.lua
│   ├── options.lua
│   ├── sounds.lua
│   └── utils.lua
├── Libs/               # Ace3 Libraries
├── modules/            # Feature modules (quest, levelup, etc) - (assuming these exist from initial structure, need to re-verify)
├── media/              # Sounds and textures (assuming these exist from initial structure)
│   ├── sounds/         # Game sound files (.ogg)
│   └── Textures/       # Icons and images (.tga, .blp, .png)
├── localization/       # Language files (assuming these exist from initial structure)
├── .github/            # GitHub Actions workflows
├── BLU.toc             # Table of Contents (uppercase)
├── blu.xml             # Main XML loader (lowercase)
├── README.md           # Public documentation
└── CLAUDE.md           # This file
```

## Architecture

### Loading Order
`BLU.toc` -> `blu.xml` -> Libraries -> Data Files.

### AI Assistant Integration
This project uses `claude-code-router` to delegate tasks to specialized AI models:
- **`wow-ui-expert` (GPT-4o)**: For UI/UX design and implementation.
- **`lua-optimizer` (Deepseek)**: For performance and memory optimization.
- **`code-reviewer` (Gemini)**: For code quality, architecture, and security reviews.

### Key Design Decisions
- Ace3 library dependencies
- Custom lightweight framework mimics Ace3 API for easier migration
- Feature modules only loaded when enabled (CPU/memory optimization)

## Common Development Tasks

### Git Workflow
- **`main`**: Stable releases.
- **`dev`**: Active development.

## Important Conventions

### Naming Conventions (STRICT REQUIREMENT)
- **ALL directories**: MUST be `lowercase`.
- **ALL Lua and XML files**: MUST be `lowercase`.
- **EXCEPTIONS**:
  - `BLU.toc` MUST be `UPPERCASE`.
- **Addon Name in Code**: `BLU` (uppercase).
- **Author**: `donniedice`
- **Email**: `donniedice@protonmail.com`

**IMPORTANT**: Windows is case-insensitive but WoW's Lua is case-sensitive. All paths in XML/Lua must match exact case.

### Sound File Structure
- The project is transitioning its sound file structure. While the goal is to have consolidated sound files with volume handled by addon settings, the current implementation still uses volume variants in filenames (e.g., `gamename_soundtype_high.ogg`).
- The sound registry (`data/sounds.lua` or similar) contains logic to handle both consolidated and variant filenames.
- When working with sounds, refer to `data/sounds.lua` and the existing files in `media/sounds/` to understand the current conventions.

### Localization
- Use `BLU:Loc(key, ...)` for all user-facing strings.
- All localizations are stored in `data/localization.lua`.
