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