CodingStandards - xopherdeep/do-it-for-the-xp GitHub Wiki

🦅 Do It For The XP - Coding Standards & Architecture

"The map must update with the territory."

This document serves as the source of truth for the codebase structure, naming conventions, and architectural patterns.

🏗️ Directory Structure

We use a hybrid structure: Atomic Design for shared components and Domain-Driven separation for the application views.

src/views/ (The Application Layers)

Organized by "Who is using the app?"

| Directory | Purpose | |O---|---| | App/ | The Production Application | | ├── Console/ | The Player Interface (Mobile-first, "Pip-Boy" style). | | ├── GameMaster/ | The Admin Interface (Desktop-optimized, Database management). | | ├── SideMenu/ | Auxiliary pages (Settings, Profile, Support, About). | | └── Auth/ | Authentication & Onboarding flow. | | Dev/ | Developer Tools & Easter Eggs (Isolated from production). |

src/components/ (Shared UI Library)

Organized by Atomic Design principles.

Directory Component Type Example
atoms/ Indivisible elements. Logic-less. XpButton, XpIcon, XpText
molecules/ Simple groups of atoms. XpStatBox, XpSearchBar
organisms/ Complex UI sections. XpNavBar, XpBattleShield
templates/ Page layouts / Shells. XpPage, XpRpgPage, XpModal

src/lib/ (The Brain)

Pure logic, separated from the UI.

  • engine/: Pure game logic (Damage calculations, RNG, Entity definitions). No Vue dependencies if possible.
  • services/: Business logic that interacts with the State or API.
  • store/: Pinia stores (Global state).
  • hooks/: Vue Composables (Replaces Mixins).
  • types/: shared TypeScript interfaces.

📝 Naming Conventions

Files & Directories

  • Vue Components: PascalCase.vue (e.g., XpGoldBadge.vue)
  • Composables: camelCase.ts prefixed with use (e.g., useBattleSystem.ts)
  • Pinia Stores: use{StoreName}Store.ts (e.g., usePlayerStore.ts)
  • TypeScript Logic: camelCase.ts generally.
  • Directories:
    • PascalCase if it contains a component family (components/atoms/MyButton/).
    • camelCase if it contains logic or general groupings (lib/engine/battle/).

Code

  • Variables/Functions: camelCase
  • Constants: UPPER_SNAKE_CASE
  • Classes/Interfaces/Types: PascalCase

🛡️ Architectural Patterns

1. Composables > Mixins

❌ Forbidden: Vue 2 Options API mixins.
✅ Required: Vue 3 Composition API useComposable.

Why? Explicit imports are better than implicit dependency injection. Mixins cause name collisions and are hard to type.

2. State Management

  • Pinia is the standard for global state.
  • Vuex is deprecated and removed.

3. CSS & Styling

  • Scoped SCSS in .vue files is preferred.
  • Global Styles live in src/styles/ but should be minimal.
  • Variables: Use our defined SCSS variables for consistent coloring (e.g., $xp-green, $gp-yellow).

4. "The 3 Layers of Abstraction" Rule

If you have to jump through more than 3 layers to find where the work is done, you've over-engineered it. Keep it simple (KISS).

🚀 Refactoring Guide (Legacy -> Modern)

If you encounter legacy code (Mixins, Vuex), follow this migration path:

  1. Extract Logic: Move the logic from the Mixin/Store into a src/hooks/useFeature.ts composable.
  2. Type It: Ensure the composable is fully typed.
  3. Replace: Update the component to import and destructure the composable.