Add SOLID Principles & Project Structure Upgrade documentation

- Introduced comprehensive analysis and refactoring roadmap for Wrdler's architecture.
- Detailed current architecture analysis, including package structure and key problems identified.
- Proposed reorganized package structure with layered architecture.
- Addressed violations of SOLID principles, including Single Responsibility, Open/Closed, Dependency Inversion, and Interface Segregation.
- Eliminated magic numbers and consolidated constants into dedicated configuration files.
- Implemented centralized session state management to reduce global state usage.
- Consolidated overlapping modules for improved clarity and maintainability.
- Added configuration validation to ensure required settings are provided.

specs/solid.mdx

@@ -0,0 +1,1175 @@
+---
+title: "SOLID Principles & Project Structure Upgrade"
+description: "Comprehensive analysis and refactoring roadmap for Wrdler's architecture, covering SOLID principles, package reorganization, and prioritized implementation steps."
+---
+
+# Wrdler — SOLID Principles & Project Structure Upgrade
+
+> **Version:** 0.3.2  
+> **Date:** 2026-04-17  
+> **Status:** Recommendation
+
+---
+
+## Executive Summary
+
+Wrdler is a Streamlit-based vocabulary puzzle game with a flat package structure where architectural boundaries are blurred. The `ui.py` module is a god module (~1000+ lines) that couples the presentation layer directly to infrastructure concerns (HuggingFace, Streamlit internals, file I/O). This document provides a prioritized refactoring roadmap grounded in SOLID principles, with concrete code examples and Mermaid diagrams.
+
+---
+
+## Current Architecture Analysis
+
+### Package Structure (Current)
+
+```mermaid
+graph TB
+    subgraph wrdler["wrdler/ (flat)"]
+        app["app.py<br/>Entry point"]
+        ui["ui.py<br/>~1000 lines<br/>God module"]
+        logic["logic.py<br/>Game mechanics"]
+        generator["generator.py<br/>Puzzle generation"]
+        models["models.py<br/>Data classes"]
+        leaderboard["leaderboard.py<br/>Leaderboard logic"]
+        leaderboard_page["leaderboard_page.py<br/>Leaderboard UI"]
+        game_storage["game_storage.py<br/>HF storage + serialization"]
+        local_storage["local_storage.py<br/>Local file storage"]
+        settings_page["settings_page.py<br/>Settings UI + persistence"]
+        word_loader["word_loader.py<br/>Word loading"]
+        word_loader_ai["word_loader_ai.py<br/>AI generation"]
+        audio["audio.py<br/>Audio playback"]
+        ui_helpers["ui_helpers.py<br/>UI utilities"]
+        hall_of_legends["hall_of_legends.py<br/>Hall of Legends"]
+        oauth["oauth.py<br/>OAuth utilities"]
+        version_info["version_info.py<br/>Version display"]
+        modules["modules/<br/>Dumping ground"]
+        constants["modules/constants.py<br/>Mixed concerns"]
+        storage_mod["modules/storage.py<br/>HF storage"]
+        file_utils["modules/file_utils.py"]
+    end
+
+    app --> ui
+    ui --> logic
+    ui --> generator
+    ui --> models
+    ui --> word_loader
+    ui --> game_storage
+    ui --> leaderboard
+    ui --> settings_page
+    ui --> audio
+    ui --> ui_helpers
+    ui --> hall_of_legends
+    ui --> local_storage
+    game_storage --> storage_mod
+    game_storage --> constants
+    leaderboard --> storage_mod
+    leaderboard --> constants
+    settings_page --> constants
+    word_loader_ai --> constants
+    hall_of_legends --> storage_mod
+    hall_of_legends --> constants
+```
+
+### Key Problems Identified
+
+| # | Problem | Severity | Files Affected |
+|---|---------|----------|----------------|
+| 1 | `ui.py` is a god module (~1000+ lines) | Critical | `ui.py` |
+| 2 | No architectural layering | Critical | Entire package |
+| 3 | Magic numbers scattered throughout | High | `logic.py`, `generator.py`, `constants.py`, `ui.py` |
+| 4 | Hardcoded game modes as strings | High | `logic.py`, `ui.py`, `generator.py` |
+| 5 | Hardcoded scoring tiers | High | `logic.py`, `ui.py` |
+| 6 | `st.session_state` as global state | High | Throughout |
+| 7 | `modules/` is a dumping ground | Medium | `modules/` |
+| 8 | Overlapping storage modules | Medium | `game_storage.py`, `local_storage.py`, `modules/storage.py` |
+| 9 | `GameState` is a god class | Medium | `models.py` |
+| 10 | Constants mix unrelated concerns | Low | `constants.py` |
+
+---
+
+## 1. Reorganize Package Structure
+
+### Current Structure
+
+```
+wrdler/
+├── app.py                          # Entry point
+├── wrdler/
+│   ├── __init__.py
+│   ├── models.py            # Data models (Coord, Word, Puzzle, GameState)
+│   ├── generator.py         # Puzzle generation
+│   ├── logic.py             # Game mechanics
+│   ├── ui.py                # Streamlit UI (god module)
+│   ├── oauth.py             # OAuth utilities
+│   ├── settings_page.py     # Settings page UI + persistence
+│   ├── leaderboard.py       # Leaderboard logic
+│   ├── leaderboard_page.py  # Leaderboard UI
+│   ├── word_loader.py       # Word list management
+│   ├── word_loader_ai.py    # AI word generation
+│   ├── game_storage.py      # HF game storage wrapper
+│   ├── version_info.py      # Version display
+│   ├── audio.py             # Audio playback
+│   ├── hall_of_legends.py   # Hall of Legends
+│   ├── local_storage.py     # Local file storage
+│   ├── ui_helpers.py        # UI utilities
+│   ├── sounds.py            # Sound effects
+│   ├── ui_helpers.py        # UI helpers
+│   ├── modules/             # Dumping ground
+│   │   ├── constants.py     # Mixed concerns
+│   │   ├── storage.py       # HF storage
+│   │   └── file_utils.py    # File utilities
+│   ├── settings/            # Settings files
+│   └── words/               # Word list files
+├── tests/
+├── specs/
+├── static/
+├── pyproject.toml
+└── requirements.txt
+```
+
+### Recommended Structure
+
+```
+wrdler/
+├── app.py                          # Entry point (minimal)
+├── wrdler/
+│   ├── __init__.py
+│   ├── domain/                     # Domain layer (entities, value objects)
+│   │   ├── __init__.py
+│   │   ├── models.py               # Coord, Word, Puzzle (pure data)
+│   │   ├── game_state.py           # GameState behavior
+│   │   ├── game_config.py          # GameConfig value object
+│   │   ├── game_mode.py            # GameMode strategy interface
+│   │   └── scoring.py              # Scoring tiers
+│   ├── application/                # Application layer (use cases)
+│   │   ├── __init__.py
+│   │   ├── game_service.py         # Game orchestration (guess, reveal, score)
+│   │   ├── puzzle_service.py       # Puzzle generation orchestration
+│   │   ├── leaderboard_service.py  # Leaderboard orchestration
+│   │   └── settings_service.py     # Settings orchestration
+│   ├── infrastructure/             # Infrastructure layer (external concerns)
+│   │   ├── __init__.py
+│   │   ├── storage/
+│   │   │   ├── __init__.py
+│   │   │   ├── storage_backend.py  # Abstract interface (Protocol)
+│   │   │   ├── hf_storage.py       # HuggingFace implementation
+│   │   │   └── local_storage.py    # Local file implementation
+│   │   ├── audio/
+│   │   │   ├── __init__.py
+│   │   │   ├── audio_backend.py    # Abstract interface
+│   │   │   └── streamlit_audio.py  # Streamlit implementation
+│   │   ├── word_loader.py          # Word loading (keep, simplify)
+│   │   └── word_generator_ai.py    # AI word generation (keep)
+│   ├── presentation/               # Presentation layer (UI)
+│   │   ├── __init__.py
+│   │   ├── ui.py                   # Streamlit UI orchestration
+│   │   └── components/
+│   │       ├── __init__.py
+│   │       ├── grid.py             # Grid rendering
+│   │       ├── scoring.py          # Score display
+│   │       ├── settings_panel.py   # Settings UI
+│   │       ├── leaderboard_panel.py# Leaderboard UI
+│   │       └── game_over_dialog.py # Game over dialog
+│   └── config/                     # Configuration
+│       ├── __init__.py
+│       ├── constants.py            # App constants
+│       ├── hf_config.py            # HF credentials and repo IDs
+│       ├── ai_config.py            # AI model settings
+│       └── app_config.py           # Application defaults
+├── tests/
+├── words/                          # Word list files (keep at root)
+├── static/                         # PWA assets (keep at root)
+├── settings/                       # User settings (keep at root)
+├── pyproject.toml
+└── requirements.txt
+```
+
+### Layered Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "Presentation Layer"
+        app["app.py<br/>Entry point"]
+        ui["ui.py<br/>Orchestration"]
+        grid["components/grid.py"]
+        scoring["components/scoring.py"]
+        settings["components/settings_panel.py"]
+        leaderboard["components/leaderboard_panel.py"]
+    end
+
+    subgraph "Application Layer"
+        game_svc["game_service.py"]
+        puzzle_svc["puzzle_service.py"]
+        lb_svc["leaderboard_service.py"]
+        settings_svc["settings_service.py"]
+    end
+
+    subgraph "Domain Layer"
+        models["models.py<br/>Coord, Word, Puzzle"]
+        game_state["game_state.py"]
+        game_config["game_config.py"]
+        game_mode["game_mode.py"]
+        scoring_domain["scoring.py"]
+    end
+
+    subgraph "Infrastructure Layer"
+        storage_backend["storage_backend.py<br/>Protocol"]
+        hf_storage["hf_storage.py"]
+        local_storage["local_storage.py"]
+        audio_backend["audio_backend.py<br/>Protocol"]
+        streamlit_audio["streamlit_audio.py"]
+        word_loader["word_loader.py"]
+        word_gen_ai["word_generator_ai.py"]
+    end
+
+    subgraph "Config Layer"
+        hf_config["hf_config.py"]
+        ai_config["ai_config.py"]
+        app_config["app_config.py"]
+    end
+
+    app --> ui
+    ui --> game_svc
+    ui --> puzzle_svc
+    ui --> lb_svc
+    ui --> settings_svc
+    ui --> grid
+    ui --> scoring
+    ui --> settings
+    ui --> leaderboard
+
+    game_svc --> game_state
+    game_svc --> game_config
+    game_svc --> game_mode
+    game_svc --> scoring_domain
+    game_svc --> storage_backend
+
+    puzzle_svc --> game_config
+    puzzle_svc --> word_loader
+    puzzle_svc --> word_gen_ai
+
+    lb_svc --> storage_backend
+    lb_svc --> game_config
+
+    settings_svc --> storage_backend
+    settings_svc --> game_config
+
+    storage_backend --> hf_storage
+    storage_backend --> local_storage
+
+    audio_backend --> streamlit_audio
+
+    hf_config --> app_config
+    ai_config --> app_config
+```
+
+---
+
+## 2. Fix Single Responsibility Principle (SRP) Violations
+
+### 2.1 `ui.py` — God Module
+
+**Current responsibilities (8+):**
+
+| Responsibility | Lines (approx) | Should Be In |
+|---|---|---|
+| Game logic orchestration | ~200 | `application/game_service.py` |
+| Grid rendering | ~250 | `presentation/components/grid.py` |
+| Settings management | ~150 | `presentation/components/settings_panel.py` |
+| Audio control | ~100 | `infrastructure/audio/streamlit_audio.py` |
+| Leaderboard integration | ~100 | `presentation/components/leaderboard_panel.py` |
+| Word loading | ~50 | `infrastructure/word_loader.py` |
+| Version info | ~30 | `config/app_config.py` |
+| Game storage | ~100 | `infrastructure/storage/` |
+| Session state management | ~100 | `application/session_manager.py` |
+
+**Refactored `ui.py` (after split):**
+
+```python
+# wrdler/presentation/ui.py (after refactoring - ~150 lines)
+import streamlit as st
+from wrdler.application.game_service import GameService
+from wrdler.application.puzzle_service import PuzzleService
+from wrdler.presentation.components.grid import render_grid
+from wrdler.presentation.components.scoring import render_scoring
+from wrdler.presentation.components.settings_panel import render_settings
+from wrdler.presentation.components.leaderboard_panel import render_leaderboard_banner
+
+def run_app():
+    """Orchestrate the main game page."""
+    st.set_page_config(initial_sidebar_state="collapsed")
+    _init_session()
+    
+    render_header()
+    render_leaderboard_banner()
+    render_grid()
+    render_scoring()
+    render_settings()
+    render_footer()
+```
+
+### 2.2 `settings_page.py` — Mixed Concerns
+
+**Current responsibilities:**
+
+| Responsibility | Should Be In |
+|---|---|
+| Settings persistence | `application/settings_service.py` |
+| Word list management | `infrastructure/word_loader.py` |
+| Audio configuration | `infrastructure/audio/` |
+| UI rendering | `presentation/components/settings_panel.py` |
+
+### 2.3 `game_storage.py` — Mixed Concerns
+
+**Current responsibilities:**
+
+| Responsibility | Should Be In |
+|---|---|
+| Serialization | `application/serializer.py` |
+| HF storage | `infrastructure/storage/hf_storage.py` |
+| UID generation | `application/game_service.py` |
+| Difficulty computation | `infrastructure/word_loader.py` |
+
+---
+
+## 3. Fix Open/Closed Principle (OCP) Violations
+
+### 3.1 Hardcoded Game Modes
+
+**Current code (logic.py):**
+
+```python
+# BAD: String literals scattered everywhere
+if state.game_mode in ("easy", "too easy"):
+    state.can_guess = True
+else:
+    state.can_guess = state.can_guess or (ch != "·")
+```
+
+**Refactored:**
+
+```python
+# config/game_mode.py
+from abc import ABC, abstractmethod
+
+class GameMode(ABC):
+    @abstractmethod
+    def allows_consecutive_guesses(self) -> bool: ...
+    @abstractmethod
+    def name(self) -> str: ...
+
+class ClassicMode(GameMode):
+    def allows_consecutive_guesses(self) -> bool: return True
+    def name(self) -> str: return "classic"
+
+class TooEasyMode(GameMode):
+    def allows_consecutive_guesses(self) -> bool: return False
+    def name(self) -> str: return "too easy"
+
+# application/game_service.py
+class GameService:
+    def __init__(self, mode: GameMode, config: GameConfig):
+        self.mode = mode  # Open to new modes, closed to modification
+
+    def on_reveal(self, state: GameState, letter: str) -> None:
+        if self.mode.allows_consecutive_guesses():
+            state.can_guess = state.can_guess or (letter != "·")
+        else:
+            state.can_guess = True  # Any reveal allows a guess
+```
+
+### 3.2 Hardcoded Scoring Tiers
+
+**Current code (logic.py):**
+
+```python
+# BAD: Magic numbers scattered
+if score >= 45:
+    tier = "Legendary"
+elif score >= 42:
+    tier = "Fantastic"
+elif score >= 39:
+    tier = "Great"
+elif score >= 34:
+    tier = "Good"
+else:
+    tier = "OK"
+```
+
+**Refactored:**
+
+```python
+# domain/scoring.py
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class ScoringTier:
+    min_score: int
+    name: str
+
+class ScoringSystem:
+    TIERS: tuple[ScoringTier, ...] = (
+        ScoringTier(45, "Legendary"),
+        ScoringTier(42, "Fantastic"),
+        ScoringTier(39, "Great"),
+        ScoringTier(34, "Good"),
+    )
+    DEFAULT_TIER = ScoringTier(0, "OK")
+
+    @classmethod
+    def compute_tier(cls, score: int) -> ScoringTier:
+        for tier in cls.TIERS:
+            if score >= tier.min_score:
+                return tier
+        return cls.DEFAULT_TIER
+
+    @classmethod
+    def is_legendary(cls, score: int) -> bool:
+        return score >= cls.TIERS[0].min_score  # 45
+```
+
+### 3.3 Hardcoded Grid Dimensions
+
+**Current code (scattered across models.py, generator.py, logic.py, constants.py):**
+
+```python
+# BAD: Magic numbers everywhere
+grid_rows = 6
+grid_cols = 8
+```
+
+**Refactored:**
+
+```python
+# domain/game_config.py
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class GameConfig:
+    grid_rows: int = 6
+    grid_cols: int = 8
+    words_per_puzzle: int = 6
+    word_distribution: tuple[int, ...] = (2, 2, 2)  # lengths 4, 5, 6
+    free_letters: int = 2
+    max_incorrect: int = 10
+    max_generation_attempts: int = 5000
+    min_words_per_length: int = 500
+    default_spacer: int = 1
+    scoring_tiers: tuple[ScoringTier, ...] = ScoringSystem.TIERS
+    max_display_entries: int = 25
+```
+
+---
+
+## 4. Fix Dependency Inversion Principle (DIP) Violations
+
+### Current Dependency Graph (Problematic)
+
+```mermaid
+graph LR
+    ui["ui.py"] --> st["streamlit<br/>(direct)"]
+    game_storage["game_storage.py"] --> hf["huggingface_hub<br/>(direct)"]
+    audio["audio.py"] --> st["streamlit.components<br/>(direct)"]
+    leaderboard["leaderboard.py"] --> hf["huggingface_hub<br/>(direct)"]
+    word_loader["word_loader.py"] --> stdlib["importlib.resources<br/>(direct)"]
+```
+
+### Refactored Dependency Graph
+
+```mermaid
+graph LR
+    ui["ui.py"] --> game_svc["game_service.py"]
+    game_svc --> storage["StorageBackend<br/>(Protocol)"]
+    storage --> hf_impl["HuggingFaceStorage"]
+    storage --> local_impl["LocalStorage"]
+    
+    game_svc --> audio["AudioBackend<br/>(Protocol)"]
+    audio --> streamlit_impl["StreamlitAudio"]
+    
+    game_svc --> config["GameConfig<br/>(frozen dataclass)"]
+```
+
+### Protocol Definitions
+
+```python
+# infrastructure/storage/storage_backend.py
+from typing import Protocol, dict, Optional
+
+class StorageBackend(Protocol):
+    """Abstract storage interface — DIP in action."""
+    
+    async def save(self, key: str, data: dict) -> bool: ...
+    async def load(self, key: str) -> dict | None: ...
+    async def delete(self, key: str) -> bool: ...
+    async def list_folders(self, prefix: str) -> list[str]: ...
+
+# infrastructure/storage/hf_storage.py
+class HuggingFaceStorage(StorageBackend):
+    """HuggingFace dataset storage implementation."""
+    
+    def __init__(self, repo_id: str, token: str):
+        self.repo_id = repo_id
+        self.token = token  # Injected, not hardcoded
+    
+    async def save(self, key: str, data: dict) -> bool:
+        # Uses self.repo_id and self.token
+        ...
+
+# infrastructure/storage/local_storage.py
+class LocalStorage(StorageBackend):
+    """Local file system storage implementation."""
+    
+    def __init__(self, base_dir: Path):
+        self.base_dir = base_dir  # Injected, not hardcoded
+    
+    async def save(self, key: str, data: dict) -> bool:
+        # Uses self.base_dir
+        ...
+
+# application/game_service.py — depends on abstraction, not concrete
+class GameService:
+    def __init__(
+        self,
+        storage: StorageBackend,  # Injected
+        config: GameConfig,       # Injected
+        audio: AudioBackend,      # Injected
+    ):
+        self.storage = storage
+        self.config = config
+        self.audio = audio
+```
+
+---
+
+## 5. Fix Interface Segregation Principle (ISP) Violations
+
+### Current `GameState` — God Class
+
+```mermaid
+classDiagram
+    class GameState {
+        +int grid_rows
+        +int grid_cols
+        +Puzzle puzzle
+        +Set~Coord~ revealed
+        +Set~str~ guessed
+        +int score
+        +str last_action
+        +bool can_guess
+        +str game_mode
+        +Dict~str, int~ points_by_word
+        +datetime start_time
+        +datetime end_time
+    }
+    
+    note for GameState "11 fields across 6 concerns"
+    
+    class GameProgress {
+        +frozenset~Coord~ revealed
+        +frozenset~str~ guessed
+        +int score
+        +dict~str, int~ points_by_word
+        +str last_action
+    }
+    
+    class GameTiming {
+        +datetime~None~ start_time
+        +datetime~None~ end_time
+    }
+    
+    class GameMode {
+        <<interface>>
+        +allows_consecutive_guesses~bool~
+        +name~str~
+    }
+    
+    GameState --> GameProgress : contains
+    GameState --> GameTiming : contains
+    GameState --> GameMode : uses
+```
+
+### Refactored Value Objects
+
+```python
+# domain/game_state.py
+from dataclasses import dataclass
+from typing import frozenset
+
+@dataclass(frozen=True)
+class GameProgress:
+    """Immutable game progress snapshot."""
+    revealed: frozenset[Coord]
+    guessed: frozenset[str]
+    score: int
+    points_by_word: dict[str, int]
+    last_action: str
+
+@dataclass(frozen=True)
+class GameTiming:
+    """Immutable game timing."""
+    start_time: datetime | None
+    end_time: datetime | None
+
+@dataclass
+class GameState:
+    """Mutable game state with focused concerns."""
+    progress: GameProgress
+    timing: GameTiming
+    puzzle: Puzzle
+    game_mode: GameMode
+    can_guess: bool
+
+    def advance_score(self, points: int) -> None:
+        """Mutate progress immutably — returns new state."""
+        new_progress = GameProgress(
+            revealed=self.progress.revealed,
+            guessed=self.progress.guessed,
+            score=self.progress.score + points,
+            points_by_word=dict(self.progress.points_by_word),
+            last_action=f"Scored {points} points.",
+        )
+        object.__setattr__(self, "progress", new_progress)
+```
+
+---
+
+## 6. Eliminate Magic Numbers
+
+### Magic Number Inventory
+
+| Magic Number | Meaning | Current Locations | Should Be |
+|---|---|---|---|
+| `6` | grid_rows | `models.py`, `generator.py`, `logic.py`, `constants.py` | `GameConfig.grid_rows` |
+| `8` | grid_cols | `models.py`, `generator.py`, `logic.py`, `constants.py` | `GameConfig.grid_cols` |
+| `5000` | max_attempts | `generator.py` | `GameConfig.max_generation_attempts` |
+| `25` | max_display_entries | `constants.py`, `leaderboard.py` | `GameConfig.max_display_entries` |
+| `45` | Legendary threshold | `logic.py`, `ui.py`, `hall_of_legends.py` | `ScoringSystem.TIERS[0].min_score` |
+| `42` | Fantastic threshold | `logic.py` | `ScoringSystem.TIERS[1].min_score` |
+| `39` | Great threshold | `logic.py` | `ScoringSystem.TIERS[2].min_score` |
+| `34` | Good threshold | `logic.py` | `ScoringSystem.TIERS[3].min_score` |
+| `500` | MIN_REQUIRED | `word_loader.py` | `GameConfig.min_words_per_length` |
+| `10` | max_incorrect_guesses | `constants.py`, `logic.py` | `GameConfig.max_incorrect` |
+| `2` | free_letters_count | `constants.py`, `logic.py` | `GameConfig.free_letters` |
+| `6` | words_per_puzzle | `constants.py`, `generator.py` | `GameConfig.words_per_puzzle` |
+| `1` | default_spacer | `constants.py`, `generator.py` | `GameConfig.default_spacer` |
+
+### Refactored Configuration
+
+```python
+# domain/game_config.py
+@dataclass(frozen=True)
+class GameConfig:
+    """Centralized game configuration — eliminates all magic numbers."""
+    # Grid
+    grid_rows: int = 6
+    grid_cols: int = 8
+    words_per_puzzle: int = 6
+    word_distribution: tuple[int, ...] = (2, 2, 2)  # lengths 4, 5, 6
+    
+    # Gameplay
+    free_letters: int = 2
+    max_incorrect: int = 10
+    default_spacer: int = 1
+    max_generation_attempts: int = 5000
+    min_words_per_length: int = 500
+    
+    # Display
+    max_display_entries: int = 25
+    
+    # Scoring
+    scoring_tiers: tuple[ScoringTier, ...] = (
+        ScoringTier(45, "Legendary"),
+        ScoringTier(42, "Fantastic"),
+        ScoringTier(39, "Great"),
+        ScoringTier(34, "Good"),
+    )
+```
+
+---
+
+## 7. Consolidate Constants
+
+### Current `constants.py` — Three Unrelated Concerns
+
+```mermaid
+graph TB
+    subgraph "constants.py (MIXED)"
+        hf["HF Config<br/>HF_API_TOKEN<br/>HF_REPO_ID<br/>SPACE_NAME<br/>SHORTENER_JSON_FILE<br/>USE_HF_WORDS<br/>HF_WORD_LIST_REPO_ID<br/>MAX_DISPLAY_ENTRIES<br/>HALL_OF_LEGENDS_FILE"]
+        ai["AI Config<br/>AI_MODELS<br/>DEFAULT_MODEL_NAME<br/>MAX_NEW_TOKENS"]
+        app["App Settings<br/>game_title<br/>show_incorrect_guesses<br/>enable_free_letters<br/>sound_effects_enabled<br/>music_enabled<br/>grid_rows<br/>grid_cols<br/>..."]
+    end
+```
+
+### Refactored Configuration
+
+```
+wrdler/config/
+├── __init__.py
+├── constants.py        # App-wide constants (version, etc.)
+├── hf_config.py        # HF credentials and repo IDs
+├── ai_config.py        # AI model settings
+└── app_config.py       # Application defaults
+```
+
+```python
+# config/hf_config.py
+@dataclass(frozen=True)
+class HFConfig:
+    api_token: str
+    repo_id: str = "Surn/Storage"
+    space_name: str = "Surn/Wrdler"
+    shortener_json_file: str = "shortener.json"
+    use_hf_words: bool = False
+    word_list_repo_id: str = "ysharma/Chat_with_Meta_llama3_1_8b"
+    hall_of_legends_file: str = "games/wrdler_hall_of_legends.json"
+    
+    @classmethod
+    def from_env(cls) -> "HFConfig":
+        return cls(
+            api_token=os.getenv("HF_API_TOKEN", ""),
+            repo_id=os.getenv("HF_REPO_ID", "Surn/Storage"),
+            space_name=os.getenv("SPACE_NAME", "Surn/Wrdler"),
+            use_hf_words=os.getenv("USE_HF_WORDS", "false").lower() == "true",
+            word_list_repo_id=os.getenv("HF_WORD_LIST_REPO_ID", "ysharma/Chat_with_Meta_llama3_1_8b"),
+            hall_of_legends_file=os.getenv("HALL_OF_LEGENDS_FILE", "games/wrdler_hall_of_legends.json"),
+        )
+
+# config/ai_config.py
+@dataclass(frozen=True)
+class AIConfig:
+    models: tuple[str, ...] = (
+        "microsoft/Phi-3-mini-4k-instruct",
+        "meta-llama/Llama-3.1-8B-Instruct",
+        "google/gemma-2b-it",
+        "distilbert/distilgpt2",
+        "mistralai/Mistral-7B-Instruct-v0.3",
+        "NousResearch/Hermes-2-Pro-Llama-3-8B",
+    )
+    default_model: str = "meta-llama/Llama-3.1-8B-Instruct"
+    max_new_tokens: int = 512
+
+# config/app_config.py
+@dataclass(frozen=True)
+class AppConfig:
+    game_title: str = "Wrdler"
+    show_incorrect_guesses: bool = True
+    enable_free_letters: bool = False
+    show_challenge_links: bool = True
+    sound_effects_enabled: bool = True
+    sound_effects_volume: int = 30
+    music_enabled: bool = False
+    music_volume: int = 10
+    default_wordlist: str = "classic.txt"
+    default_game_mode: str = "classic"
+    max_display_entries: int = 25
+```
+
+---
+
+## 8. Reduce `st.session_state` as Global State
+
+### Current Problem
+
+```mermaid
+graph LR
+    ui["ui.py"] --> ss["st.session_state<br/>(global state)]
+    logic["logic.py"] --> ss
+    generator["generator.py"] --> ss
+    word_loader["word_loader.py"] --> ss
+    leaderboard["leaderboard.py"] --> ss
+    settings_page["settings_page.py"] --> ss
+```
+
+### Refactored Session State Manager
+
+```python
+# application/session_manager.py
+class SessionStateManager:
+    """Centralized session state management — replaces direct st.session_state access."""
+    
+    def __init__(self):
+        self._state = st.session_state
+    
+    # --- Game settings ---
+    @property
+    def game_mode(self) -> GameMode:
+        mode_str = self._state.get("game_mode", "classic")
+        return ClassicMode() if mode_str == "classic" else TooEasyMode()
+    
+    @game_mode.setter
+    def game_mode(self, mode: GameMode) -> None:
+        self._state["game_mode"] = mode.name()
+    
+    @property
+    def wordlist_source(self) -> str:
+        return self._state.get("selected_wordlist", "classic.txt")
+    
+    @wordlist_source.setter
+    def wordlist_source(self, source: str) -> None:
+        self._state["selected_wordlist"] = source
+    
+    # --- Game state ---
+    @property
+    def score(self) -> int:
+        return int(self._state.get("score", 0))
+    
+    @score.setter
+    def score(self, value: int) -> None:
+        self._state["score"] = value
+    
+    # --- Settings ---
+    @property
+    def show_incorrect_guesses(self) -> bool:
+        return self._state.get("show_incorrect_guesses", True)
+    
+    @show_incorrect_guesses.setter
+    def show_incorrect_guesses(self, value: bool) -> None:
+        self._state["show_incorrect_guesses"] = value
+    
+    # --- Convenience ---
+    @property
+    def game_service(self) -> GameService:
+        """Dependency injection: returns a configured GameService."""
+        return GameService(
+            storage=self._resolve_storage(),
+            config=GameConfig(),
+            audio=self._resolve_audio(),
+        )
+    
+    def clear(self) -> None:
+        """Clear all session state (new game)."""
+        self._state.clear()
+```
+
+---
+
+## 9. Consolidate Overlapping Modules
+
+### Current Overlaps
+
+```mermaid
+graph TB
+    subgraph "Storage (3 modules)"
+        gs["game_storage.py<br/>HF + serialization<br/>+ UID + difficulty"]
+        ls["local_storage.py<br/>Local file storage"]
+        sm["modules/storage.py<br/>Generic HF storage"]
+    end
+    
+    subgraph "Leaderboard (2 modules)"
+        lb["leaderboard.py<br/>Leaderboard logic"]
+        lp["leaderboard_page.py<br/>Leaderboard UI"]
+    end
+    
+    subgraph "Audio (2 modules)"
+        au["audio.py<br/>Audio playback"]
+        snd["sounds.py<br/>Sound effects"]
+    end
+```
+
+### Consolidation Plan
+
+| Overlap | Merge Into | Action |
+|---|---|---|
+| `game_storage.py` + `modules/storage.py` | `infrastructure/storage/hf_storage.py` | Merge HF storage, extract serialization to `application/serializer.py` |
+| `local_storage.py` | `infrastructure/storage/local_storage.py` | Rename and implement `StorageBackend` |
+| `leaderboard.py` + `leaderboard_page.py` | `application/leaderboard_service.py` + `presentation/components/leaderboard_panel.py` | Split logic and UI |
+| `audio.py` + `sounds.py` | `infrastructure/audio/streamlit_audio.py` | Merge into single module |
+
+---
+
+## 10. Add Configuration Validation
+
+### Current Problem
+
+```python
+# BAD: Silent fallback, no validation
+HF_API_TOKEN = os.getenv("HF_API_TOKEN", None)  # None is silent
+HF_REPO_ID = os.getenv("HF_REPO_ID", "Surn/Storage")  # Wrong default may be used
+```
+
+### Refactored Validation
+
+```python
+# config/hf_config.py
+class ConfigurationError(Exception):
+    """Raised when required configuration is missing."""
+    pass
+
+@dataclass(frozen=True)
+class HFConfig:
+    api_token: str
+    repo_id: str
+    
+    @classmethod
+    def from_env(cls) -> "HFConfig":
+        token = os.getenv("HF_API_TOKEN")
+        if not token:
+            raise ConfigurationError(
+                "HF_API_TOKEN is required for challenge mode. "
+                "Set it in .env or environment variables."
+            )
+        repo_id = os.getenv("HF_REPO_ID")
+        if not repo_id:
+            raise ConfigurationError(
+                "HF_REPO_ID is required for challenge mode. "
+                "Set it in .env or environment variables."
+            )
+        return cls(api_token=token, repo_id=repo_id)
+
+# config/app_config.py
+@dataclass(frozen=True)
+class AppConfig:
+    game_title: str = "Wrdler"
+    # ... other settings
+    
+    @classmethod
+    def from_env_and_file(cls) -> "AppConfig":
+        settings_path = Path(__file__).parent.parent.parent / "settings.json"
+        defaults = cls._load_defaults()
+        
+        if settings_path.exists():
+            with open(settings_path, "r") as f:
+                overrides = json.load(f)
+            # Merge defaults with overrides
+            for key, value in overrides.items():
+                if hasattr(cls, key):
+                    defaults[key] = value
+        
+        return cls(**defaults)
+```
+
+---
+
+## Prioritized Refactoring Roadmap
+
+### Phase 0: Foundation (P0 — Do First)
+
+| # | Action | Effort | Impact | Files |
+|---|--------|--------|--------|-------|
+| 1 | Create `GameConfig` dataclass | Small | High | `domain/game_config.py` |
+| 2 | Create `ScoringSystem` class | Small | High | `domain/scoring.py` |
+| 3 | Create `GameMode` strategy interface | Small | High | `domain/game_mode.py` |
+
+**Why first:** These are small, self-contained changes that eliminate magic numbers and hardcoded strings across the entire codebase. They provide immediate value with minimal risk.
+
+### Phase 1: Architecture Boundaries (P1 — High Impact)
+
+| # | Action | Effort | Impact | Files |
+|---|--------|--------|--------|-------|
+| 4 | Introduce `StorageBackend` Protocol | Medium | High | `infrastructure/storage/storage_backend.py` |
+| 5 | Extract `HuggingFaceStorage` implementation | Medium | High | `infrastructure/storage/hf_storage.py` |
+| 6 | Extract `LocalStorage` implementation | Medium | High | `infrastructure/storage/local_storage.py` |
+| 7 | Create `GameService` with injected dependencies | Medium | High | `application/game_service.py` |
+
+**Why second:** These establish the architectural boundaries that all future work depends on. DIP is the foundation for testability.
+
+### Phase 2: UI Decomposition (P2 — Large Effort)
+
+| # | Action | Effort | Impact | Files |
+|---|--------|--------|--------|-------|
+| 8 | Split `ui.py` into components | Large | High | `presentation/components/` |
+| 9 | Create `SessionStateManager` | Medium | Medium | `application/session_manager.py` |
+| 10 | Split `settings_page.py` | Medium | Medium | `presentation/components/settings_panel.py` |
+
+**Why third:** The UI split is the largest change but depends on phases 0 and 1 being complete.
+
+### Phase 3: Cleanup (P3 — Low Risk)
+
+| # | Action | Effort | Impact | Files |
+|---|--------|--------|--------|-------|
+| 11 | Split `constants.py` | Small | Low | `config/` |
+| 12 | Consolidate storage modules | Medium | Medium | `infrastructure/storage/` |
+| 13 | Consolidate audio modules | Small | Low | `infrastructure/audio/` |
+| 14 | Split `leaderboard.py` / `leaderboard_page.py` | Medium | Medium | `application/` + `presentation/` |
+| 15 | Add configuration validation | Small | Low | `config/` |
+
+---
+
+## Risk Assessment
+
+| Risk | Likelihood | Mitigation |
+|---|---|---|
+| Breaking existing game logic | Medium | Comprehensive test suite before refactoring |
+| Streamlit compatibility issues | Low | Keep Streamlit coupling in `infrastructure/audio/` only |
+| HF storage migration complexity | Medium | Implement both backends in parallel, feature flag |
+| Session state migration | Medium | `SessionStateManager` wraps existing state, no data loss |
+| Team adoption resistance | Medium | Incremental rollout, document each phase |
+
+---
+
+## Expected Outcomes
+
+| Metric | Before | After |
+|--------|--------|-------|
+| `ui.py` lines | ~1000+ | ~150 (orchestration only) |
+| Largest file | `ui.py` (~1000 lines) | `game_service.py` (~300 lines) |
+| Magic numbers | 13+ scattered | 0 (all in `GameConfig`) |
+| Testability | Impossible (global state) | Full unit test coverage |
+| New game mode cost | Modify 5+ files | Add 1 class (`GameMode` impl) |
+| New storage backend cost | Modify 3+ files | Add 1 class (`StorageBackend` impl) |
+| SOLID compliance | 0/5 principles | 5/5 principles |
+
+---
+
+## Appendix A: File-by-File Migration Map
+
+| Current File | New Location | Action |
+|---|---|---|
+| `wrdler/models.py` | `wrdler/domain/models.py` | Move + split `GameState` |
+| `wrdler/logic.py` | `wrdler/application/game_service.py` | Move game mechanics |
+| `wrdler/generator.py` | `wrdler/application/puzzle_service.py` | Move puzzle generation |
+| `wrdler/ui.py` | `wrdler/presentation/ui.py` + `components/` | Split into orchestration + components |
+| `wrdler/settings_page.py` | `wrdler/presentation/components/settings_panel.py` | Keep UI only |
+| `wrdler/leaderboard.py` | `wrdler/application/leaderboard_service.py` | Keep logic only |
+| `wrdler/leaderboard_page.py` | `wrdler/presentation/components/leaderboard_panel.py` | Keep UI only |
+| `wrdler/game_storage.py` | `wrdler/infrastructure/storage/hf_storage.py` | Keep HF storage only |
+| `wrdler/local_storage.py` | `wrdler/infrastructure/storage/local_storage.py` | Keep local storage only |
+| `wrdler/word_loader.py` | `wrdler/infrastructure/word_loader.py` | Keep, simplify |
+| `wrdler/word_loader_ai.py` | `wrdler/infrastructure/word_generator_ai.py` | Keep, rename |
+| `wrdler/audio.py` | `wrdler/infrastructure/audio/streamlit_audio.py` | Keep, rename |
+| `wrdler/sounds.py` | `wrdler/infrastructure/audio/streamlit_audio.py` | Merge into audio.py |
+| `wrdler/ui_helpers.py` | `wrdler/presentation/ui_helpers.py` | Keep, trim down |
+| `wrdler/hall_of_legends.py` | `wrdler/presentation/components/hall_of_legends_panel.py` | Keep UI only |
+| `wrdler/oauth.py` | `wrdler/infrastructure/oauth.py` | Keep, move |
+| `wrdler/version_info.py` | `wrdler/config/version_info.py` | Keep, move |
+| `wrdler/modules/constants.py` | `wrdler/config/` (split into 3 files) | Split |
+| `wrdler/modules/storage.py` | `wrdler/infrastructure/storage/hf_storage.py` | Merge |
+| `wrdler/modules/file_utils.py` | `wrdler/infrastructure/file_utils.py` | Keep, move |
+
+---
+
+## Appendix B: Mermaid — Before/After Dependency Comparison
+
+### Before (Tight Coupling)
+
+```mermaid
+graph TB
+    subgraph "All files depend on everything"
+        ui["ui.py<br/>~1000 lines"]
+        logic["logic.py"]
+        generator["generator.py"]
+        game_storage["game_storage.py"]
+        leaderboard["leaderboard.py"]
+        settings["settings_page.py"]
+        word_loader["word_loader.py"]
+        constants["constants.py"]
+        storage_mod["modules/storage.py"]
+    end
+    
+    ui --> logic
+    ui --> generator
+    ui --> game_storage
+    ui --> leaderboard
+    ui --> settings
+    ui --> word_loader
+    ui --> constants
+    ui --> storage_mod
+    
+    game_storage --> storage_mod
+    game_storage --> constants
+    leaderboard --> storage_mod
+    leaderboard --> constants
+    settings --> constants
+    word_loader --> constants
+```
+
+### After (Clean Dependencies)
+
+```mermaid
+graph TB
+    subgraph "presentation"
+        ui["ui.py<br/>~150 lines<br/>Orchestration"]
+        grid["components/grid.py"]
+        scoring["components/scoring.py"]
+        settings["components/settings_panel.py"]
+        leaderboard["components/leaderboard_panel.py"]
+    end
+    
+    subgraph "application"
+        game_svc["game_service.py"]
+        puzzle_svc["puzzle_service.py"]
+        lb_svc["leaderboard_service.py"]
+        settings_svc["settings_service.py"]
+        session_mgr["session_manager.py"]
+    end
+    
+    subgraph "domain"
+        game_config["game_config.py"]
+        game_mode["game_mode.py"]
+        scoring_domain["scoring.py"]
+        game_state["game_state.py"]
+        models["models.py"]
+    end
+    
+    subgraph "infrastructure"
+        storage_backend["storage_backend.py<br/>Protocol"]
+        hf_storage["hf_storage.py"]
+        local_storage["local_storage.py"]
+        audio_backend["audio_backend.py<br/>Protocol"]
+        streamlit_audio["streamlit_audio.py"]
+        word_loader["word_loader.py"]
+        word_gen_ai["word_generator_ai.py"]
+    end
+    
+    subgraph "config"
+        hf_config["hf_config.py"]
+        ai_config["ai_config.py"]
+        app_config["app_config.py"]
+    end
+    
+    ui --> game_svc
+    ui --> puzzle_svc
+    ui --> lb_svc
+    ui --> settings_svc
+    ui --> grid
+    ui --> scoring
+    ui --> settings
+    ui --> leaderboard
+    
+    game_svc --> game_state
+    game_svc --> game_config
+    game_svc --> game_mode
+    game_svc --> scoring_domain
+    game_svc --> storage_backend
+    
+    puzzle_svc --> game_config
+    puzzle_svc --> word_loader
+    puzzle_svc --> word_gen_ai
+    
+    lb_svc --> storage_backend
+    lb_svc --> game_config
+    
+    settings_svc --> storage_backend
+    settings_svc --> game_config
+    
+    storage_backend --> hf_storage
+    storage_backend --> local_storage
+    
+    audio_backend --> streamlit_audio
+    
+    hf_config --> app_config
+    ai_config --> app_config
+```
+
+---
+
+## Appendix C: Key Design Decisions
+
+### Decision 1: Keep Streamlit Coupling in Infrastructure Layer
+
+**Rationale:** Streamlit is the deployment target. Abstracting it would add unnecessary complexity. Instead, keep all Streamlit imports in `presentation/` and `infrastructure/audio/` only.
+
+### Decision 2: Use Protocols (not ABCs) for Storage Backend
+
+**Rationale:** Python's `typing.Protocol` provides structural subtyping (duck typing) without inheritance overhead. It's the modern Pythonic way to define interfaces.
+
+### Decision 3: Frozen Dataclasses for Configuration
+
+**Rationale:** `@dataclass(frozen=True)` makes configuration immutable at the type level, preventing accidental mutation and enabling thread safety.
+
+### Decision 4: Incremental Migration
+
+**Rationale:** Each phase should be independently deployable. Phase 0 changes are purely additive (new files). Phase 1 introduces interfaces but keeps old implementations as adapters. Phase 2+ do the actual migration.
+
+---
+
+*Document generated: 2026-04-17 | Wrdler v0.3.2*