prmbr-image-mksaas/CLAUDE.md

CLAUDE.md

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

Development Commands

Core Development

• pnpm dev - Start development server with content collections
• pnpm build - Build the application and content collections
• pnpm start - Start production server
• pnpm lint - Run Biome linter (use for code quality checks)
• pnpm format - Format code with Biome

Database Operations (Drizzle ORM)

• pnpm db:generate - Generate new migration files based on schema changes
• pnpm db:migrate - Apply pending migrations to the database
• pnpm db:push - Sync schema changes directly to the database (development only)
• pnpm db:studio - Open Drizzle Studio for database inspection and management

Content and Email

• pnpm content - Process MDX content collections
• pnpm email - Start email template development server on port 3333

Project Architecture

This is a Next.js 15 full-stack SaaS application with the following key architectural components:

Core Stack

• Framework: Next.js 15 with App Router
• Database: PostgreSQL with Drizzle ORM
• Authentication: Better Auth with social providers (Google, GitHub)
• Payments: Stripe integration with subscription and one-time payments
• UI: Radix UI components with TailwindCSS
• State Management: Zustand for client-side state
• Internationalization: next-intl with English and Chinese locales
• Content: Fumadocs for documentation and MDX for content
• Code Quality: Biome for formatting and linting

Key Directory Structure

• src/app/ - Next.js app router with internationalized routing
• src/components/ - Reusable React components organized by feature
• src/lib/ - Utility functions and shared code
• src/db/ - Database schema and migrations
• src/actions/ - Server actions for API operations
• src/stores/ - Zustand state management
• src/hooks/ - Custom React hooks
• src/config/ - Application configuration files
• src/i18n/ - Internationalization setup
• src/mail/ - Email templates and mail functionality
• src/payment/ - Stripe payment integration
• src/credits/ - Credit system implementation
• content/ - MDX content files for docs and blog
• messages/ - Translation files (en.json, zh.json) for internationalization

Authentication & User Management

• Uses Better Auth with PostgreSQL adapter
• Supports email/password and social login (Google, GitHub)
• Includes user management, email verification, and password reset
• Admin plugin for user management and banning
• Automatic newsletter subscription on user creation

Payment System

• Stripe integration for subscriptions and one-time payments
• Three pricing tiers: Free, Pro (monthly/yearly), and Lifetime
• Credit system with packages for pay-per-use features
• Customer portal for subscription management

Feature Modules

• Blog: MDX-based blog with pagination and categories
• Docs: Fumadocs-powered documentation
• AI Features: Image generation with multiple providers (OpenAI, Replicate, etc.)
• Newsletter: Email subscription system
• Analytics: Multiple analytics providers support
• Storage: S3 integration for file uploads

Development Workflow

1. Use TypeScript for all new code
2. Follow Biome formatting rules (single quotes, trailing commas)
3. Write server actions in src/actions/
4. Use Zustand for client-side state management
5. Implement database changes through Drizzle migrations
6. Use Radix UI components for consistent UI
7. Follow the established directory structure
8. Use proper error handling with error.tsx and not-found.tsx
9. Leverage Next.js 15 features like Server Actions
10. Use next-safe-action for secure form submissions

Configuration

• Main config in src/config/website.tsx
• Environment variables template in env.example
• Database config in drizzle.config.ts
• Biome config in biome.json with specific ignore patterns
• TypeScript config with path aliases (@/* for src/*)

Testing and Quality

• Use Biome for linting and formatting
• TypeScript for type safety
• Environment variables for configuration
• Proper error boundaries and not-found pages
• Zod for runtime validation

Important Notes

• The project uses pnpm as the package manager
• Database schema is in src/db/schema.ts with auth, payment, and credit tables
• Email templates are in src/mail/templates/
• The app supports both light and dark themes
• Content is managed through MDX files in the content/ directory
• The project includes comprehensive internationalization support