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
• ios/ - iOS platform-specific code, build settings, and native configurations
• resources/ - App icons and splash screens for mobile platforms
• src/ - Main application source code
• tests/ - Unit and end-to-end tests

Core Configuration Files

• babel.config.json - Babel configuration for JavaScript transpilation
• battleroom.config.js - Configuration for the battleroom development environment
• capacitor.config.json - Capacitor configuration for native platform builds
• craco.config.js - Create React App Configuration Override for custom settings
• 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
• 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 feature:

• AudioSettings/ - Audio configuration UI components
• AvatarSelect/ - Avatar selection and customization
• CardUserStats/ - User statistics card components
• WeatherFX/ - Weather effects visualization
• XpAbility/ - Ability display and management components
• XpBackgroundSelector/ - Background selection components
• XpCardMenu/ - Card-based menu components
• XpDialog/ - Dialog and modal components
• XpGp/ - Gold Points related components
• XpIcon/ - Icon wrapper components
• XpIntroSplash/ - Introduction and splash screens
• XpLoading/ - Loading indicators
• XpStatBox/ - Statistics display components
• XpSwiperGallery/ - Image gallery components
• XpTypingText/ - Typewriter-style text animation components

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/, legacy Vuex in index.ts [DEPRECATED])
• types/ - TypeScript type definitions
• utils/ - Utility functions

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

views/

Page components for application views:

• App/ - Core application views
• Console/ - Console/admin views
• Dev/ - Development and debugging tools

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

The codebase includes specialized configurations for different development environments:

• Regular development mode
• Battleroom development mode (enabled via BATTLEROOM_DEV environment variable)

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.