CLAUDE.md

CLAUDE.md

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

Project Overview

Instapitch.io is an AI-powered pitch deck platform for entrepreneurs. Currently in early development phase (Day 1 of a 3-week sprint) targeting ₹5,000 revenue per pitch deck through a credit-based system.

Development Commands

# Package manager: bun (always use bun, not npm/yarn)
bun install              # Install dependencies
bun run dev              # Start development server (port 3000)
bun run build            # Build for production
bun run start            # Start production server

# Database commands
bun run db:push          # Push schema changes to database
bun run db:generate      # Generate Prisma migrations
bun run db:studio        # Open Prisma Studio GUI

# Code quality
bun run lint             # Run ESLint
bun run lint:fix         # Fix ESLint issues
bun run typecheck        # TypeScript type checking
bun run format:check     # Check Prettier formatting
bun run format:write     # Apply Prettier formatting

# UI Components
bunx --bun shadcn@latest add [component]  # Add shadcn/ui components

Architecture

Stack

• Framework: Next.js 15 (App Router) with React 19
• Styling: Tailwind CSS 4 + shadcn/ui components
• Database: PostgreSQL + Prisma ORM
• API: tRPC for type-safe API calls
• Auth: NextAuth.js (prepared for Google OAuth)
• State: Zustand (client), React Query (server state via tRPC)
• Forms: React Hook Form + Zod validation
• Deployment: Vercel (later GCP)

Project Structure

src/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes (auth, tRPC)
│   └── (auth)/            # Auth-related pages
├── server/                # Backend logic
│   ├── api/              # tRPC routers
│   │   ├── root.ts       # Main router configuration
│   │   └── routers/      # Individual API routers
│   ├── auth/             # NextAuth configuration
│   └── db.ts             # Prisma client singleton
├── trpc/                  # tRPC client setup
└── env.js                # Environment variable validation

Key Architectural Decisions

1. tRPC Router Pattern: All API routes go in src/server/api/routers/. Each router must be imported and added to appRouter in root.ts.

2. Database Access: Always use the Prisma client from src/server/db.ts (singleton pattern for development).

3. Environment Variables: Validated through src/env.js using Zod. Add new env vars there first.

4. Authentication: NextAuth configured but no providers active yet. Google OAuth will be primary auth method.

5. Form Handling: All forms must use React Hook Form with Zod validation schemas.

Form Handling Best Practices

Overview

We use React Hook Form for all form handling in the project. This provides better performance, built-in validation, and cleaner code.

Dependencies

• react-hook-form: Form state management
• @hookform/resolvers: Integration with validation libraries
• zod: Schema validation

Implementation Guidelines

1. Always define TypeScript interfaces and Zod schemas:

// Define the form interface
interface LoginFormData {
  email: string;
  password: string;
  rememberMe: boolean;
}

// Define the Zod schema
const loginSchema = z.object({
  email: z.string().email("Invalid email address"),
  password: z.string().min(8, "Password must be at least 8 characters"),
  rememberMe: z.boolean().default(false),
});

2. Use proper form setup with TypeScript:

const form = useForm<LoginFormData>({
  resolver: zodResolver(loginSchema),
  defaultValues: {
    email: "",
    password: "",
    rememberMe: false,
  },
});

3. Register inputs correctly:

// For standard inputs
<Input {...register("email")} />

// For controlled components (e.g., Checkbox)
<Controller
  control={control}
  name="rememberMe"
  render={({ field }) => (
    <Checkbox
      checked={field.value}
      onCheckedChange={field.onChange}
    />
  )}
/>

4. Handle errors consistently:

{errors.email && (
  <p className="mt-1 text-sm text-red-500">
    {errors.email.message}
  </p>
)}

5. Use formState for loading states:

const { formState: { isSubmitting, errors } } = form;

<Button disabled={isSubmitting}>
  {isSubmitting ? "Submitting..." : "Submit"}
</Button>

Reusable Patterns

1. Custom form field components - Create wrappers for common patterns
2. Shared validation schemas - Reuse common validations (email, password, etc.)
3. Form hooks - Extract common form logic into custom hooks
4. Error display components - Consistent error styling across forms

Migration Strategy

When updating existing forms:

1. Define the TypeScript interface
2. Create the Zod schema
3. Replace useState with useForm
4. Update input registrations
5. Update error handling
6. Test thoroughly

Current State

• Boilerplate cleaned up, simple "Hello World" page
• Basic tRPC setup with health check endpoint
• Database schema includes only auth-related tables
• No AI integrations or features implemented yet

Planned Features (3-Week Sprint)

Week 1: Auth, Dashboard, One-Pager Generator, AI Integration Week 2: Pitch Deck Builder, Document Processing, n8n Workflows Week 3: Collaboration, Payments, Polish, Launch

Important Context

1. Solo Developer: Working 15-20 hours/day for 3 weeks
2. Design Approach: No Figma, designing on-the-go with shadcn/ui
3. Color Scheme: violet-to-blue gradient primary, white backgrounds (light), dark neutral (dark mode)
4. AI Models: Will integrate OpenAI GPT-4, Claude Sonnet Pro, Perplexity Sonar via n8n
5. Revenue Model: Credit-based system (₹5,000 per complete pitch deck)

Database Connection

Local PostgreSQL expected at:

DATABASE_URL="postgresql://postgres:123456@localhost:5432/instapitch"

Use ./start-database.sh to start a Docker container if needed.

Development Priorities

1. Get authentication working with Google OAuth
2. Build company profile and dashboard
3. Implement one-pager generator (simpler MVP feature)
4. Add AI integration for content generation
5. Build pitch deck editor with drag-and-drop
6. Implement credit system and payments

Git Conventions

Commit Messages

• Always lowercase
• One-liner, very short
• Use prefixes: fix:, feat:, chore:, style:, refactor:
• Examples:
  • feat: add google oauth login
  • fix: resolve build error in trpc
  • chore: update dependencies
  • style: format code with prettier
  • refactor: simplify auth logic

Pre-commit Hooks (Husky)

Automatically runs on every commit:

1. TypeScript type checking
2. ESLint
3. Prettier formatting check