6abbd4652a
Some checks failed
Deploy to Production / test (push) Failing after 33s
- Rewrite AGENTS and README files to match the current app layout - Document API routes, trivia UI, and the active panel design language
136 lines
4.8 KiB
Markdown
136 lines
4.8 KiB
Markdown
# AGENTS.md
|
|
|
|
This file documents the current implementation shape of the Aurora repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# App
|
|
bun run dev # bot + API in one Bun process with watch mode
|
|
docker compose up # app + db
|
|
docker compose up app # app only
|
|
docker compose up db # database only
|
|
|
|
# Testing
|
|
bun test # Bun's native runner
|
|
bun run test # repo test wrapper script
|
|
bun run test:ci # include CI/integration path
|
|
|
|
# Database
|
|
bun run db:push # drizzle-kit push via Docker
|
|
bun run db:push:local # drizzle-kit push locally
|
|
bun run db:generate # drizzle-kit generate via Docker
|
|
bun run db:migrate # drizzle-kit migrate via Docker
|
|
bun run db:studio # local Drizzle Studio on :4983
|
|
|
|
# Panel
|
|
bun run panel:dev # Vite dev server on :5173
|
|
bun run panel:build # build panel/dist
|
|
```
|
|
|
|
## Architecture
|
|
|
|
Aurora is a single-process Bun application:
|
|
|
|
- `bot/index.ts` boots shared config, registers domain listeners, starts the API server, then logs into Discord.
|
|
- `api/src/server.ts` hosts REST routes, WebSocket traffic, and built panel assets.
|
|
- `shared/modules/*` contains the business logic used by both the bot and the API.
|
|
- `shared/games/*` contains reusable game plugins; `api/src/games/*` runs rooms and WebSocket orchestration.
|
|
|
|
Current high-level layout:
|
|
|
|
```text
|
|
bot/ Discord commands, events, views, interactions
|
|
api/ Bun HTTP + WebSocket server
|
|
panel/ React dashboard
|
|
shared/db/ Drizzle client and schema
|
|
shared/lib/ config, env, errors, logger, events, constants
|
|
shared/modules/ domain services
|
|
shared/games/ game plugins shared by API and panel
|
|
```
|
|
|
|
## Import conventions
|
|
|
|
Use path aliases from the repo `tsconfig.json`:
|
|
|
|
- `@/*` -> `bot/*`
|
|
- `@commands/*` -> `bot/commands/*`
|
|
- `@db/*` -> `shared/db/*`
|
|
- `@lib/*` -> `bot/lib/*`
|
|
- `@modules/*` -> `bot/modules/*`
|
|
- `@shared/*` -> `shared/*`
|
|
|
|
Import order in the repo is generally:
|
|
|
|
1. external packages
|
|
2. aliases
|
|
3. relative imports
|
|
|
|
## File patterns
|
|
|
|
- `*.service.ts`: domain/business logic, usually in `shared/modules/*`
|
|
- `*.view.ts`: Discord message/view construction
|
|
- `*.interaction.ts`: component interaction handlers
|
|
- `*.types.ts`: local types and custom ID helpers
|
|
- `*.handler.ts`: bot-side orchestration around services/views
|
|
- `*.test.ts`: colocated tests
|
|
|
|
## Runtime config
|
|
|
|
- Global game settings live in `game_settings` and are loaded into `shared/lib/config.ts`.
|
|
- Guild-specific settings live in `guild_settings`; `getGuildConfig()` adds a 60-second cache on top of DB reads.
|
|
- Most numeric DB values exposed through runtime config are converted to `bigint` in `shared/lib/config.ts`.
|
|
|
|
## Interaction routing
|
|
|
|
Global component routing is defined in `bot/lib/interaction.routes.ts` and consumed by `ComponentInteractionHandler`.
|
|
|
|
Current route table:
|
|
|
|
- `trade_` and `amount` -> `bot/modules/trade/trade.interaction.ts`
|
|
- `shop_buy_` -> `bot/modules/economy/shop.interaction.ts`
|
|
- `lootdrop_` -> `bot/modules/economy/lootdrop.interaction.ts`
|
|
- `trivia_` -> `bot/modules/trivia/trivia.interaction.ts`
|
|
- `createitem_` -> `bot/modules/admin/item_wizard.ts`
|
|
- `enrollment` -> `bot/modules/user/enrollment.interaction.ts`
|
|
- `feedback_` -> `bot/modules/feedback/feedback.interaction.ts`
|
|
|
|
Some features still use local collectors instead of the global route table, notably inventory.
|
|
|
|
## Commands and access control
|
|
|
|
- Slash command execution is centralized in `bot/lib/handlers/CommandHandler.ts`.
|
|
- `withCommandErrorHandling()` is the normal command wrapper for defer/reply/error behavior.
|
|
- Beta commands rely on `featureFlagsService.hasAccess()`.
|
|
- `ADMIN_USER_IDS` controls admin panel access, not Discord permissions inside command code.
|
|
|
|
## API and panel
|
|
|
|
- API routes are prefix-matched in `api/src/routes/index.ts`.
|
|
- `/auth/*` and `/api/health` are public.
|
|
- Players may access `/api/stats`, `/api/health`, `/api/me`, and `/api/me/inventory`.
|
|
- Remaining `/api/*` routes are admin-only.
|
|
- The panel dev server proxies back to the Bun server; the integrated server serves `panel/dist` when built.
|
|
|
|
## Database notes
|
|
|
|
- Docker Compose uses PostgreSQL 17.
|
|
- Discord IDs and currency/xp values are stored as `bigint`.
|
|
- `withTransaction()` lives in `bot/lib/db.ts` and is the normal way shared services compose DB work.
|
|
|
|
## Testing
|
|
|
|
- Tests use `bun:test`.
|
|
- Mock modules before importing the unit under test.
|
|
- Most service tests stub `DrizzleClient` or `withTransaction()` rather than hitting the real database.
|
|
|
|
## Key entrypoints
|
|
|
|
- `bot/index.ts`
|
|
- `bot/lib/BotClient.ts`
|
|
- `api/src/server.ts`
|
|
- `api/src/routes/index.ts`
|
|
- `shared/lib/config.ts`
|
|
- `shared/db/DrizzleClient.ts`
|
|
- `shared/db/schema/index.ts`
|