scalesite/CLAUDE.md

# CLAUDE.md

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

## Project Overview

ScaleSite is a Next.js 16 frontend-only application for a digital agency service platform. It provides web design and AI automation services with a complete client portal. The application uses mock data only—no backend or database.

**Tech Stack:**
- Next.js 16.1.6 with App Router and Turbopack
- React 19.2.3
- TypeScript 5
- Tailwind CSS v4 (CSS-based theme configuration)
- shadcn/ui components (Radix UI primitives)
- Lucide React icons
- React Hook Form + Zod validation

## Development Commands

```bash
# Start development server (runs on port 3000 by default)
npm run dev

# Production build
npm run build

# Start production server
npm start

# Lint
npm run lint
```

## Architecture

### Page Structure

**Public Pages (Marketing Layout)**
- `/` - Landing page with hero, services, pricing, testimonials, FAQ
- `/services` - Service selection with toggle between Web Design and AI Automation
- `/login` and `/register` - Authentication pages

**Protected Pages (Dashboard Layout)**
- `/dashboard` - Client dashboard with stats, projects, tickets
- `/billing` - Subscription management, payment methods, invoice history

**Checkout Flow**
- `/checkout` - Multi-step checkout (Account → Billing → Payment)

### Layouts

Pages use one of two layout wrappers:

**MarketingLayout** (`components/layouts/marketing-layout.tsx`)
- Used by: `/`, `/services`
- Includes: SiteHeader, SiteFooter
- Sticky header with glass morphism effect

**Dashboard Layout** (sidebar layout)
- Used by: `/dashboard`, `/billing`
- Note: Dashboard pages currently render inline without a wrapper component
- Components reference: `DashboardSidebar` in `components/layouts/dashboard-sidebar.tsx`
- Navigation items: Dashboard, Projects, AI Automations, Support, Billing, Settings

**Auth Layout** (`components/auth/auth-layout.tsx`)
- Used by: `/login`, `/register`
- Split screen: hero image (left) + form (right)
- No header/footer

**Minimal Layout**
- Used by: `/checkout`
- Logo header only, no navigation

### Data & Types

**TypeScript Types** (`lib/types/index.ts`)
- `User`, `ServiceType`, `PricingTier`, `PricingPlan`
- `Project`, `ProjectStatus`, `ProjectStage`
- `SupportTicket`, `TicketStatus`
- `Invoice`, `InvoiceStatus`, `PaymentMethod`, `Subscription`
- `CheckoutSession`, `CheckoutStep`, `Address`
- `Testimonial`, `FAQ`, `DashboardStats`

**Mock Data** (`lib/mock-data/`)
- All data is mocked—no API calls
- Exports: `mockProjects`, `mockSupportTickets`, `mockInvoices`, `mockTestimonials`, `mockPricingPlans`, etc.
- Helper functions: `getPricingPlanById()`, `getPricingPlansByServiceType()`, `getAllFAQs()`

### Component Organization

```
components/
├── auth/           # Auth-related components (social login, password input)
├── billing/        # Subscription, payment methods, invoice table
├── checkout/       # Checkout steps, summary, payment forms
├── dashboard/      # Stats cards, project cards, tickets
├── layouts/        # Marketing layout, header, footer, sidebar
├── marketing/      # Hero, service cards, pricing, testimonials, FAQ
├── mobile/         # Mobile-specific components (if implementing separate views)
└── ui/             # shadcn/ui base components (button, card, input, etc.)
```

### Icon System

**Lucide React Only**
- All icons use Lucide React (`lucide-react` package)
- Icons passed as components: `icon={Rocket}` not `icon="rocket"`
- Do NOT use Material Symbols (previously caused display issues)
- Import pattern: `import { Rocket, Bot, ArrowRight } from 'lucide-react'`

**Component Props Pattern**
For components that accept icons:
```tsx
import { LucideIcon } from 'lucide-react'

interface Props {
  icon: LucideIcon  // Pass component, not string
}

export function Component({ icon: Icon }: Props) {
  return <Icon className="w-6 h-6" />
}
```

### Styling & Theme

**Tailwind CSS v4 Configuration** (app/globals.css)
- Theme defined inline with `@theme` directive
- Custom colors:
  - `primary`: #8B5CF6 (Electric Violet)
  - `background`: #0B0B0B (Deep Obsidian)
  - `surface`: #1E1E1E (Slate Gray)
- Dark mode by default: `<html lang="en" className="dark">` in root layout

**Utility Classes**
- `.glow-button` - Primary button with purple glow effect
- `.glass-card` - Glass morphism card background
- `.glass-nav` - Glass navigation header

### Special Patterns

**Checkout Suspense Boundary**
Checkout page uses `useSearchParams` which requires a Suspense boundary:
```tsx
// app/checkout/page.tsx
import { Suspense } from 'react'
import { CheckoutContent } from './checkout-content'

export default function CheckoutPage() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <CheckoutContent />
    </Suspense>
  )
}
```

The actual client component with `useSearchParams` is in `checkout-content.tsx`.

**Status Color Mapping**
Several components use Record types for status-based styling:
```tsx
const statusColors: Record<Project['status'], string> = {
  discovery: 'bg-blue-500/10 text-blue-400',
  design: 'bg-purple-500/10 text-purple-400',
  // ...
}
```

## Common Tasks

**Adding a New Page**
1. Create `app/route-name/page.tsx`
2. For marketing pages: wrap with `MarketingLayout`
3. For dashboard pages: render content inline (layout wrapper not yet implemented)

**Adding Mock Data**
1. Create file in `lib/mock-data/`
2. Export data and any helper functions
3. Re-export in `lib/mock-data/index.ts`

**Updating Icons**
- Always use Lucide React components
- Search available icons: https://lucide.dev/icons/
- Import and pass as component props

## Known Limitations

- No backend—all data is mocked
- Dashboard layout wrapper not implemented (pages render sidebar content inline)
- No authentication flow (login/register pages are UI only)
- No form validation connected (React Hook Form + Zod installed but not implemented)