101 lines
6.3 KiB
Markdown
101 lines
6.3 KiB
Markdown
# GMW — Agent Guide
|
|
|
|
GMW (Guild Moderation Watcher) is a Discord bot + web dashboard for AI-powered moderation. A monorepo with three services: a selfbot gateway that captures Discord events and runs LLM moderation, an Express/oRPC backend that serves the dashboard API, and a Next.js 16 SSR frontend. They communicate via Redis pub/sub (gateway→backend) and WebSocket (backend→browser).
|
|
|
|
## Quick reference
|
|
|
|
```bash
|
|
# Per-service — cd into the service first
|
|
pnpm install # install deps (pnpm 11, not npm or bun)
|
|
pnpm typecheck # tsc --noEmit
|
|
pnpm lint # biome check
|
|
pnpm format # biome format --write
|
|
pnpm build # gateway/backend: tsc + fix-imports.mjs; frontend: next build
|
|
pnpm test # vitest run (gateway & backend only — frontend has no tests)
|
|
```
|
|
|
|
No monorepo-level scripts exist. Run each command from inside the service directory.
|
|
|
|
## Layout
|
|
|
|
```
|
|
services/
|
|
├── discord-gateway/ Event-driven selfbot. No HTTP (except :4016 metrics).
|
|
│ ├── src/
|
|
│ │ ├── app/ Bootstrap, shutdown, retention
|
|
│ │ ├── modules/ Feature modules — each self-contained
|
|
│ │ └── shared/ Config, DB (Drizzle), logger, errors, utils
|
|
│ ├── tests/ Vitest tests (colocated, not inside src/)
|
|
│ ├── drizzle/migrations/ DB migrations
|
|
│ └── scripts/fix-imports.mjs Post-build: rewrites @/ aliases → relative .js
|
|
│
|
|
├── backend/ Express HTTP + WebSocket + oRPC server (:4001).
|
|
│ ├── src/
|
|
│ │ ├── modules/ Feature modules (schema→repo→service→controller→routes)
|
|
│ │ ├── http/ Express app setup
|
|
│ │ ├── ws/ WebSocket server + Redis bridge
|
|
│ │ ├── orpc/ oRPC router definition
|
|
│ │ └── shared/ Config, DB, errors, Redis, logger
|
|
│ └── tests/ Vitest tests
|
|
│
|
|
└── frontend/ Next.js 16 App Router, React 19, Tailwind v4 (:4017).
|
|
├── src/
|
|
│ ├── app/ Pages — route groups under (dashboard)/
|
|
│ ├── components/ UI components (primitives, shell, charts, etc.)
|
|
│ ├── hooks/ React hooks
|
|
│ └── lib/ API clients, types, utils, WebSocket, audio
|
|
└── pnpm-workspace.yaml Build-script approvals (sharp only)
|
|
```
|
|
|
|
## Conventions
|
|
|
|
### Package manager & runtime
|
|
|
|
- **pnpm** (v11), not npm or bun. Lockfiles are committed. Node ≥ 22.
|
|
- ESM throughout (`"type": "module"` in all package.json files).
|
|
|
|
### Import style
|
|
|
|
Source files use `@/*` path aliases (mapped in tsconfig to `./src/*`). Relative imports **must include the `.js` extension** (e.g., `from "./embed.js"`). The `moduleResolution: "bundler"` tsconfig setting allows bare specifiers during dev, but `tsc` emits them as-is. A post-build script (`scripts/fix-imports.mjs`) rewrites both `@/` aliases and extensionless imports in `dist/` so Node ESM can resolve them at runtime.
|
|
|
|
### Error handling
|
|
|
|
Both gateway and backend define an `AppError` base class in `@/shared/errors/index` with subclasses: `ValidationError` (400), `NotFoundError` (404), `UnauthorizedError` (401), `DatabaseError` (500), `ConfigError` (500). Services throw these; callers or middleware map them to HTTP status codes.
|
|
|
|
### Logging
|
|
|
|
Use `createChildLogger('module-name')` from `@/shared/logger/index`. Never use raw `console`. It wraps pino; in development it pretty-prints via `pino-pretty`.
|
|
|
|
### Config
|
|
|
|
Environment variables are validated with Zod at startup in `shared/config/index.ts` of both gateway and backend. Do not read `process.env` directly outside config modules.
|
|
|
|
### Module boundaries
|
|
|
|
- Gateway: each feature lives in `src/modules/<name>/` with its own `index.ts` barrel. Modules register event listeners and are composed in `src/app/bootstrap.ts`.
|
|
- Backend: `modules/<name>/` follows schema → repository → service → controller → routes. Data flows up only. No cross-module repository imports.
|
|
- Frontend: `page.tsx` is a server component that fetches data via `src/lib/api/server.ts` (oRPC over HTTP, server-side only) and passes it to a `view.tsx` client component. Browser code uses `src/lib/orpc/client.ts` (oRPC over WebSocket via partysocket). Never import the server API client from a client component.
|
|
|
|
### API layer
|
|
|
|
The backend exposes an oRPC router mounted at `/trpc` (both HTTP and WebSocket). The frontend does **not** use a REST `/api/*` layer — all data goes through oRPC procedures. The server-side client (`src/lib/api/server.ts`) uses a fetch-based RPCLink; the browser client uses a WebSocket-based RPCLink backed by partysocket for auto-reconnection. Results are asserted to the frontend's local types at each call site (the backend's router type is not imported into the frontend).
|
|
|
|
### Testing
|
|
|
|
- **Gateway**: Vitest, tests in `tests/` at the service root. Config sets env vars (`DISCORD_TOKEN`, `DATABASE_URL`, etc.) so tests run without real services.
|
|
- **Backend**: Vitest, tests in `tests/` and `src/`. Includes an `e2e.test.ts` excluded from CI (needs a live backend).
|
|
- **Frontend**: No test runner configured.
|
|
- Tests are pure-function / unit-level. Mock external dependencies; do not start real DB/Redis in tests.
|
|
|
|
### Formatting
|
|
|
|
Biome, 2-space indent, spaces. Config at repo root `biome.json`. `lint` uses `--diagnostic-level=error`; `format` auto-writes.
|
|
|
|
## Pitfalls
|
|
|
|
1. **Never commit without running `fix-imports.mjs` after `tsc`** — gateway and backend builds will produce ESM that crashes at startup (`ERR_MODULE_NOT_FOUND`).
|
|
2. **Don't add `@discordjs/opus` build-from-source flags** — it ships prebuilt binaries for Node 22. Forcing source builds in CI/Nix will fail or add minutes of compile time.
|
|
3. **Frontend SSR fetches are always `cache: "no-store"`** — the server API client bypasses Next.js fetch cache. Do not add caching without understanding the live dashboard requirement.
|
|
4. **oRPC types are loosely coupled** — the frontend casts oRPC results to its own types with `as unknown`. Adding a field to the backend schema does not automatically update the frontend type. Update both sides.
|
|
5. **Gateway is a selfbot** (`discord.js-selfbot-v13`) — it uses a user token, not a bot token. It must not be deployed as a standard Discord bot.
|