214 lines
12 KiB
Markdown
214 lines
12 KiB
Markdown
---
|
|
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/` |
|
|
| `framework/NetNeutralityBot.java` | remove or merge into App |
|
|
| `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 `framework/NetNeutralityBot.java` into `core/` or merge into App if it's just a shell
|
|
- 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 |