Meaning Full Power - Game Mechanics Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         PRESENTATION                             │
│  MainHubView │ BattleArenaView │ GrimoireView │ DeckBuilderView │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                        VIEW MODELS                               │
│     BattleViewModel │ DeckViewModel │ CollectionViewModel       │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                      GAME LOGIC LAYER                           │
│  AbilityEngine │ ThemeInteraction │ VictoryCalculator          │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                        DATA LAYER                                │
│   Card │ Deck │ Battle │ User │ Theme │ GameRules              │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                     PERSISTENCE LAYER                            │
│  PersistenceManager │ SwiftData Models │ Sync Queue            │
└─────────────────────────────────────────────────────────────────┘

Models/
├── Card.swift           # Card, CardType, Rarity, CardAbility, UserCard, Grimoire
├── Deck.swift           # Deck, DeckBuilder
├── Battle.swift         # BattleType, BattlePhase, VictoryCondition, BattleState
├── Theme.swift          # Theme enum, ThemeInteraction
├── User.swift           # User, PlayStyle, EmotionalProfile, UserStats
├── GameRules.swift      # All game constants and rules
├── PersistentModels.swift  # SwiftData @Model classes

Services/
├── AbilityEngine.swift  # Card ability execution
├── PersistenceManager.swift  # Data persistence
├── TutorialManager.swift    # Tutorial flow
├── AIOrchestrator.swift     # AI content generation

struct Card: Identifiable, Codable, Hashable {
    let id: String
    let page: Int                    // 1-127 (book page number)
    let title: String
    let type: CardType
    let rarity: Rarity

    // Content
    let excerpt: String              // Display text
    let fullText: String             // Complete text
    let reflectionQuestion: String?  // For reflection cards

    // Themes (core gameplay)
    let primaryTheme: Theme
    let secondaryThemes: [Theme]

    // Gameplay Attributes
    let emotionalPower: Int          // 10-100
    let wisdomCost: Int              // 0-5
    let abilities: [CardAbility]

    // Visual Assets
    let designPageURL: String?
    let illustrationURL: String?
    let illustrationWithTextURL: String?

    // Metadata
    let chapterTitle: String?
    let isChapterTitle: Bool
    let language: String
}

struct CardAbility: Codable, Identifiable {
    let id: String
    let name: String
    let description: String
    let triggerType: AbilityTrigger
    let effect: AbilityEffect
}

enum AbilityTrigger: String, Codable {
    case onPlay       // When card is played
    case onDiscard    // When card is discarded
    case passive      // Always active
    case resonance    // When themes combine
    case reflection   // When question is answered
}

enum AbilityEffect: String, Codable {
    case drawCard         // Draw 1 card
    case gainWisdom       // +1-2 wisdom
    case emotionalGrowth  // +15-20 growth
    case themeBonus       // +3 per matching theme
    case healingAura      // +5 growth, +1 wisdom
    case resonanceBoost   // 1.5x synergy bonus
}

SETUP → DRAW → WISDOM → PLAY → RESONANCE → REFLECTION → GROWTH → (repeat or ENDED)

struct BattleState: Codable {
    let battleId: String
    var turn: Int                      // Current turn number
    var phase: BattlePhase             // Current phase
    var currentPlayerId: String        // Whose turn

    var player1: PlayerBattleState
    var player2: PlayerBattleState

    var resonanceZone: [Card]          // Cards resolving effects
    var turnTimer: TimeInterval        // 90 seconds per turn
    var lastAction: BattleAction?
    var actionLog: [String]
}

struct PlayerBattleState: Codable, Identifiable {
    let id: String
    let oderId: String
    let nickname: String
    let avatarURL: String?

    var hand: [Card]                   // Cards in hand (max 10)
    var deckCards: [String]            // Remaining deck card IDs
    var discardPile: [Card]            // Discarded cards
    var activeCards: [Card]            // Cards in play zone
    var emotionalState: EmotionalState // Growth tracking
}

struct EmotionalState: Codable {
    var growthPoints: Int = 0              // Target: 100 for victory
    var wisdomPool: Int = 3                // Mana system (max 5)
    var maxWisdom: Int = 5
    var resonanceMultiplier: Double = 1.0  // Synergy bonus
    var activeThemes: Set<Theme> = []      // Themes played this game
    var reflectionBonus: Int = 0           // From answering questions
    var resonanceComboCount: Int = 0       // Target: 5 for victory

    // Victory checks
    var isEnlightened: Bool { growthPoints >= 100 }
    var hasAllThemes: Bool { activeThemes.count >= 12 }
    var hasResonanceVictory: Bool { resonanceComboCount >= 5 }
}

enum BattleAction: Codable {
    case drawCard
    case playCard(cardId: String)
    case activateAbility(cardId: String, abilityId: String)
    case answerReflection(cardId: String, answer: String)
    case endTurn
    case surrender
}

var synergyThemes: [Theme] {
    switch self {
    case .hope: return [.healing, .potential]
    case .healing: return [.hope, .forgiveness]
    case .confidence: return [.potential, .passion]
    case .potential: return [.confidence, .hope]
    case .passion: return [.freedom, .confidence]
    case .freedom: return [.passion, .transcendence]
    case .transcendence: return [.freedom, .time]
    case .time: return [.transcendence, .accountability]
    case .accountability: return [.time, .equality]
    case .equality: return [.accountability, .forgiveness]
    case .forgiveness: return [.equality, .healing]
    case .fulfillment: return [.hope, .passion]
    }
}

var counterThemes: [Theme] {
    switch self {
    case .freedom: return [.accountability]
    case .passion: return [.time]
    case .accountability: return [.freedom]
    case .time: return [.passion]
    default: return []
    }
}

struct ThemeInteraction {
    let theme1: Theme
    let theme2: Theme
    let isSynergy: Bool
    let powerModifier: Int      // +8 synergy, +10 counter, -8 countered

    var bonusMultiplier: Double {
        if isSynergy { return 1.5 }
        if isCounter { return 0.5 }
        return 1.0
    }
}

Card Played
    │
    ▼
Check Trigger Type
    │
    ├── ON_PLAY → Execute immediately
    ├── PASSIVE → Always active
    ├── RESONANCE → Check theme match
    ├── REFLECTION → Check if question answered
    └── ON_DISCARD → Execute when discarded
    │
    ▼
Calculate Effect
    │
    ▼
Return AbilityResult

struct AbilityResult {
    let ability: CardAbility
    let wasTriggered: Bool
    let effects: [EffectResult]

    var totalGrowthGained: Int
    var totalWisdomGained: Int
    var cardsDrawn: Int
}

struct EffectResult {
    let effectType: CardAbility.AbilityEffect
    let description: String
    var growthChange: Int?
    var wisdomChange: Int?
    var cardsDrawn: Int?
    var bonusMultiplier: Double?
}

func calculateThemeSynergy(
    playerCard: Card,
    opponentCard: Card,
    playedPlayerThemes: [Theme]
) -> SynergyResult

struct SynergyResult {
    let playerTheme: Theme
    let opponentTheme: Theme
    let type: SynergyType         // synergy, counter, countered, neutral
    let powerModifier: Int
    let description: String
}

struct Deck: Identifiable, Codable {
    let id: String
    var name: String
    var cardIds: [String]
    var primaryThemes: [Theme]      // Max 3
    let createdAt: Date
    var lastModified: Date
    var winCount: Int
    var lossCount: Int

    var isValid: Bool {
        cardCount >= 20 && cardCount <= 40 && primaryThemes.count <= 3
    }
}

struct DeckBuilder {
    var deck: Deck
    var availableCards: [Card]

    var themeDistribution: [Theme: Int]
    var rarityDistribution: [Rarity: Int]
    var averageWisdomCost: Double
    var averagePower: Double

    func suggestedCards(limit: Int = 5) -> [Card]  // Synergy-based suggestions
    func canAdd(_ card: Card) -> Bool              // Rarity limit check
}

@MainActor
class PersistenceManager: ObservableObject {
    static let shared = PersistenceManager()

    // Published state
    @Published var userProfile: UserProfile?
    @Published var ownedCards: [OwnedCard]
    @Published var savedDecks: [SavedDeck]
    @Published var battleHistory: [BattleRecord]

    // Collection operations
    func unlockCard(_ cardId: String, source: CardSource) -> OwnedCard?
    func recordCardPlayed(_ cardId: String, won: Bool)
    func setFavorite(_ cardId: String, rank: Int?)

    // Deck operations
    func createDeck(name: String, cardIds: [String], primaryTheme: Theme) -> SavedDeck
    func updateDeck(_ deck: SavedDeck, name: String?, cardIds: [String]?)
    func deleteDeck(_ deck: SavedDeck)
    func setActiveDeck(_ deck: SavedDeck)

    // Battle operations
    func recordBattle(...) -> BattleRecord

    // Statistics
    var collectionStats: CollectionStats
    var battleStats: BattleStats
}

// Mastery requires: 10 plays + 5 wins
var isMastered: Bool {
    playCount >= 10 && winCount >= 5
}

var masteryProgress: Double {
    let playProgress = min(Double(playCount) / 10.0, 1.0)
    let winProgress = min(Double(winCount) / 5.0, 1.0)
    return (playProgress + winProgress) / 2.0
}

func checkVictory() -> (winner: String, condition: VictoryCondition)? {
    // Check Enlightenment (100 growth)
    if player.emotionalState.growthPoints >= 100 {
        return (player.id, .enlightenment)
    }

    // Check Wisdom (all 12 themes)
    if player.emotionalState.activeThemes.count >= 12 {
        return (player.id, .wisdom)
    }

    // Check Resonance (5 combos)
    if player.emotionalState.resonanceComboCount >= 5 {
        return (player.id, .resonance)
    }

    return nil
}

class AIOpponent {
    let level: AILevel

    func selectCardToPlay(hand: [Card], wisdom: Int, gameState: BattleState) -> Card? {
        switch level {
        case .novice:
            return selectRandomPlayable(hand: hand, wisdom: wisdom)
        case .apprentice:
            return selectBestThemeMatch(hand: hand, wisdom: wisdom, gameState: gameState)
        case .sage:
            return selectOptimalPlay(hand: hand, wisdom: wisdom, gameState: gameState)
        case .enlightened:
            return selectAdaptivePlay(hand: hand, wisdom: wisdom, gameState: gameState)
        }
    }
}

enum GameRules {
    enum Battle {
        static let startingHandSize = 5
        static let maxHandSize = 10
        static let cardsPerDraw = 1
        static let turnTimeLimit: TimeInterval = 90
    }

    enum Wisdom {
        static let startingPool = 3
        static let maxCapacity = 5
        static let regenPerTurn = 2
    }

    enum Victory {
        static let enlightenmentThreshold = 100
        static let wisdomThemeCount = 12
        static let resonanceComboCount = 5
    }
}

enum Matchmaking {
    static let ratingRange = 200       // Initial ±200 ELO
    static let maxWaitTime = 60        // Seconds before expanding
    static let rangeExpansion = 100    // Expand by ±100 each timeout
}

enum Progression {
    static let masteryPlayCount = 10
    static let ratingPerWin = 25
    static let ratingPerLoss = -15
    static let victoryConditionBonus = 10
}

                    ┌─────────────────┐
                    │   GameRules     │ ◄── Source of truth for all constants
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
   ┌──────────┐       ┌──────────┐       ┌──────────┐
   │  Theme   │ ◄────►│   Card   │ ◄────►│   Deck   │
   └────┬─────┘       └────┬─────┘       └────┬─────┘
        │                  │                  │
        │      ┌───────────┴───────────┐      │
        │      │                       │      │
        ▼      ▼                       ▼      ▼
   ┌──────────────┐              ┌──────────────┐
   │AbilityEngine │◄────────────►│    Battle    │
   └──────┬───────┘              └──────┬───────┘
          │                             │
          │         ┌───────────────────┤
          │         │                   │
          ▼         ▼                   ▼
   ┌──────────────────┐         ┌──────────────┐
   │   BattleState    │         │     User     │
   └────────┬─────────┘         └──────┬───────┘
            │                          │
            └──────────┬───────────────┘
                       │
                       ▼
            ┌─────────────────────┐
            │ PersistenceManager  │ ◄── Persists all game data
            └─────────────────────┘

// 1. Check if can afford
guard emotionalState.spendWisdom(card.wisdomCost) else { return }

// 2. Execute abilities
let results = AbilityEngine.shared.executeOnPlayAbilities(
    card: card,
    playerThemes: activeThemes,
    opponentCard: opponentCard,
    reflectionAnswered: answeredQuestion
)

// 3. Calculate synergies
let synergy = AbilityEngine.shared.calculateThemeSynergy(
    playerCard: card,
    opponentCard: opponentCard,
    playedPlayerThemes: Array(emotionalState.activeThemes)
)

// 4. Update state
emotionalState.activateTheme(card.primaryTheme)
emotionalState.addGrowth(totalGrowth)

// 5. Check victory
if let victory = checkVictory() { endBattle(victory) }

let baseGrowth = card.effectivePower
let synergyBonus = synergy.powerModifier
let abilityBonus = results.reduce(0) { $0 + $1.totalGrowthGained }
let totalGrowth = baseGrowth + synergyBonus + abilityBonus

let battle = Battle(
    id: UUID().uuidString,
    type: .ranked,
    player1Id: user.id,
    player2Id: opponent.id,
    player1DeckId: activeDeck.id,
    player2DeckId: opponentDeck.id,
    state: initialState,
    startedAt: Date()
)