Codebase Structure

This document outlines the structure of the "Do It for the XP" codebase, highlighting key directories, files, and their purposes to help developers navigate and understand the project organization.

Project Overview

"Do It for the XP" is a gamified task management application built with Vue.js and Ionic, with support for deployment on the web, Android, and iOS platforms. The application uses a battle system metaphor to represent tasks and achievements.

Root Structure

The project is organized with the following top-level directories:

• android/ - Android platform-specific code, build settings, and native configurations
• assets/ - App icons and splash screens for mobile platforms
• ios/ - iOS platform-specific code, build settings, and native configurations
• src/ - Main application source code
• tests/ - Unit and end-to-end tests

Core Configuration Files

• babel.config.json - Babel configuration for JavaScript transpilation
• capacitor.config.json - Capacitor configuration for native platform builds
• craco.config.js - Leftover from a React experiment (a Create React App override). Unused: nothing references it and the Vue CLI build reads vue.config.js. Candidate for deletion.
• cypress.json - Cypress end-to-end testing configuration
• ionic.config.json - Ionic framework configuration
• jest.config.json - Jest unit testing configuration
• package.json - NPM dependencies and scripts
• tailwind.config.js - Tailwind CSS configuration
• tsconfig.json - TypeScript compiler configuration
• vue.config.js - Vue.js configuration with environment-specific settings

Source Code Structure (src/)

Entry Points

• main.ts - Application entry point
• app.config.ts - Core application configuration
• manifest.webmanifest - Web application manifest
• types/shims-vue.d.ts - TypeScript type definitions for Vue

Main Directories

assets/

Contains static assets used throughout the application:

• audio/ - Sound effects and music files
• fonts/ - Font files including Font Awesome
• fx/ - Special effects assets
• icons/ - App and UI icons
• images/ - Image files used throughout the app

components/

Reusable Vue components organized by atomic design level:

• atoms/ - Smallest reusable building blocks
• molecules/ - Small groups of atoms that work together
• organisms/ - Larger, self-contained UI sections
• templates/ - Page-level layouts

constants/

Application-wide constant values and enumerations.

hooks/

Custom Vue composition API hooks.

lib/

Core application libraries and services:

• api/ - API client interfaces and implementations
• databases/ - Database access and management
• engine/ - Game engine components
• services/ - Business logic services
  • battle/ - Battle system services
    • BattleService.ts - Manages battle interactions
    • BestiaryService.ts - Manages beast/monster data
  • gp/ - Gold Points service
• store/ - State management (Pinia stores in stores/)
• utils/ - Utility functions

lib/mixins/

Vue component mixins for sharing functionality.

router/

Vue Router configuration and route definitions.

styles/

Global styles and theming:

• icons/ - Icon-specific styles
• mixins/ - SCSS mixins
• themes/ - Theme definitions

app/

Feature components for application screens:

• Admin/ - Game Master and admin tools
• Console/ - Console screens (MyPortal, WorldMap, BattleField, TempleGrounds)
• Dev/ - Development and debugging tools
• SideMenu/ - Side menu screens (settings, support, membership, and others)
• App.vue - Root application component

views/

Standalone page views:

• LogIn/, XpIntro/, XpDemo/, XpGameOver/

Mobile Platform Code

Android (android/)

Android-specific configuration:

• app/ - Android application code
  • build.gradle - Android build configuration
  • proguard-rules.pro - Code optimization rules
  • src/ - Android-specific source code

iOS (ios/)

iOS-specific configuration:

• App/ - iOS application code
  • Podfile - CocoaPods dependencies

Development Environments

Non-production builds (NODE_ENV other than production) include developer-only features such as the Dev routes and the Support Dev Tools page. Production builds exclude them.

Key Services

Battle System

The battle system is a core feature, representing tasks and achievements as "battles" with enemies:

• BattleService - Manages battle state and gameplay mechanics
• BestiaryService - Manages monster/beast data and interactions

Databases

The application uses local storage databases:

• BestiaryDb - Manages beast data storage
• Other specialized database services for different data types

Future Direction

For our plans on improving the codebase, refactoring services, and new features, please refer to our Roadmap.