Introduction to TREAD Talks

Relevant source files

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

• README.md
• AGENTS.md
• src/app/about/page.tsx
• convex/model/talks/queries.ts
• convex/model/talks/mutations.ts
• convex/model/topics/mutations.ts
• package.json

TREAD Talks is a full-stack faith-based content platform. It enables users to discover, bookmark, and share Christ-centered sermons and talks. Originally created as a personal tool for tracking sermons listened to during physical exercise, the platform has evolved into a comprehensive resource for spiritual growth.

The system integrates modern web technologies to provide a high-performance experience, focusing on content organization by speaker and topic. It employs a serverless architecture where the frontend handles user interaction and the backend manages data persistence and real-time synchronization.

Sources: README.md:3-5, src/app/about/page.tsx:12-25

Core Technology Stack

The project utilizes a modern development stack focused on type safety, performance, and developer experience.

Layer	Technology
Frontend Framework	Next.js 16 (App Router), React 19
Styling	Tailwind CSS v4
Backend / Database	Convex
Authentication	Better Auth
UI Components	Coss UI (built on Base UI)
Forms & Validation	React Hook Form, Zod
Analytics	Vercel Web Analytics, Segment, Mixpanel

Sources: README.md:7-18, package.json:44-77

System Architecture

TREAD Talks follows a feature-based organization pattern. This structure groups code by business domain rather than technical layer to improve maintainability and discoverability.

Application Layers

The application is divided into three primary environments:

1. Frontend (Next.js): Manages routing, page rendering, and client-side state.
2. Backend (Convex): Handles database schema, server-side functions, and real-time data flow.
3. Infrastructure: Services for authentication (Better Auth), email (Resend), and error monitoring (Sentry).

Directory Structure

Code organization adheres to strict domain separation:

• src/features/{domain}/: Contains domain-specific logic including actions, components, hooks, and schemas.
• convex/model/{domain}/: Defines entity-specific backend helpers, queries, and mutations.
• src/components/ui/: Contains reusable UI primitives.

Sources: AGENTS.md:55-75, AGENTS.md:120-125

Data Domain Model

The platform organizes content around several key entities. The primary unit of content is the Talk, which is associated with Speakers, Topics, and Collections.

Entity Relationships

• Speaker: The individual delivering the talk.
• Talk: The core content document containing media URLs, descriptions, and scripture references.
• Topic: Categorical tags for talks (e.g., "Faith", "Grace").
• Clip: Short, impactful segments extracted from a full talk.
• Collection: A group of related talks, often in a specific series order.

Content Management Logic

The backend implements specific naming and lifecycle conventions for data management.

Query and Mutation Naming

Convex functions follow a standardized naming convention to indicate their purpose:

• get*: Fetches a single document or null.
• list*: Returns a filtered array of public data.
• create/update/archive: Standard write operations.
• add*To* / remove*From*: Manages associations between entities (e.g., adding a talk to a topic).

Sources: AGENTS.md:130-142

Caching and Revalidation

The platform utilizes Next.js and Convex caching strategies for optimal performance:

• 'use cache': Applied to public queries that do not require authentication.
• 'use cache: private': Applied to user-specific or authenticated queries.
• updateTag: Used in Server Actions to trigger immediate "read-your-writes" semantics, ensuring users see changes instantly.

Sources: AGENTS.md:148-171

User Experience and UI Patterns

The UI is built using Coss UI, which provides accessible primitives.

Layout Principles

• Server Fetching: Data fetching is avoided in layout.tsx to prevent forcing children into dynamic rendering. Instead, components fetch their own data internally.
• Auth Guards: Routes are protected using requireCurrentUser or requireAdminUser helpers, which handle redirection before page rendering.
• Feedback: Mutations use a custom useMutation hook that provides isLoading and error states for UI feedback.

Sources: AGENTS.md:100-117, AGENTS.md:183-190, src/app/talks/new/page.tsx:11

Field Validation

Form handling leverages React Hook Form with Zod schemas. A critical pattern in the project is the use of the match prop in FieldError components. This allows external validation libraries to control error visibility, bypassing native HTML5 validity checks.

Sources: AGENTS.md:218-232, src/features/talks/components/edit-talk-sheet.tsx:84-100

Summary

TREAD Talks provides a structured environment for consuming spiritual content. By organizing talks through a feature-driven architecture and utilizing Convex for real-time backend capabilities, the platform maintains high performance and developer clarity. The integration of "Better Auth" and specific UI patterns ensures a secure and responsive user experience.