Feature: Topics
Relevant source files
The following files were used as context for generating this wiki page:
The Topics feature organizes Christ-centered talks into specific biblical themes and subjects. It allows users to browse sermons by theological category and helps administrators manage the relationship between content and specific tags.
Sources: src/app/topics/page.tsx:12-16, convex/model/topics/queries.ts:258-270
Data Model and Schema
Topics are stored as distinct entities in the database and linked to talks via a join table. This structure supports a many-to-many relationship where one talk can belong to multiple topics.
Topic Entity
A Topic contains descriptive metadata including a title, a unique slug for URL routing, and a status for visibility control.
| Field | Type | Description |
|---|---|---|
title | string | The display name of the topic. |
slug | string | URL-friendly identifier generated from the title. |
description | string (optional) | Detailed context regarding the topic theme. |
status | string | Current state (e.g., published, draft). |
Sources: convex/model/topics/mutations.ts:139-144, src/features/topics/types.ts
Relationship Schema
The system uses the talksOnTopics table to manage associations.
The diagram shows the many-to-many relationship between Talks and Topics facilitated by a join table.
Sources: convex/model/topics/mutations.ts:23-57, convex/model/topics/queries.ts:47-53
Backend Operations
Data Retrieval (Queries)
The system provides specialized queries for different view contexts, such as the main browse page and individual topic detail pages.
listTopicsWithTalks: Retrieves topics that have at least one published talk, including up to 5 enriched talk objects per topic for horizontal scrolling views.getTopicBySlug: Fetches a specific topic's metadata and a paginated list of all associated talks, supporting search filtering by talk title or speaker name.listTopicsWithCount: Returns topics sorted by talk volume (most-talks, least-talks) or alphabetically.
Sources: convex/model/topics/queries.ts:88-140, convex/model/topics/queries.ts:258-305, convex/model/topics/queries.ts:200-205
Data Modification (Mutations)
Administrative actions require authentication and include validation to ensure data integrity.
createTopic: Generates a new topic and automatically creates a unique slug.setTalkTopics: An internal helper that synchronizes a talk's topic associations by deleting removed links and inserting new ones in a single transaction.destroyTopic: Permanently deletes a topic only if it has no associated talks (reference check).
Sources: convex/model/topics/mutations.ts:62-81, convex/model/talks/mutations.ts:15-47, convex/model/topics/mutations.ts:86-117
Frontend Implementation
Topic Browsing
The topics browse page utilizes a SidebarLayout to display a list of categories alongside a navigation sidebar.
The flow shows how data from the getTopicsWithTalks query populates the UI components.
Sources: src/app/topics/page.tsx:18-35, src/app/topics/_components/topics-browse-content.tsx:28-48
Talk Metadata Integration
When viewing a specific talk, the TalkMetadataSidebar displays the associated topics as interactive pills.
// From src/app/talks/[speakerSlug]/[talkSlug]/_components/talk-metadata-sidebar.tsx
{topics.length > 0 ? (
topics.map((topic) => (
<Link
className="bg-muted text-foreground hover:bg-muted/80 inline-block rounded-full px-3 py-1.5 text-sm transition-colors"
href={`/topics/${topic.slug}`}
key={topic._id}
>
{topic.title}
</Link>
))
) : (
<span className="text-muted-foreground text-sm">No topics</span>
)}
Sources: src/app/talks/[speakerSlug]/[talkSlug]/_components/talk-metadata-sidebar.tsx:36-50
Summary
The Topics feature provides the primary taxonomical structure for the platform. By utilizing Convex join tables and paginated queries, the system ensures that users can discover content through specific biblical themes while maintaining strict data relationships and administrative controls.