MosswartOverlord/docs/plans/2026-02-09-suitbuilder-architecture.md

# Suitbuilder Architecture & Implementation Status

## Overview

The Equipment Suit Builder is a real-time optimization engine that finds optimal equipment loadouts for characters by searching across multiple characters' inventories (mules). It uses constraint satisfaction algorithms derived from the original Mag-SuitBuilder (C#) plugin, reimplemented in Python as part of the inventory-service.

**Status:** Production Ready
**Access:** `/suitbuilder.html`
**Backend:** `inventory-service/suitbuilder.py`
**Frontend:** `static/suitbuilder.js`, `static/suitbuilder.html`, `static/suitbuilder.css`

---

## Key Achievements (2025-2026)

- Multi-character search across 100+ characters and 25,000+ items
- Mag-SuitBuilder constraint satisfaction algorithms with branch pruning
- Real-time SSE streaming with phase updates and progress tracking
- Spell bitmap-based overlap detection and scoring
- Locked slot constraints with set/spell preservation across searches
- Stable deterministic sorting for reproducible results
- Comprehensive UI with suit summary and copy-to-clipboard
- Individual slot clear buttons for granular control
- Full cantrip/ward selection UI (attributes, weapon skills, magic skills, defenses, wards)

---

## Architecture

### Core Components

1. **ConstraintSatisfactionSolver** - Main search engine. Performs recursive depth-first search through equipment buckets, applying constraints and scoring at each level.

2. **ItemBucket** - Slot-based item organization. Groups items by equipment slot, sorts by priority (armor level, ratings, spells), and handles armor reduction variants.

3. **SpellBitmapIndex** - O(1) spell overlap detection using bitwise operations. Each spell is assigned a unique bit position, enabling instant duplicate detection.

4. **SuitState** - Mutable state during recursive search. Tracks equipped items, aggregated spell bitmap, set counts, total armor, and ratings.

5. **SearchConstraints** - User-defined requirements including character selection, set preferences, required spells, locked slots, and scoring weights.

6. **ItemPreFilter** - Pre-processing step that removes strictly dominated items (items surpassed in all metrics by another item in the same slot).

### Data Flow

```
User (suitbuilder.html)
  |
  | POST /inv/suitbuilder/search (constraints JSON)
  |
  v
Main Service (main.py)
  |
  | Streaming proxy (dedicated SSE endpoint)
  |
  v
Inventory Service (inventory-service/main.py)
  |
  | Routes to suitbuilder module
  |
  v
ConstraintSatisfactionSolver
  |
  | 1. Load items from inventory DB
  | 2. Create equipment buckets per slot
  | 3. Apply armor reduction rules
  | 4. Sort buckets (smallest first for pruning)
  | 5. Recursive search with constraint checking
  | 6. Score and yield suits via SSE stream
  |
  v
User (real-time suit results appear as found)
```

### SSE Streaming Architecture

The suitbuilder search is a long-running operation (up to 5 minutes). Results stream in real-time via Server-Sent Events (SSE).

**Main service** (`main.py`) has a dedicated streaming proxy endpoint at `/inv/suitbuilder/search` that uses `httpx.AsyncClient.stream()` to forward chunks without buffering. The generic `/inv/{path:path}` proxy buffers entire responses, which would cause timeouts for SSE streams.

**Event types streamed:**
- `phase` - Search phase updates (loading, buckets, reducing, sorting, searching)
- `suit` - New suit found with items and score
- `log` - Verbose debug messages
- `stats` - Search statistics (branches explored, suits found, elapsed time)
- `complete` - Search finished
- `error` - Error occurred

---

## Spell System Implementation

### Spell Bitmap Index

Uses bitwise operations for O(1) spell overlap detection:
- Each spell is assigned a unique bit position in an integer bitmap
- `spell_bitmap |= item.spell_bitmap` aggregates spells across items in a suit
- `new_spells = item_bitmap & needed_bitmap & ~current_bitmap` detects novel spell contributions
- Prevents duplicate spell slots across items in strict mode

### Spell Constraint Flow

1. **UI Collection**: Checkboxes for legendary cantrips and wards
   - **Attributes**: Strength, Endurance, Coordination, Quickness, Focus, Willpower
   - **Weapon Skills**: Finesse, Heavy, Light, Missile, Two-handed
   - **Magic Skills**: War Magic, Void Magic, Creature, Item, Life Magic
   - **Defenses**: Magic Resistance, Invulnerability
   - **Wards**: Flame, Frost, Acid, Storm, Slashing, Piercing, Bludgeoning, Armor

2. **Backend Processing**:
   - `needed_spell_bitmap = spell_index.get_bitmap(required_spells)` pre-computes target
   - During item loading: `item.spell_bitmap = spell_index.get_bitmap(item.spell_names)`
   - During search: `_can_get_beneficial_spell_from()` rejects items with only duplicate spells
   - Items with spells that contribute nothing new to the suit are pruned

3. **Scoring**:
   - Each fulfilled required spell: +100 points
   - Duplicate spells prevented by constraint (not scored negatively, just blocked)
   - Encourages maximum spell diversity across the suit

### Jewelry Special Handling

Jewelry (rings, bracelets, necklaces, trinkets) receives special treatment:
- Only added to suits if they contribute new required spells
- Prevents jewelry spam when no spell constraints are specified
- Prioritizes spell contribution over raw stats for jewelry slots
- Items with zero beneficial spell contribution are rejected

---

## Recent Features (February 2026)

### Locked Slots System

Allows users to lock specific equipment slots with set and spell constraints. Locked slots are preserved when selecting different suit results.

**Features:**
- Lock populated slots automatically (extracts set + spells from the item)
- Lock empty slots manually (configure set + spell requirements via form)
- Visual distinction (red border, lock icon)
- Constraints sent to backend (locked slots filtered from search buckets)
- Preserved when selecting different suits from results

**Use Cases:**
- "I already have this Legendary Empyrean Helm, find suits around it"
- "Lock Head slot to Empyrean set with L. Strength + L. Flame Ward"
- Iterative refinement: lock good items, re-search for better accessories

### Suit Summary Panel

Copy-paste friendly summary below equipment slots showing all items with their source characters.

**Format:**
```
Slot: Item Name [Spell1, Spell2] - Character Name
```

**Features:**
- Auto-updates when suit selected or slots cleared
- Copy to clipboard button with visual feedback
- Monospace font for readability
- Shows all equipped items with their source characters

### Clear Slot Button

Small "x" button on populated slots for granular control:
- Clears individual slots without affecting locked state
- Removes item from selected suit state
- Updates summary automatically

---

## Known Limitations

### Slot-Aware Spell Filtering
The system currently treats all slots equally when checking spell availability. In reality, certain cantrips and wards never appear on underclothes (shirt/pants). The search could be optimized by pre-filtering based on realistic spell pools per slot type.

### Spell Priority Weighting
All required spells are weighted equally (+100 points each). There is no mechanism to mark certain spells as "critical" vs "nice to have."

---

## Future Enhancements Roadmap

### Phase 1: Spell System Improvements

#### Spell Priority Weighting
Allow users to mark certain spells as critical vs optional:
- Critical spells: +200 points (must have)
- High priority: +150 points
- Normal priority: +100 points (current default)
- Low priority: +50 points

#### Slot-Aware Spell Filtering
Pre-filter items based on realistic spell pools per slot type:
- **Underclothes** (Shirt/Pants): Primarily damage rating, rarely cantrips/wards
- **Armor** (Head/Chest/Arms/Legs/Hands/Feet): Full cantrip/ward pool
- **Jewelry** (Rings/Bracelets/Neck): Full cantrip/ward pool
- **Trinket**: Limited or no spells

Benefits: Faster search (smaller search space), more realistic suit expectations, better UX.

### Phase 2: New Builders

#### Weapon Suit Builder
Optimize weapon + shield/offhand combinations:
- Weapon skill requirements (Heavy, Light, Finesse, etc.)
- Damage type optimization
- Special property constraints (Crushing Blow, Armor Rending, etc.)

#### Accessory-Only Builder
Find best jewelry/trinket combinations when armor is already decided:
- Smaller search space = faster results
- Focus on spell coverage and rating optimization
- Use case: "I have my armor set, find best accessories"

#### Multi-Suit Batch Generation
Generate multiple viable suits in one search:
- "Show me top 10 suits for different playstyles"
- Variation in set combinations
- Export/compare multiple options

### Phase 3: Advanced Features

#### Saved Searches
- Save constraint configurations as named presets
- Quick re-run with updated inventory
- Presets like "Mage Build", "Tank Build", etc.

#### Suit Comparison
- Side-by-side comparison of 2-3 suits
- Highlight differences in items, spells, and ratings
- Visual scoring breakdown