Developer Guidelines & Best Practices

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/components/ui/primitives/README.md
• convex/model/topics/mutations.ts

This document outlines the technical standards, architectural patterns, and development workflows for the Tread Talks platform. It ensures code quality, maintainability, and consistency across the full-stack environment. Developers must follow these guidelines when contributing to the Next.js frontend, Convex backend, or UI component library.

Sources: README.md:1-15, AGENTS.md:1-5

Core Workflow & Tooling

The project uses pnpm as the primary package manager. Developers must maintain code health by running automated scripts before finalizing tasks.

Mandatory Scripts

Script	Description
pnpm style	Fixes formatting and linting issues using ultracite.
pnpm typecheck	Validates TypeScript types across the project.
pnpm run audit:code	Runs a deep audit for hotspots and code health via fallow.
pnpm dev	Starts Next.js and Convex development servers in parallel.

Sources: package.json:7-25, AGENTS.md:8-12

Development Rules

• Protocol: Always use https when testing local URLs.
• Naming: Use alphabetized imports, object keys, and props unless grouping related items improves readability.
• Styling: Avoid emojis in code, commits, and PR titles.
• Documentation: Use JSDoc only for non-obvious context (max 2 lines). Omit @param and @returns unless documenting side effects or constraints.

Sources: AGENTS.md:13-28

System Architecture

The project organizes code by domain/feature rather than technical layers. This structure groups business logic, components, and data fetching within specific functional units.

Feature Directory Structure

Next.js Data Fetching Patterns

Developers must fetch data within individual components rather than layout.tsx. Server-side fetching in layouts forces dynamic rendering on all child routes, which prevents static optimization.

Convex Backend Best Practices

Convex serves as the database and backend function layer. Files in the convex/ directory must follow specific naming and implementation rules to avoid deployment errors.

Implementation Guidelines

• File Naming: Use camelCase for multi-word files (e.g., affiliateLinks.ts) and lowercase for single-word files. Kebab-case is strictly forbidden.
• Validation: Every function must include argument validators using the v object from convex/values.
• Auth Guards: Never accept userId as a function argument. Derive user identity server-side using ctx.auth.getUserIdentity().
• Error Handling: Mutations should use the useMutation custom hook with onError mapping to getErrorMessage(error).

Sources: convex/_generated/ai/guidelines.md:100-110, AGENTS.md:92-105, convex/model/topics/mutations.ts:20-35

Query and Action Directives

Directive	Use Case	Location
'use cache'	Public queries with no authentication.	queries/
'use cache: private'	Authentication-dependent queries.	queries/
'use server'	Server Actions or mutations.	actions/

Sources: AGENTS.md:120-135

UI Development & Coss UI

The project utilizes Coss UI, which is built on Base UI. UI components are categorized by their usage scope: Shared, Feature, and Route.

UI Primitive Rules

Primitives located in src/components/ui/primitives/ are vendor-managed and must never be edited directly.

1. Barrel Imports: Always import from @/components/ui, never from primitive paths.
2. Customization: If a primitive requires changes, create a wrapper in src/components/ui/ and update the barrel export.
3. Ref Prop: Use the standard ref prop instead of React.forwardRef (React 19 standard).

Sources: src/components/ui/primitives/README.md:1-20, AGENTS.md:52-65, AGENTS.md:175-178

React Best Practices

• No Manual Memoization: Do not use useMemo, useCallback, or React.memo. React 19 handles these optimizations automatically.
• Prop Delegation: Use the name delegated when spreading props onto child elements (e.g., {...delegated}).
• Explicit Type Imports: Import types directly from React (e.g., import type { ReactNode } from 'react').

Sources: AGENTS.md:167-185

Analytics & Monitoring

Product analytics are managed via Segment, with Mixpanel acting as the primary destination.

• Segment: Use NEXT_PUBLIC_SEGMENT_WRITE_KEY. Provide distinct keys for dev and prod environments.
• Mixpanel: Enabled via Segment cloud-mode (Actions). Do not use device-mode or inject tokens directly into the Next.js environment.
• Error Monitoring: Sentry is integrated for tracking runtime errors.

Sources: README.md:37-47, package.json:40-45