System Glossary: Expo Migration

# System Glossary: Expo Migration
## 0.1.2 - Terminology Reference

Version: 1.0.0
Last Updated: 2026-01-04
Status: LOCKED (Phase Zero Complete)

---

Document Purpose

This glossary defines every core term used throughout the Expo migration project. Each definition specifies:
- What the term is
- What it is not
- What layer it belongs to (conceptual, architectural, runtime, data)

No overloaded or ambiguous language is permitted beyond this document.

---

Layer Classifications

---

Core Game Terms

### Card
- Is: A digital representation of a wisdom passage with gameplay attributes (power, cost, abilities, themes)
- Is Not: A physical card (though physical counterparts exist), a generic UI element
- Layer: Data
- Properties: id, title, type, rarity, themes, emotionalPower, wisdomCost, abilities
- Expo Equivalent: TypeScript interface `Card` in `types/card.ts`

### Card Type
- Is: Classification determining power multiplier and gameplay role
- Is Not: Visual styling, rarity level
- Layer: Data
- Values: Wisdom (1.0x), Poem (1.5x), Reflection (1.2x), Theme (1.3x), Custom (1.0x)
- Expo Equivalent: TypeScript enum `CardType`

### Rarity
- Is: Scarcity classification affecting drop rates and deck limits
- Is Not: Power level (though correlated), visual-only distinction
- Layer: Data
- Values: Common (60
- Expo Equivalent: TypeScript enum `Rarity`

### Theme
- Is: Emotional archetype (one of 12) that defines synergy/counter relationships
- Is Not: Visual theme, color scheme alone
- Layer: Conceptual, Data
- Values: Time, Hope, Passion, Fulfillment, Confidence, Healing, Potential, Transcendence, Freedom, Equality, Accountability, Forgiveness
- Expo Equivalent: TypeScript enum `Theme` in `types/theme.ts`

### Synergy
- Is: Bonus (+8 power) when specific theme pairs are played together
- Is Not: Random bonus, counter relationship
- Layer: Runtime
- Example: Hope + Healing = "Recovery Boost" synergy
- Expo Equivalent: Function `calculateSynergy()` in `engine/themeInteraction.ts`

### Counter
- Is: Relationship where one theme overpowers another (+10 power to counter, -8 to countered)
- Is Not: Synergy, neutral relationship
- Layer: Runtime
- Pairs: Freedom counters Accountability, Passion counters Time (bidirectional)
- Expo Equivalent: Function `calculateCounter()` in `engine/themeInteraction.ts`

### Emotional Power
- Is: Base strength value (10-100) of a card, modified by type multiplier
- Is Not: Wisdom cost, growth points awarded
- Layer: Data
- Expo Equivalent: Property `emotionalPower: number` on Card interface

### Wisdom Cost
- Is: Resource points (0-5) required to play a card
- Is Not: Card power, turn cost
- Layer: Data
- Expo Equivalent: Property `wisdomCost: number` on Card interface

### Wisdom Pool
- Is: Player resource (max 5) used to pay card costs, regenerates +2 per turn
- Is Not: Victory points, hand size
- Layer: Runtime
- Expo Equivalent: Property `wisdomPool: number` in `PlayerBattleState`

---

Battle System Terms

### Battle
- Is: A complete game session between two players with victory condition
- Is Not: Single turn, card interaction only
- Layer: Conceptual, Runtime
- Expo Equivalent: Interface `Battle` in `types/battle.ts`

### Battle Phase
- Is: Discrete stage in turn cycle (8 phases total)
- Is Not: Victory condition, random state
- Layer: Runtime
- Values: SETUP → DRAW → WISDOM → PLAY → RESONANCE → REFLECTION → GROWTH → ENDED
- Expo Equivalent: TypeScript enum `BattlePhase`

### Battle State
- Is: Complete snapshot of battle at any moment (turn, phase, players, cards)
- Is Not: Partial state, UI state only
- Layer: Data, Runtime
- Expo Equivalent: Interface `BattleState` in `types/battle.ts`

### Turn
- Is: One complete cycle through phases for a single player
- Is Not: Single phase, entire battle
- Layer: Runtime
- Expo Equivalent: Property `turn: number` in BattleState

### Resonance Zone
- Is: Active area where cards resolve effects and interact
- Is Not: Hand, deck, discard pile
- Layer: Runtime
- Expo Equivalent: Property `resonanceZone: Card[]` in BattleState

### Growth Points
- Is: Victory resource accumulated from card play, synergies, abilities
- Is Not: Wisdom points, experience points
- Layer: Runtime
- Target: 100 points for Enlightenment victory
- Expo Equivalent: Property `growthPoints: number` in EmotionalState

---

Victory Terms

### Victory Condition
- Is: One of three ways to win a battle
- Is Not: Partial achievement, participation metric
- Layer: Conceptual
- Values: Enlightenment, Wisdom, Resonance
- Expo Equivalent: TypeScript enum `VictoryCondition`

### Enlightenment Victory
- Is: Win by accumulating 100+ Growth Points
- Is Not: Theme-based victory, combo victory
- Layer: Conceptual
- Expo Equivalent: Check `growthPoints >= 100`

### Wisdom Victory
- Is: Win by playing cards from all 12 themes in one battle
- Is Not: High score victory, combo victory
- Layer: Conceptual
- Expo Equivalent: Check `activeThemes.size >= 12`

### Resonance Victory
- Is: Win by triggering 5+ perfect theme synergy combos
- Is Not: Power victory, theme diversity victory
- Layer: Conceptual
- Expo Equivalent: Check `resonanceComboCount >= 5`

---

Ability System Terms

### Card Ability
- Is: Special effect triggered by card under specific conditions
- Is Not: Base power, theme interaction
- Layer: Data, Runtime
- Expo Equivalent: Interface `CardAbility` in `types/card.ts`

### Ability Trigger
- Is: Condition that activates an ability
- Is Not: Effect, result
- Layer: Data
- Values: onPlay, onDiscard, passive, resonance, reflection
- Expo Equivalent: TypeScript enum `AbilityTrigger`

### Ability Effect
- Is: Result of triggered ability (draw, gain wisdom, growth, etc.)
- Is Not: Trigger condition, ability name
- Layer: Runtime
- Values: drawCard, gainWisdom, emotionalGrowth, themeBonus, healingAura, resonanceBoost
- Expo Equivalent: TypeScript enum `AbilityEffect`

### Ability Engine
- Is: Service that processes ability triggers and calculates effects
- Is Not: Battle engine (separate concern), UI component
- Layer: Architectural, Runtime
- Expo Equivalent: Module `engine/abilityEngine.ts`

---

Collection & Deck Terms

### Grimoire
- Is: Player's complete card collection
- Is Not: Active deck, battle hand
- Layer: Conceptual, Data
- Expo Equivalent: Interface `Grimoire` or array of `OwnedCard`

### Deck
- Is: Subset of grimoire (20-40 cards) configured for battle
- Is Not: Full collection, current hand
- Layer: Data
- Constraints: 20-40 cards, max 3 primary themes, rarity limits
- Expo Equivalent: Interface `Deck` in `types/deck.ts`

### Hand
- Is: Cards currently held by player during battle (max 10)
- Is Not: Deck, discard pile, full collection
- Layer: Runtime
- Expo Equivalent: Property `hand: Card[]` in PlayerBattleState

### Card Mastery
- Is: Achievement earned after 10 plays + 5 wins with a card
- Is Not: Ownership, rarity upgrade
- Layer: Data
- Expo Equivalent: Computed property on `OwnedCard`

---

Architecture Terms

### View Model
- Is: (iOS) Class managing UI state and business logic for a screen
- Is Not: UI component, data model
- Layer: Architectural
- Expo Equivalent: Custom hook (e.g., `useBattle()`) or Zustand store slice

### Service Layer
- Is: Abstraction over external dependencies (API, storage)
- Is Not: UI code, business logic
- Layer: Architectural
- Expo Equivalent: Module in `services/` directory (e.g., `supabaseService.ts`)

### State Store
- Is: Centralized application state container (Zustand)
- Is Not: Component local state, database
- Layer: Architectural
- iOS Equivalent: @Published properties in ObservableObject
- Expo Equivalent: Zustand store in `stores/` directory

### Persistence Manager
- Is: Service handling local data storage and sync
- Is Not: Remote API, state store
- Layer: Architectural
- iOS: PersistenceManager (SwiftData)
- Expo Equivalent: AsyncStorage + expo-sqlite wrapper

---

Infrastructure Terms

### Expo Managed Workflow
- Is: Build configuration where Expo handles native code
- Is Not: Bare React Native, custom native modules
- Layer: Infrastructure
- Constraint: Project must stay within managed workflow unless explicitly documented

### EAS Build
- Is: Expo Application Services for cloud builds
- Is Not: Local build, Xcode/Android Studio direct build
- Layer: Infrastructure
- Usage: Production builds for App Store and Google Play

### OTA Update
- Is: Over-The-Air JavaScript bundle update without store submission
- Is Not: Native code update, full app reinstall
- Layer: Infrastructure
- Tool: expo-updates

### CDN (Cloudinary)
- Is: Cloud delivery network for card images and assets
- Is Not: Local bundle, database, code repository
- Layer: Infrastructure
- Current Usage: Card images, GIFs, design assets

---

Data Source Terms

### Supabase
- Is: Backend-as-a-Service providing database, auth, and realtime
- Is Not: Local storage, CDN, state management
- Layer: Infrastructure
- Components Used: PostgreSQL, Auth, Row Level Security
- Expo Client: `@supabase/supabase-js`

### cards.json
- Is: Local JSON file containing all 45 card definitions
- Is Not: Remote API, user data, mutable at runtime
- Layer: Data
- Expo Equivalent: Bundled JSON in `assets/data/cards.json`

### SwiftData / SQLite
- Is: Local persistent storage for user data
- Is Not: Remote database, memory cache
- Layer: Data
- iOS: SwiftData @Model classes
- Expo Equivalent: expo-sqlite with drizzle ORM

### AsyncStorage
- Is: Key-value storage for simple data (settings, tokens)
- Is Not: Relational database, large data storage
- Layer: Data
- Expo Equivalent: `@react-native-async-storage/async-storage`

---

UI Component Terms

### Screen
- Is: Full-page view representing a navigation destination
- Is Not: Reusable component, modal
- Layer: Architectural
- Expo Convention: Files in `app/` directory (Expo Router)

### Component
- Is: Reusable UI element with props interface
- Is Not: Screen, service, store
- Layer: Architectural
- Expo Convention: Files in `components/` directory

### Design Token
- Is: Named value for colors, spacing, typography
- Is Not: Component, style object
- Layer: Architectural
- Expo Location: `constants/tokens.ts`

---

Quality Terms

### Functional Parity
- Is: 100
- Is Not: Visual pixel-perfection, performance match
- Layer: Conceptual
- Validation: Feature checklist comparison

### Performance Parity
- Is: Meeting or exceeding iOS baseline metrics
- Is Not: Identical implementation, feature parity
- Layer: Conceptual
- Metrics: Launch time, FPS, memory, battery

### Type Coverage
- Is: Percentage of code with explicit TypeScript types
- Is Not: Test coverage, comment coverage
- Layer: Infrastructure
- Target: >90

---

Revision History

---

This glossary is the authoritative source for all terminology in the Expo migration project. Any term not defined here should be proposed for addition before use.