Data model

Catalog

• heads owns the stable numeric ID, normalized texture hash, texture source, category, publication state, and removal audit fields.
• texture_assets stores canonical head-only PNGs by SHA-256 for skins uploaded directly to HeadDB.
• categories and tags store human-readable names with URL-safe slugs.
• head_tags models the many-to-many taxonomy relationship.
• head_redirects can preserve references when a future duplicate is merged into a canonical entry.
• collections and collection_heads store ordered public or private user head sets.
• user_favorites stores a lightweight personal saved-head list separately from named collections.

Workflow and access

• submissions stores the proposed data, texture value, current state, Discord delivery result, reviewer, notes, and approved head ID.
• site_roles grants submitter, moderator, or administrator capabilities to OAuth users.
• Better Auth owns its user, session, identity-account, and verification tables.
• head_reports tracks one open report per user/head pair through resolution or dismissal, including the moderator and review notes.

Audit and synchronization

• moderation_events is an append-only record of moderation actions and their structured details.
• catalog_revisions gives each published catalog change a monotonic revision number.
• catalog_changes identifies the complete upsert or remove operation attached to each revision, which lets plugins synchronize without downloading a full snapshot.

Foreign keys prevent dangling taxonomy and redirect records. Texture hashes are unique, but removed rows retain that uniqueness so an old texture cannot silently return under a new ID.