Technical Architecture

A comprehensive overview of the XP App's technical architecture, from entry points to service layers.

---

Technology Stack

Layer	Technology	Purpose
Framework	Vue 3	Reactive UI framework
UI Components	Ionic 7	Cross-platform UI components
State	Pinia	Modern Vue state management
Styling	TailwindCSS + SCSS	Utility-first CSS + custom styles
Native	Capacitor	iOS/Android native bridge
Animations	GSAP	Battle animations & effects
Type Safety	TypeScript	Static type checking

---

Directory Structure

src/
├── main.ts                 # Application entry point
├── app.config.ts           # App configuration
├── router/                 # Vue Router configuration
│   └── game-master.routes.ts
│
├── lib/                    # Core libraries
│   ├── api/                # API clients
│   ├── databases/          # Local data persistence
│   ├── engine/             # Game engine (battle, temples)
│   ├── services/           # Business logic services
│   ├── store/stores/       # Pinia state stores
│   ├── types/              # TypeScript definitions
│   └── utils/              # Utility functions
│
├── components/             # Reusable Vue components
│   ├── atoms/              # Basic UI primitives
│   ├── molecules/          # Composed components
│   └── organisms/          # Complex feature components
│
├── hooks/                  # Vue composables
├── mixins/                 # Legacy Vue mixins
├── constants/              # Application constants
├── styles/                 # Global styles & themes
│
├── views/                  # Page-level components
│   ├── App/                # Core app views
│   │   └── SideMenu/
│   │       └── XpGameMaster/  # Admin/GM views
│   ├── Console/            # Player views
│   │   ├── BattleField/    # Combat system
│   │   ├── MyPortal/       # Player hub
│   │   ├── TempleGrounds/  # Temple exploration
│   │   └── WorldMap/       # Overworld navigation
│   └── Dev/                # Development tools
│
└── assets/                 # Static assets
    ├── audio/              # Sound effects & music
    ├── fonts/              # Typography
    └── images/             # Graphics & icons

---

State Management (Pinia)

All state management uses Pinia stores, located in src/lib/store/stores/:

Core Stores

Store	File	Purpose
useUserStore	user.ts	Authentication, user profiles, GP management
useGameStore	game.ts	Global game state, theme, entity caching
useBattleStore	battle.ts	Battle state, turn management
useAudioStore	audio.ts	Sound effects and music control
useTempleCreatorStore	temple-creator.ts	Temple builder state
useBestiarySelectionStore	bestiary-selection.ts	Beast selection for rooms

Store Pattern

All stores use the Composition API pattern:

import { defineStore } from 'pinia';
import { ref, reactive, computed } from 'vue';

export const useExampleStore = defineStore('example', () => {
  // State
  const items = reactive<Record<string, Item>>({});
  const currentId = ref<string | null>(null);
  
  // Computed
  const currentItem = computed(() => 
    currentId.value ? items[currentId.value] : null
  );
  
  // Actions
  function setItem(item: Item) {
    items[item.id] = item;
  }
  
  return { items, currentId, currentItem, setItem };
});

---

Engine Architecture

The game engine is organized into subsystems under src/lib/engine/:

engine/
├── battle/                 # Combat engine
│   ├── BattleState.ts      # Reactive battle state
│   ├── EnemySpawner.ts     # Schedule-based spawning
│   └── types.ts            # Battle type definitions
│
├── core/                   # Core systems
│   ├── BackgroundManager.ts   # Parallax backgrounds
│   ├── DialogSystem.ts        # Text dialog system
│   ├── abilities/             # Ability system
│   └── dungeons/              # Temple engine
│       ├── TempleSystem.ts    # Main temple logic
│       ├── DungeonManager.ts  # Multi-floor management
│       ├── ChestSystem.ts     # Treasure chest logic
│       └── types.ts           # Dungeon types
│
├── dungeons/               # Room configuration
│   ├── roomTypes.ts        # Room type definitions
│   ├── roomIcons.ts        # Visual icons
│   └── templeIcons.ts      # Per-temple icons
│
└── temples/                # Static temple definitions
    ├── water-temple.ts
    ├── fire-temple.ts
    └── ... (9 temples)

---

Service Layer

Business logic is encapsulated in services under src/lib/services/:

Service	Path	Purpose
BattleService	battle/BattleService.ts	Turn-based combat logic
BestiaryService	battle/BestiaryService.ts	Monster data management
GPService	gp/GPService.ts	Gold Points persistence
PlayerStatsService	stats/PlayerStatsService.ts	HP/MP calculations

BattleService

The central combat service managing all battle interactions:

class BattleService {
  // Initialize battle
  initBattle(enemy: Enemy): void
  initMultiBattle(enemies: Enemy[], userIds?: string[]): void
  
  // Actions
  handleBattleAction(action: string): BattleResult
  handleAttack(): BattleResult
  handleDefend(): BattleResult
  handleRun(): BattleResult
  
  // Turn management
  startPlayerTurn(): void
  endPlayerTurn(): void
  performEnemyTurn(): void
  
  // State
  getState(): BattleState
  setBattleMessage(message: string): void
}

---

Component Architecture

Components follow an Atomic Design hierarchy:

Atoms (components/atoms/)

Basic UI primitives that cannot be broken down further:

• AnimatedNumber/ - Animated number displays
• Currency/ - GP/XP/AP displays
• Icon/ - Icon wrapper components
• TypingText/ - Typewriter text animation

Molecules (components/molecules/)

Combinations of atoms into functional units:

• Ability/ - Ability cards and lists
• AvatarSelect/ - Character avatar picker
• CardMenu/ - Card-based menu system
• Dialog/ - Modal dialogs
• RpgMenu/ - RPG-styled menus
• StatBox/ - Statistics display boxes
• Loading/ - Loading states

Organisms (components/organisms/)

Complex, feature-rich components:

• AudioSettings/ - Full audio configuration
• BattleControls/ - Battle action interface
• CardUserStats/ - User statistics cards
• IntroSplash/ - Introduction screens
• WeatherFX/ - Weather effect overlays
• SwiperGallery/ - Image carousels

---

Composables (Hooks)

Custom Vue composables in src/hooks/:

Hook	Purpose
useTemple	Temple navigation and state
useAudio	Sound effect and music playback
useAbilities	Ability system access
useAbilitySystem	Ability management
useDialog	Dialog state management
useMerchant	Shop interactions
useQuests	Quest tracking
useToast	Toast notifications

---

API Layer

API clients in src/lib/api/:

// Main API client
import XpApi from '@/lib/api/doit.forthexp.com.api';

// Usage
const response = await XpApi.get('xp_achievement', { page: 1 });
const { data } = response;

API Endpoints

• users - User management
• xp_ability - Abilities
• xp_accessory - Accessories/equipment
• xp_achievement - Quests/tasks

---

Styling System

Structure

styles/
├── icons/           # Icon-specific styles
├── mixins/          # SCSS mixins
├── themes/          # Theme definitions
└── core/            # Core styles

Theming

Themes support multiple UI and RPG sound sets:

const theme = reactive({
  ui: 'nintendo',      // UI sound theme
  rpg: 'earthbound'    // RPG sound theme
});

---

Platform Support

Platform	Build System	Status
Web	Vite/Vue CLI	✅ Primary
Android	Capacitor	✅ Supported
iOS	Capacitor	✅ Supported

Native Configuration

• capacitor.config.json - Capacitor settings
• android/ - Android project files
• ios/ - iOS project files

---

Development Tools

• Dev Views: src/views/Dev/ - Development utilities
• Battleroom Mode: Special dev environment (via BATTLEROOM_DEV env variable)
• Debug Utilities: src/lib/utils/debug.ts

---

Related Documentation

• Codebase Structure - Detailed file breakdown
• Battle System Engine - Combat mechanics
• Temple System - Dungeon engine
• Roadmap - Development progress