User Accounts & Interactions

Relevant source files

The following files were used as context for generating this wiki page:

• convex/model/users/mutations.ts
• convex/model/auth/utils.ts
• src/app/talks/[speakerSlug]/[talkSlug]/_components/talk-metadata-sidebar.tsx
• convex/model/auth/roles.ts
• convex/model/users/validators.ts
• AGENTS.md

User Accounts & Interactions manage identity, profile settings, and personal content engagement. The system tracks user preferences such as favorite talks, clips, and speakers, as well as consumption progress through "finished" markers.

This module relies on Better Auth for identity management and Convex for storing user-specific relational data. Authorization levels distinguish between standard users and administrative users to protect sensitive mutations.
Sources: README.md:5-15, convex/model/users/mutations.ts:5-10

User Authentication & Roles

The system manages user identity through Better Auth. Authentication is required for most user-specific actions, and roles determine access levels for internal management functions.

Access Control

• User Identity: Derived server-side using getUserId(ctx) or requireAuth(ctx) to ensure operations only affect the caller's data.
• Roles: The system supports a userRole validator. Administrative functions require the admin role, verified via requireAdmin(ctx).
• Internal Access: A specific setUserRoleInternal mutation exists for programmatic role management without standard auth headers, intended for use via the CLI or Dashboard.

Sources: convex/model/users/mutations.ts:251-295, convex/model/auth/roles.ts, convex/model/users/validators.ts

Authentication Data Flow

The following diagram illustrates how the system validates identity before processing a user mutation:

Profile Management

Users manage their core account data through mutations that interface with the authentication provider.

Mutation	Argument	Description
updateUserProfile	name	Updates the user's display name.
updateUserEmail	newEmail	Changes the primary email address.
updateUserPassword	currentPassword, newPassword	Modifies account security credentials.
deleteUser	password	Permanently removes the user account and returns to the home page.

Sources: convex/model/users/mutations.ts:205-248

Content Interactions

Users interact with platform content by favoriting items or marking talks as finished. These interactions are stored in dedicated relational tables: userFavoriteTalks, userFavoriteClips, userFavoriteSpeakers, and userFinishedTalks.

Interaction Logic

Mutations validate that an interaction does not already exist before creating a new record. Attempting to favorite an item twice throws a ValidationError.

Engagement Components

The metadata sidebar on individual talk pages provides the interface for these interactions through specific button components:

• FavoriteTalkButton: Manages the favorited state of a talk.
• FinishTalkButton: Toggles the "finished" status to track consumption.
• ShareTalkButton: Provides sharing functionality.

Sources: src/app/talks/[speakerSlug]/[talkSlug]/_components/talk-metadata-sidebar.tsx:40-65

Interaction Schema

Table	Fields	Constraints
userFavoriteTalks	userId, talkId	Unique index on userId and talkId.
userFavoriteClips	userId, clipId	Unique index on userId and clipId.
userFavoriteSpeakers	userId, speakerId	Unique index on userId and speakerId.
userFinishedTalks	userId, talkId	Tracks completed content per user.

Sources: convex/model/users/mutations.ts:15-130

Interaction Removal

Corresponding "unfavorite" and "unfinish" mutations perform hard deletes on the relational records after verifying ownership via getUserId.
Sources: convex/model/users/mutations.ts:109-150

Summary

User Accounts & Interactions provide the personalization layer for the platform. By combining Better Auth for identity and Convex mutations for engagement tracking, the system enables users to build a personal library of favorite sermons, clips, and speakers while maintaining control over their profile and security settings.