AuroraBot-discord/shared/docs/DATABASE.md

Database Schema

This document outlines the database schema for the Aurora project. The database is PostgreSQL, managed via Drizzle ORM.

Tables

Users (users)

Stores user data, economy, and progression.

Column	Type	Description
id	bigint	Primary Key. Discord User ID.
class_id	bigint	Foreign Key -> classes.id.
username	varchar(255)	User's Discord username.
is_active	boolean	Whether the user is active (default: true).
balance	bigint	User's currency balance.
xp	bigint	User's experience points.
level	integer	User's level.
daily_streak	integer	Current streak of daily command usage.
settings	jsonb	User-specific settings.
created_at	timestamp	Record creation time.
updated_at	timestamp	Last update time.

Classes (classes)

Available character classes.

Column	Type	Description
id	bigint	Primary Key. Custom ID.
name	varchar(255)	Class name (Unique).
balance	bigint	Class bank balance (shared/flavor).
role_id	varchar(255)	Discord Role ID associated with the class.

Items (items)

Definitions of items available in the game.

Column	Type	Description
id	serial	Primary Key. Auto-incrementing ID.
name	varchar(255)	Item name (Unique).
description	text	Item description.
rarity	varchar(20)	Common, Rare, etc. Default: 'Common'.
type	varchar(50)	MATERIAL, CONSUMABLE, EQUIPMENT, etc.
usage_data	jsonb	Effect data for consumables/usables.
price	bigint	Base value of the item.
icon_url	text	URL for the item's icon.
image_url	text	URL for the item's large image.

Inventory (inventory)

Items held by users.

Column	Type	Description
user_id	bigint	PK/FK -> users.id.
item_id	integer	PK/FK -> items.id.
quantity	bigint	Amount held. Must be > 0.

Transactions (transactions)

Currency transaction history.

Column	Type	Description
id	bigserial	Primary Key.
user_id	bigint	FK -> users.id. The user affecting the balance.
related_user_id	bigint	FK -> users.id. The other party (if any).
amount	bigint	Amount transferred.
type	varchar(50)	Transaction type identifier.
description	text	Human-readable description.
created_at	timestamp	Time of transaction.

Item Transactions (item_transactions)

Item flow history.

Column	Type	Description
id	bigserial	Primary Key.
user_id	bigint	FK -> users.id.
related_user_id	bigint	FK -> users.id.
item_id	integer	FK -> items.id.
quantity	bigint	Amount gained (+) or lost (-).
type	varchar(50)	TRADE, SHOP_BUY, DROP, etc.
description	text	Description.
created_at	timestamp	Time of transaction.

Quests (quests)

Quest definitions.

Column	Type	Description
id	serial	Primary Key.
name	varchar(255)	Quest title.
description	text	Quest text.
trigger_event	varchar(50)	Event that triggers progress checks.
requirements	jsonb	Completion criteria.
rewards	jsonb	Rewards for completion.

User Quests (user_quests)

User progress on quests.

Column	Type	Description
user_id	bigint	PK/FK -> users.id.
quest_id	integer	PK/FK -> quests.id.
progress	integer	Current progress value.
completed_at	timestamp	Completion time (null if active).

User Timers (user_timers)

Generic timers for cooldowns, temporary effects, etc.

Column	Type	Description
user_id	bigint	PK/FK -> users.id.
type	varchar(50)	PK. Timer type (COOLDOWN, EFFECT, ACCESS).
key	varchar(100)	PK. specific ID (e.g. 'daily').
expires_at	timestamp	When the timer expires.
metadata	jsonb	Extra data.

Lootdrops (lootdrops)

Active chat loot drop events.

Column	Type	Description
message_id	varchar(255)	Primary Key. Discord Message ID.
channel_id	varchar(255)	Discord Channel ID.
reward_amount	integer	Currency amount.
currency	varchar(50)	Currency type constant.
claimed_by	bigint	FK -> users.id. Null if unclaimed.
created_at	timestamp	Spawn time.
expires_at	timestamp	Despawn time.

Moderation Cases (moderation_cases)

History of moderation actions.

Column	Type	Description
id	bigserial	Primary Key.
case_id	varchar(50)	Unique friendly ID.
type	varchar(20)	warn, timeout, kick, ban, etc.
user_id	bigint	Target user ID.
username	varchar(255)	Target username snapshot.
moderator_id	bigint	Acting moderator ID.
moderator_name	varchar(255)	Moderator username snapshot.
reason	text	Reason for action.
metadata	jsonb	Extra data.
active	boolean	Is this case active?
created_at	timestamp	Creation time.
resolved_at	timestamp	Resolution/Expiration time.
resolved_by	bigint	User ID who resolved it.
resolved_reason	text	Reason for resolution.