---
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