netneutrality/.junie/plans/revert-package-structure.md

sessionId

sessionId
session-260905-145156-xyio

Requirements

Overview & Goals

Revise the package structure section of the lifecycle refactor plan to use a hybrid layout that keeps the new bootstrap/ package but reverts the rest to the familiar old-style naming and organization.

Scope

In Scope

• Reverting framework/ → core/ (engine: command, context, task machinery)
• Reverting platform/ hierarchy → flat old-style packages: db/ (persistence + entities + repositories + services), hooks/ (events), http/ (web API), music/ (music domain)
• Reverting feature/ vertical grouping → separate top-level command/, tasks/, context/ packages with subcategory folders (e.g. command/music/, tasks/scheduled/)
• Restoring utils/ for remaining helpers (Settings, JpaUtils, MusicUtils, ChannelMessagePurger)
• Keeping bootstrap/ (ApplicationContext, Lifecycle, BotState, ReflectionHelper) — this is new and stays
• Keeping exceptions/ — unchanged
• Keeping shared/util/ (ContextUtils, GuildUtils, MessageFunction, MiscUtils, UserFunction)

Out of Scope

• Any behavioral or DI/lifecycle logic changes — this is purely a package restructure
• Changing the DI refactor plan's other sections (Lifecycle contract, ApplicationContext, constructor injection, interfaces)

Target Layout

me.bobert.netneutrality
├── App.java
├── bootstrap/                  # NEW — keep as-is
│   ├── ApplicationContext.java
│   ├── BotState.java
│   ├── Lifecycle.java
│   └── ReflectionHelper.java
├── core/                       # was framework/ → revert to core/
│   ├── command/                # Command, CommandProcessor, CommandRegistry, CommandManager, options/, impl/
│   ├── context/                # Context hierarchy, abstract bases
│   └── tasks/                  # Task, TaskManager, StepTask, PersistableTask, persistence/, trait/, impl/
├── command/                    # concrete command implementations (was feature/*/command/)
│   ├── admin/
│   ├── basic/
│   ├── bot/
│   ├── crypto/
│   ├── custom/
│   ├── git/
│   ├── music/
│   └── react/
├── context/                    # concrete context implementations (was framework/context/command/ + task/)
│   ├── command/
│   ├── tasks/
│   └── MusicChannelContext.java
├── tasks/                      # concrete task implementations (was feature/*/task/)
│   ├── emoji/
│   ├── generic/
│   ├── git/
│   ├── help/
│   ├── music/
│   ├── reaction/
│   └── scheduled/
├── db/                         # persistence model (was data/ + platform/persistence/)
│   ├── entities/               # O* entities
│   ├── repository/
│   ├── service/                # GuildService, GuildServiceProvider, BlacklistService, etc.
│   ├── GSettings.java
│   ├── Repository.java
│   ├── DatabaseMigration.java
│   ├── SessionManager.java     # SessionProvider impl
│   └── JpaUtils.java
├── hooks/                      # was platform/event/
│   └── EventsHandler.java
├── http/                       # was platform/web/
│   ├── server/
│   └── WebModule.java
├── music/                      # music domain (was feature/music/ minus commands/tasks)
│   ├── AudioPlayerSendHandler.java
│   ├── MusicManager.java
│   ├── MusicService.java
│   ├── QueueManager.java
│   ├── SourceFinder.java
│   ├── source/
│   ├── TrackInfo.java
│   ├── TrackLoadingHandler.java
│   └── TrackScheduler.java
├── utils/                      # remaining helpers not in shared/util/
│   ├── Settings.java           # SettingsProvider impl
│   ├── ChannelMessagePurger.java
│   ├── JpaUtils.java           # (or in db/, see note)
│   └── MusicUtils.java
├── shared/util/                # NEW — keep as-is
│   ├── ContextUtils.java
│   ├── GuildUtils.java
│   ├── MessageFunction.java
│   ├── MiscUtils.java
│   └── UserFunction.java
├── exceptions/                 # unchanged
└── core/thread/ OR thread/     # ThreadManager, ScheduledTaskManager, BaseThreadFactory

Note: core/thread/ was the old location for threading. The old layout also had a top-level thread/ for MusicManagerCleanupThread. Both can be restored as they were.

Key Moves (current → proposed)

Current (new)	Proposed (hybrid)
framework/command/	core/command/
framework/context/	core/context/
framework/task/	core/tasks/
platform/config/Settings.java	utils/Settings.java
platform/persistence/*	db/ (SessionManager, DatabaseMigration, JpaUtils, Repository)
platform/concurrency/*	core/thread/
platform/logging/LogHandler.java	core/LogHandler.java
platform/event/EventsHandler.java	hooks/EventsHandler.java
platform/web/*	http/*
data/entity/	db/entities/
data/repository/	db/repository/
data/service/	db/service/
feature/music/command/*	command/music/
feature/music/*.java (domain)	music/
feature/moderation/command/*	command/admin/
feature/moderation/ChannelMessagePurger.java	utils/ChannelMessagePurger.java
feature/reaction/command/*	command/react/
feature/reaction/task/*	tasks/reaction/
feature/git/command/*	command/git/
feature/git/task/*	tasks/git/
feature/crypto/command/*	command/crypto/
feature/help/command/*	command/basic/ + command/bot/
feature/help/task/*	tasks/help/
feature/custom/command/*	command/custom/
bootstrap/	bootstrap/ (no change)
shared/util/	shared/util/ (no change)
exceptions/	exceptions/ (no change)

Technical Design

Current Implementation

The codebase currently uses the post-refactor layout with:

• bootstrap/ — ApplicationContext, Lifecycle, BotState, ReflectionHelper
• framework/ — command, context, task engine
• platform/ — config, persistence, concurrency, logging, event, web
• feature/ — music, moderation, reaction, git, crypto, help, custom (feature-vertical grouping)
• data/ — entity, repository, service
• shared/util/ — cross-cutting helpers
• exceptions/

All DI/lifecycle wiring (constructor injection, interfaces like SettingsProvider, SessionProvider, ExecutorProvider, CommandRegistry, TaskManager, MusicService, GuildServiceProvider) remains intact — only package locations change.

Key Decisions

1. Revert engine package name: framework/ → core/ — matches the original naming the team is familiar with.
2. Flatten infrastructure: dissolve platform/ hierarchy back to db/, hooks/, http/, core/thread/, utils/ — removes the extra nesting that added cognitive overhead.
3. Separate top-level command/tasks/context: undo feature-vertical grouping in feature/ — concrete implementations go back to command/<category>/, tasks/<category>/, context/ as before.
4. Keep bootstrap/ and shared/util/: these are genuinely new and useful additions with no old equivalent.
5. Restore db/entities/: revert data/entity/ back to db/entities/ (plural, matching old convention).
6. Service interfaces stay: SettingsProvider, SessionProvider, ExecutorProvider, etc. remain — they just live in their reverted package locations (e.g. SettingsProvider in utils/ alongside Settings).

Proposed Changes

This is a pure move/rename refactor using IDE safe "Move Class" operations. No logic changes. The DI wiring, lifecycle priorities, constructor injection, and all interfaces remain exactly as they are — only their package declarations and import statements change.

Risks

• Import churn — same risk as the original restructure; mitigated by IDE "Move Class" refactor, one subsystem at a time, build after each.
• Interface co-location — service interfaces (e.g. SessionProvider) now live alongside their impls in db/ or utils/ rather than in a separate platform/ package. This is acceptable for this project's size.

Delivery Steps

✓ Step 1: Move engine packages from framework/ back to core/

The framework/ package is renamed back to core/ with its original subpackage names.

• Move framework/command/ → core/command/ (all engine classes: Command, CommandProcessor, CommandRegistry, CommandManager, CommandCategory, CommandContainer, CommandExecutionResult, CommandOptionsBuilder, impl/, options/)
• Move framework/context/ → core/context/ (Context, AbstractContext, CommandContext, TaskContext, InteractionContext, MessageContext, NoMessageContext, AsyncContext)
• Move framework/task/ → core/tasks/ (Task, TaskManager interface + impl, StepTask, PersistableTask, BuiltInTask, ScheduledTask, TaskCleanup, persistence/, trait/, impl/, generic/)
• Move platform/logging/LogHandler.java → core/LogHandler.java
• Move platform/concurrency/* → core/thread/ (ThreadManager/ExecutorProvider, ScheduledTaskManager, BaseThreadFactory)
• Update all imports; verify build with ./mvnw compile

✓ Step 2: Move persistence and infrastructure packages back to db/, hooks/, http/, utils/

Infrastructure packages are flattened back to their original top-level locations.

• Move data/entity/ → db/entities/ (restore plural naming)
• Move data/repository/ → db/repository/
• Move data/service/ → db/service/ (GuildService, GuildServiceProvider, GuildSettingService, BlacklistService, TaskService)
• Move data/GSettings.java → db/GSettings.java
• Move platform/persistence/ contents → db/ (SessionManager/SessionProvider, DatabaseMigration, Repository, JpaUtils, SessionProvider interface)
• Move platform/config/Settings.java + SettingsProvider → utils/
• Move platform/event/EventsHandler.java → hooks/EventsHandler.java
• Move platform/web/ → http/ (WebApi, server/, WebModule)
• Move feature/moderation/ChannelMessagePurger.java → utils/ChannelMessagePurger.java
• Move feature/music/MusicUtils.java → utils/MusicUtils.java (if it exists)
• Delete empty platform/ and data/ directories
• Update all imports; verify build with ./mvnw compile

✓ Step 3: Restore music domain package and split feature/ into command/, tasks/, context/

Feature-vertical grouping is dissolved back into separate top-level packages.

• Move feature/music/ domain classes (MusicManager, MusicService, QueueManager, AudioPlayerSendHandler, SourceFinder, source/, TrackInfo, TrackLoadingHandler, TrackScheduler, MusicChannelContext) → music/
• Move concrete context classes from framework/context/command/ → context/command/ and framework/context/task/ → context/tasks/; move MusicChannelContext → context/MusicChannelContext.java
• Move feature/music/command/* → command/music/
• Move feature/moderation/command/* → command/admin/
• Move feature/reaction/command/* → command/react/
• Move feature/git/command/* → command/git/
• Move feature/crypto/command/* → command/crypto/
• Move feature/help/command/* → command/basic/ and command/bot/ (matching old categorization)
• Move feature/custom/command/* → command/custom/
• Move feature/reaction/task/* → tasks/reaction/
• Move feature/git/task/* → tasks/git/
• Move feature/help/task/* → tasks/help/
• Move feature/music/task/* → tasks/music/
• Move scheduled tasks → tasks/scheduled/
• Delete empty feature/ directory
• Update all imports; verify full build with ./mvnw package
• Update docs/architecture.md package map table to reflect the new hybrid layout