aurorabot/AGENTS.md

AGENTS.md

This file documents the current implementation shape of the Aurora repository.

Commands

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

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