chore: clean dependencies and format restructure
This commit is contained in:
MythEclipse
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,223 @@
|
||||
# Aggressive Codebase Restructure Design
|
||||
|
||||
## Goal
|
||||
|
||||
Restructure the codebase aggressively enough to make ownership clear, while preserving runtime behavior and public contracts. The first target is the oversized webserver/bootstrap area, then dependency cleanup after the new boundaries compile and pass tests.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- Split `src/webserver.ts` responsibilities into focused modules.
|
||||
- Move bootstrap and shutdown lifecycle out of `src/index.ts`.
|
||||
- Keep existing REST endpoints, WebSocket payloads, dashboard behavior, and Discord audio behavior unchanged.
|
||||
- Add small tests for extracted pure logic.
|
||||
- Audit dependencies after structure stabilizes, then remove, move, or replace only dependencies proven unused or misplaced.
|
||||
|
||||
Out of scope:
|
||||
|
||||
- Changing Discord moderation, voice recording, media playback, or dashboard features.
|
||||
- Replacing the selfbot library.
|
||||
- Reworking database schema or migrations.
|
||||
- Removing the temporary `globalThis` broadcast compatibility layer in this pass.
|
||||
|
||||
## Target Structure
|
||||
|
||||
```text
|
||||
src/
|
||||
app/
|
||||
bootstrap.ts
|
||||
shutdown.ts
|
||||
http/
|
||||
app.ts
|
||||
server.ts
|
||||
health.ts
|
||||
ws/
|
||||
server.ts
|
||||
voiceAudioBridge.ts
|
||||
broadcastGlobals.ts
|
||||
state/
|
||||
uiState.ts
|
||||
mediaSettings.ts
|
||||
audio/
|
||||
pcm.ts
|
||||
routes/
|
||||
...existing
|
||||
```
|
||||
|
||||
### `src/app/bootstrap.ts`
|
||||
|
||||
Owns application startup:
|
||||
|
||||
1. Initialize database.
|
||||
2. Create Discord client and `VoiceController`.
|
||||
3. Register Discord debug/error handlers.
|
||||
4. On ready, register moderation capture, start AI worker, start backlog sync, and start HTTP/WebSocket server.
|
||||
5. Start Discord login.
|
||||
|
||||
### `src/app/shutdown.ts`
|
||||
|
||||
Owns graceful shutdown:
|
||||
|
||||
- Close database.
|
||||
- Disconnect voice controller.
|
||||
- Pause player.
|
||||
- Destroy Discord client.
|
||||
- Exit with correct status.
|
||||
|
||||
The shutdown module receives dependencies instead of importing mutable singletons where practical.
|
||||
|
||||
### `src/http/app.ts`
|
||||
|
||||
Creates and configures Express:
|
||||
|
||||
- Helmet with existing CSP setting.
|
||||
- API no-store middleware.
|
||||
- HTTP error logging.
|
||||
- JSON body parser.
|
||||
- Static dashboard serving.
|
||||
- Route mounting.
|
||||
- Express error handler.
|
||||
|
||||
### `src/http/health.ts`
|
||||
|
||||
Contains health, metrics, and auth routes currently inline in `webserver.ts`.
|
||||
|
||||
### `src/http/server.ts`
|
||||
|
||||
Creates HTTP server, WebSocket server, broadcaster, media controller, stream controller, and route dependencies. Starts listening on `0.0.0.0` using existing port behavior.
|
||||
|
||||
### `src/ws/server.ts`
|
||||
|
||||
Owns WebSocket lifecycle:
|
||||
|
||||
- Accept connections.
|
||||
- Register clients with broadcaster.
|
||||
- Send initial `user_state`, `ui_state`, and `media_state` messages.
|
||||
- Route binary PCM messages to voice audio bridge.
|
||||
- Remove clients on close/error.
|
||||
|
||||
### `src/ws/voiceAudioBridge.ts`
|
||||
|
||||
Owns browser PCM to Discord audio:
|
||||
|
||||
- Upsample 24kHz mono PCM to 48kHz stereo PCM.
|
||||
- Keep existing 20ms pull loop.
|
||||
- Preserve silence tail, max buffer, owner checks, pause/unpause behavior, and logging.
|
||||
- Use extracted pure helpers from `src/audio/pcm.ts`.
|
||||
|
||||
### `src/ws/broadcastGlobals.ts`
|
||||
|
||||
Contains the temporary compatibility layer for existing recorder/moderation code:
|
||||
|
||||
- `moderationBroadcaster`
|
||||
- `broadcastPcmToWeb`
|
||||
- `broadcastVideoToWeb`
|
||||
- `updateActiveUser`
|
||||
- `ADMIN_PASSWORD`
|
||||
|
||||
This isolates `globalThis` usage so later work can replace it with explicit dependency injection.
|
||||
|
||||
### `src/state/uiState.ts`
|
||||
|
||||
Owns persisted UI state:
|
||||
|
||||
- Defaults.
|
||||
- `normalizeSharedUIState`.
|
||||
- Initialize, get, and patch helpers.
|
||||
|
||||
### `src/state/mediaSettings.ts`
|
||||
|
||||
Owns persisted media settings:
|
||||
|
||||
- Defaults.
|
||||
- Initialize helper.
|
||||
- Update helper for music volume.
|
||||
|
||||
### `src/audio/pcm.ts`
|
||||
|
||||
Owns pure PCM utilities:
|
||||
|
||||
- `upsample24kMonoTo48kStereo`.
|
||||
- `rmsDb`.
|
||||
|
||||
## Data Flow
|
||||
|
||||
```text
|
||||
index.ts
|
||||
-> bootstrap app
|
||||
-> initializeDatabase()
|
||||
-> create Discord client + VoiceController
|
||||
-> on ready:
|
||||
-> register moderation capture
|
||||
-> start AI worker + backlog sync
|
||||
-> startHttpServer()
|
||||
|
||||
startHttpServer()
|
||||
-> create Express app
|
||||
-> create HTTP server
|
||||
-> create WebSocket server
|
||||
-> create broadcaster
|
||||
-> create Streamer + ScreenShareController + MediaController
|
||||
-> mount API routes
|
||||
-> expose temporary global hooks
|
||||
```
|
||||
|
||||
## Behavior Preservation
|
||||
|
||||
Do not change:
|
||||
|
||||
- REST endpoint paths or JSON shapes.
|
||||
- WebSocket outbound JSON message types.
|
||||
- WebSocket binary voice/video packet format.
|
||||
- Browser PCM assumptions: 24kHz mono signed 16-bit little-endian.
|
||||
- Discord outbound audio assumptions: 48kHz stereo Opus frames.
|
||||
- Static dashboard fallback behavior.
|
||||
- Existing logging messages unless moving them requires minor context changes.
|
||||
|
||||
## Dependency Cleanup
|
||||
|
||||
Dependency cleanup happens after structural refactor passes validation.
|
||||
|
||||
Process:
|
||||
|
||||
1. Build an import map from source, tests, scripts, frontend, and config files.
|
||||
2. Identify unused dependencies and devDependencies.
|
||||
3. Move packages used only by tooling/tests/frontend into correct dependency class if currently misplaced.
|
||||
4. Remove package entries only when no import, config usage, script usage, or runtime side-effect import exists.
|
||||
5. Prefer not adding libraries unless they replace custom fragile code or fill a concrete missing capability.
|
||||
|
||||
Potential new tool dependency: `depcheck` may be used as a one-off via `pnpm dlx depcheck`, not necessarily added to `package.json`.
|
||||
|
||||
## Testing Plan
|
||||
|
||||
Add or update tests for extracted pure logic:
|
||||
|
||||
- UI state normalization keeps legacy `selectedGuild` behavior.
|
||||
- PCM upsample doubles sample rate and duplicates mono into stereo channels.
|
||||
- RMS dB handles normal PCM input consistently.
|
||||
|
||||
Run validation after each major step:
|
||||
|
||||
```bash
|
||||
pnpm run typecheck
|
||||
pnpm run lint
|
||||
pnpm run test
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
- Aggressive file movement can break imports. Mitigation: move one responsibility at a time and run typecheck frequently.
|
||||
- `globalThis` compatibility can hide coupling. Mitigation: isolate it in `broadcastGlobals.ts` and avoid expanding it.
|
||||
- Dependency cleanup can remove runtime side-effect packages. Mitigation: treat side-effect imports in `src/index.ts` as used.
|
||||
- Frontend and backend share one package manifest. Mitigation: audit source areas separately before moving dependencies.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `src/webserver.ts` is removed or reduced to a thin compatibility facade.
|
||||
- `src/index.ts` delegates startup to `src/app/bootstrap.ts`.
|
||||
- HTTP, WebSocket, UI state, media settings, audio bridge, and broadcast globals have separate modules.
|
||||
- Existing tests pass.
|
||||
- Typecheck, lint, and build pass.
|
||||
- Dependency changes are justified by import/config/script evidence.
|
||||
Reference in New Issue
Block a user