Architecture & Project Structure

Relevant source files

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

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

TREAD Talks is a modern, full-stack platform for finding and sharing Christ-centered talks. The architecture separates the frontend concerns (Next.js) from the backend logic (Convex) while maintaining a strict domain-driven feature structure. The project uses a unified tech stack including React 19, Next.js 16, and Tailwind CSS v4 to provide a high-performance web experience.

Sources: README.md:1-10, package.json:53-57

Core Tech Stack

The project utilizes the following technologies:

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

Sources: README.md:5-15, package.json:53-85

Directory Organization

The codebase follows a domain/feature organization rather than a technical layer organization. This means all logic related to a specific business domain (e.g., talks, speakers) resides within a single directory.

Root Directories

• convex/: Contains the database schema and backend functions.
• src/app/: Contains Next.js App Router pages and route-specific components.
• src/features/: Contains business domain logic organized by feature.
• src/components/: Contains shared UI components used across multiple features.
• src/services/: Contains infrastructure concerns such as auth, email, and error monitoring.

Sources: AGENTS.md:36-47

Feature Structure

Each directory in src/features/{domain}/ follows a standardized structure to ensure consistency across the application:

This diagram shows the internal organization of a single feature module within the project.
Sources: AGENTS.md:52-60

Backend Architecture (Convex)

The backend is powered by Convex, which handles data storage, server-side functions, and reactive updates. Convex logic is organized into two primary categories:

1. Public API: Defined in convex/{domain}.ts, these functions are exposed to the frontend.
2. Model Layer: Located in convex/model/{domain}/, these directories contain entity-specific helpers, queries, and mutations.

Convex Data Flow

This diagram illustrates the flow of data for a write operation (mutation) from the client to the database.
Sources: AGENTS.md:104-120, convex/_generated/ai/guidelines.md:83-100

UI Architecture & Component Hierarchy

The project implements a strict hierarchy for React components to maintain separation of concerns:

1. UI Primitives: Located in src/components/ui/primitives/. These are vendor components (Coss UI/Base UI) and must never be edited directly.
2. UI Wrappers: Located in src/components/ui/. These wrap primitives to provide project-specific styling and overrides.
3. Shared Components: Located in src/components/. General-purpose layouts and headers used across the entire site.
4. Feature Components: Located in src/features/{domain}/components/. Components specific to a business domain.
5. Route Components: Located in src/app/{route}/_components/. Components used only by a specific route.

Sources: AGENTS.md:63-75, src/components/ui/primitives/README.md:1-20

Global Layout & Providers

The RootLayout in src/app/layout.tsx wraps the entire application with necessary providers. Data fetching is avoided in layouts to prevent forcing children into dynamic rendering.

Provider	Purpose
ThemeProvider	Manages light/dark mode.
AuthProvider	Handles user session and authentication state.
AnalyticsProvider	Manages Segment and Vercel Analytics.
ToastProvider	Provides global notification system.
ErrorBoundary	Catches and logs application errors using Sentry.

Sources: src/app/layout.tsx:64-85, AGENTS.md:87-95

Naming & Development Conventions

• File Naming: Kebab-case is used for all src/ folders. Convex files use camelCase (e.g., affiliateLinks.ts) because Convex does not support kebab-case in deployments.
• Imports: Imports must be alphabetized. Object keys and destructured props must also follow alphabetical order.
• Memoization: React 19's compiler is utilized; manual memoization via useMemo, useCallback, or React.memo is prohibited.
• Data Access: Public queries use 'use cache' or 'use cache: private' for Next.js caching, with invalidation handled via updateTag.

Sources: AGENTS.md:15-32, AGENTS.md:108-115, AGENTS.md:143-150

Summary

The TREAD Talks architecture emphasizes a clear separation between domain-specific business logic (src/features) and infrastructure (src/services, convex). By enforcing strict component layering and backend naming conventions, the project ensures scalability and maintainability. The use of Convex as a reactive backend simplifies data synchronization between the database and the Next.js frontend.

Sources: AGENTS.md:36-50, README.md:1-10