Getting Started & Local Setup

Relevant source files

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

• README.md
• AGENTS.md
• package.json
• convex/_generated/ai/guidelines.md
• src/app/layout.tsx

TREAD Talks is a full-stack faith-based content platform built with Next.js, Convex, and Better Auth. This guide provides instructions for configuring the local development environment and understanding the project's technical architecture.

Sources: README.md:3-5, AGENTS.md:16-25

Prerequisites

Before setting up the project, ensure your environment meets the following requirements:

• Node.js: Version 22+ (LTS recommended).
• Package Manager: pnpm is the required tool for dependency management.
• Database/Backend: Access to a Convex project.
• Authentication: Better Auth credentials.

Sources: README.md:18-20, AGENTS.md:6-6, package.json:96-96

Local Installation

Follow these steps to initialize the repository on your local machine:

1. Clone the repository: Download the source code to your local environment.
2. Install dependencies: Run pnpm install to fetch all necessary packages.
3. Configure environment variables: Copy .env.example to .env.local and populate it with your specific service keys.
4. Start development services: Execute pnpm dev to run the Next.js frontend and Convex backend in parallel.

Sources: README.md:25-36, package.json:11-14

The following diagram illustrates the parallel execution flow of the development environment:

The pnpm dev command triggers concurrent processes for the backend database functions and the frontend web server.
Sources: package.json:11-14

Development Workflow & Scripts

The project utilizes pnpm for all tasks. Developers must follow specific validation workflows before completing tasks.

Core Scripts

Command	Description
pnpm dev	Starts Next.js (frontend) and Convex (backend) in parallel.
pnpm build	Compiles the Next.js application for production.
pnpm release	Deploys backend functions to Convex production.
pnpm typecheck	Runs the TypeScript compiler to validate types.
pnpm style	Runs ultracite fix to enforce code formatting.
pnpm audit:code	Runs fallow to audit code health and hotspots.

Sources: package.json:9-25, AGENTS.md:6-10

Mandatory Checks

Before marking a task as complete, you must execute the following:

1. Run pnpm style to format code.
2. Run pnpm typecheck to ensure type safety.
3. After meaningful changes, run pnpm run audit:code for a health assessment.

Sources: AGENTS.md:6-10

Architecture Overview

The project follows a Feature-Based Organization rather than a technical layer organization. This groups logic by domain (e.g., talks, speakers, topics) to improve maintainability.

Directory Structure

• convex/: Contains the database schema and backend functions.
• src/app/: Next.js App Router pages and route-specific components.
• src/features/: Core business domains containing actions, hooks, and schemas.
• src/components/: Shared UI components and primitives.
• src/services/: Infrastructure concerns like auth, email, and error monitoring.

Sources: AGENTS.md:32-46

Data Flow Pattern

The application uses Convex for real-time data and server-side logic. The following sequence shows how a client interacts with the backend:

Client interactions flow through Server Actions to Convex mutations which execute transactional database writes.
Sources: AGENTS.md:104-122, convex/_generated/ai/guidelines.md:54-65

Tech Stack Summary

Layer	Technology
Frontend Framework	Next.js 16 & 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

Sources: README.md:7-16, package.json:30-58

Configuration

Environment Variables

Configure the following in .env.local for local development:

• NEXT_PUBLIC_CONVEX_URL: Your Convex deployment URL.
• NEXT_PUBLIC_SEGMENT_WRITE_KEY: The Segment source key for tracking.
• BETTER_AUTH_SECRET: Secret for session management.

Sources: README.md:29-30, README.md:41-43

UI Primitives

UI primitives located in src/components/ui/primitives/ are vendor components from Coss UI. Never edit these files directly. To customize a component, create a wrapper or extension in src/components/ui/.

Sources: AGENTS.md:73-77, src/components/ui/primitives/README.md:7-15

Summary

Setting up TREAD Talks requires Node.js 22 and pnpm. The project leverages a dual-process development mode that runs Next.js and Convex concurrently. Developers must adhere to the feature-based directory structure and use the provided validation scripts (style, typecheck, audit:code) to maintain code quality. All backend operations are handled through Convex functions, while the frontend utilizes Next.js 16 and React 19 patterns.