Skip to content

CLAUDE.md

Latest commit

 

History

History
132 lines (101 loc) · 4.65 KB

CLAUDE.md

File metadata and controls

132 lines (101 loc) · 4.65 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Resonex is an AI-powered newsletter automation platform built for the Convex + Resend Hackathon. It's a full-stack web application that enables users to create, manage, and track email campaigns with AI-generated content and A/B testing capabilities.

Development Commands

Essential Commands

# Full development mode (frontend + backend)
npm run dev

# Frontend only (Next.js with Turbopack)
npm run dev:frontend

# Backend only (Convex)
npm run dev:backend

# Production build
npm run build

# Production server
npm run start

# Code linting
npm run lint

Development Workflow

  1. Run npm run dev to start both frontend and backend
  2. Frontend runs on http://localhost:3000
  3. Convex backend automatically syncs and provides real-time updates
  4. Use npm run lint before committing changes

Architecture Overview

Technology Stack

  • Frontend: Next.js 15 (App Router), React 19, TypeScript, TailwindCSS v4
  • Backend: Convex (real-time database + functions), OpenAI API, Resend
  • UI: shadcn/ui components with Radix UI, Lucide React icons
  • Authentication: Clerk
  • Visualization: React Flow, Recharts
  • Background Jobs: @convex-dev/workpool

Key Directories

/app/ - Next.js App Router

  • Main routes: /dashboard (authenticated area), / (landing page)
  • Dashboard structure: Nested routes under /dashboard/ including campaigns, activity, logs, settings
  • Authentication: /sign-in/ routes with Clerk integration

/components/ - React Components

  • /ui/: shadcn/ui base components (buttons, cards, dialogs, etc.)
  • /icons/: Lucide React icon components
  • /nodes/: React Flow nodes for visual campaign creation
  • /emails/: Email template components
  • Core components: CampaignCard, Sidebar, Header, MetricDashboard

/convex/ - Backend Logic

  • schema.ts: Database schema definition (DO NOT MODIFY without understanding implications)
  • campaigns.ts: Campaign management functions
  • abEmails.ts: A/B testing email logic
  • events.ts: Event tracking and webhooks
  • llmCall.ts: OpenAI integration for AI content generation
  • http.ts: HTTP router for webhooks (Resend integration)

Database Schema (Convex)

Main tables: campaigns, users, abEmails, abEmailResend, emailAnalytics, reactFlowCanvas

Data Flow Architecture

  1. User Interaction → React components in /app/ or /components/
  2. API Calls → Convex functions in /convex/ (queries, mutations, actions)
  3. AI Processing → OpenAI API via llmCall.ts
  4. Email Delivery → Resend API with tracking via http.ts
  5. Event Tracking → Webhooks from Resend back to Convex
  6. Real-time Updates → Convex real-time data sync to frontend

Key Patterns and Conventions

Component Development

  • Use shadcn/ui components as base building blocks
  • Follow the existing component structure in /components/
  • Implement new icons in /components/icons/ using Lucide React
  • Use TypeScript interfaces for component props

Backend Development

  • All database operations go through Convex functions
  • Use TypeScript types from schema.ts for type safety
  • Implement background jobs using @convex-dev/workpool
  • Follow the existing function patterns in /convex/

Styling

  • Use TailwindCSS v4 with CSS variables for theming
  • Follow the neutral color scheme established in the project
  • Use utils.ts for clsx and tailwind-merge utilities

State Management

  • Primary state management through Convex real-time queries
  • React state for local UI state
  • Use custom hooks in /hooks/ for complex logic

Important Notes

Convex Development

  • Convex schema changes require careful consideration
  • Use convex dev for backend development
  • Real-time updates are automatic - no manual polling needed

AI Integration

  • OpenAI API calls are centralized in llmCall.ts
  • AI-generated content is used for email subject lines and body content
  • Implement new AI features by extending the existing patterns

Email Integration

  • Resend is used for email delivery
  • Webhooks track email events (delivered, opened, clicked)
  • A/B testing is implemented through abEmails.ts

Authentication

  • Clerk handles all authentication
  • User data is synchronized between Clerk and Convex
  • Protect dashboard routes using Clerk middleware

Testing and Quality

  • No specific test framework is configured
  • Use npm run lint for code quality checks
  • TypeScript provides compile-time type checking
  • Follow existing code patterns for consistency