Feature: Talks
Relevant source files
The following files were used as context for generating this wiki page:
The Talks feature serves as the primary content engine for the TREAD Talks platform. It manages the lifecycle, display, and categorization of faith-based audio and video content. The system enables users to browse, search, and filter talks by speaker and topic, while providing administrators with tools to curate collections and metadata.
Sources: README.md, src/app/talks/page.tsx:8-12, convex/model/talks/queries.ts:208-220
Data Architecture
The Talk entity acts as a central node in the database schema, establishing relationships with speakers, topics, collections, and clips.
Entity Relationships
A talk belongs to exactly one speaker but can be associated with multiple topics through a join table (talksOnTopics). It may optionally belong to a collection, where it maintains a specific collectionOrder. Highlights or short segments are managed as related clips.
The diagram above illustrates how the Talk entity connects various domains within the system.
Sources: convex/model/talks/queries.ts:88-125, convex/model/talks/mutations.ts:77-101, convex/model/topics/mutations.ts:20-56
Data Fields
| Field | Type | Description |
|---|---|---|
title | string | The display name of the talk. |
slug | string | URL-friendly identifier, unique per speaker. |
mediaUrl | string | The source URL for the audio or video content. |
status | enum | Lifecycle state: published, backlog, or archived. |
featured | boolean | Flag for daily rotation in high-visibility sections. |
speakerId | Id<'speakers'> | Reference to the primary speaker. |
collectionId | Id<'collections'> | Optional reference to a series or group. |
topicIds | array | List of associated topic identifiers (in mutations). |
Sources: convex/model/talks/mutations.ts:77-88, convex/model/talks/queries.ts:210-218
Core Backend Logic
The backend uses Convex for data persistence and business logic, organized into queries (reads) and mutations (writes).
Querying and Filtering
The listTalks query handles complex filtering and pagination. It supports native Convex pagination for default views and falls back to in-memory filtering when multiple criteria (search, speaker slugs, topic slugs) are applied.
This flowchart describes the logic within listTalks to handle combined filtering and sorting.
Sources: convex/model/talks/queries.ts:210-313
Talk Mutations and Validation
Administrators modify talk data through specific mutations that enforce integrity rules:
- Slug Generation: Slugs are automatically generated from titles using
slugify. - Uniqueness: A talk slug must be unique for the specific speaker; the system throws a duplicate slug error if a conflict occurs.
- Topic Synchronization: The
setTalkTopicshelper function reconciles the join table by deleting removed associations and inserting new ones. - Status Management: Mutations automatically handle the
publishedAttimestamp based on transitions betweenbacklogandpublished.
Sources: convex/model/talks/mutations.ts:7-60, convex/model/talks/mutations.ts:90-110, convex/model/talks/mutations.ts:162-178
Frontend Components
The feature uses a feature-based organization structure where domain-specific logic resides in src/features/talks.
Talk Detail Page
The talk detail page (src/app/talks/[speakerSlug]/[talkSlug]/page.tsx) uses dynamic routing to fetch data based on the speaker and talk slugs. It renders an EditorialProfileLayout containing:
- TalkHero: Displays the primary media and metadata.
- TalkContentSections: Manages related content like Clips, Collections, and "More Talks" from the same speaker.
- TalkMetadataSidebar: Provides actions (Share, Favorite, Finish) and lists associated topics and scripture references.
Sources: src/app/talks/[speakerSlug]/[talkSlug]/page.tsx:55-103, src/app/talks/[speakerSlug]/[talkSlug]/_components/talk-content-sections.tsx:28-98
Admin Management
Administrators manage talks via the EditTalkSheet. This component includes specialized logic to detect URL changes. If a title or speaker change would result in a new URL for a published talk, the component triggers a UrlChangeDialog to warn the user about potential broken links before committing the update.
The sequence shows the safety flow implemented in the administrative UI.
Sources: src/features/talks/components/edit-talk-sheet.tsx:56-125
Search and Discovery
The platform implements a multi-layered search strategy:
- Query-side Filtering:
filterTalksByTitleOrSpeakerperforms title matching first, then loads unique speakers for remaining candidates to check for name matches. - Topic Enrichment: The
enrichWithTopicsutility fetches topic slugs for talk results, enabling client-side filtering and SEO-friendly labeling. - Daily Rotation: Featured talks use
rotateContentwith adailyperiod to provide fresh content to users every 24 hours.
Sources: convex/model/talks/utils.ts:30-80, convex/model/talks/queries.ts:153-162
Summary: The Talks feature integrates robust backend filtering with Convex, strict administrative validation for content integrity, and a hierarchical UI to surface related faith-based content efficiently.