Skip to content

Refactor: Restructure codebase for better organization #95

Description

@FirebrickRed

Problem

The current codebase structure has become bloated and unclear:

  • data.model/ contains both templates (DndWeapon, DndSpell) and runtime instances (DndEntityInstance)
  • data.model/ has 15+ files with no subcategorization
  • Shop components (ShopConfig, ShopItem, Cost) mixed with domain models
  • No clear separation between YAML-loaded templates and runtime objects
  • Feature-related code scattered across packages

Root cause: Trying multiple organizational patterns during rapid development, resulting in mixed approaches.

Goal

Wait until core features are implemented, then restructure for clarity and scalability.

Potential Approaches

Option A: Feature-based (Recommended)

entity/
  ├── model/ (DndEntity, DndEntityInstance, DndAttack)
  ├── loader/ (EntityLoader)
  ├── menu/ (EntityStatBlockMenu)

item/
  ├── model/ (DndWeapon, DndArmor, DndItem)
  ├── loader/ (WeaponLoader, ArmorLoader, ItemLoader)

spell/
  ├── model/ (DndSpell, SpellcastingInfo, InnateSpell)
  ├── loader/ (SpellLoader)

shop/
  ├── model/ (ShopConfig, ShopItem, Cost)
  ├── ShopGuiUtil, ShopListener

Pros: Everything for a feature co-located, scalable
Cons: Large refactor, imports change everywhere

Option B: Template vs Instance

data/
  ├── template/ (all YAML-loaded definitions)
  ├── instance/ (runtime objects)
  ├── component/ (Cost, ShopConfig, etc.)

Pros: Clear conceptual separation
Cons: Treats everything as "data" which may not be domain-appropriate

Option C: Entity package only

entity/ (DndEntity, DndEntityInstance, DndAttack, EntityStatBlockMenu)
data/model/ (everything else)

Pros: Minimal refactor
Cons: Doesn't solve broader clutter

Timing

⏸️ WAIT until core features are complete (shop system, level-up, combat basics) so we can see the full picture.

Should be done AFTER Issue #12 (LoaderUtils refactor) since that's smaller scope and will be moved anyway.

Success Criteria

  • Clear separation between templates and instances
  • Related code co-located by feature or domain
  • Easy to find files (intuitive structure)
  • No conceptual mixing (e.g., runtime + static together)
  • All imports updated
  • Documentation updated (CLAUDE.md)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions