Skip to content

CLAUDE.md

Latest commit

 

History

History
126 lines (96 loc) · 4.49 KB

CLAUDE.md

File metadata and controls

126 lines (96 loc) · 4.49 KB

CLAUDE.md

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

Development Commands

# Start development server
pnpm dev

# Build for production
pnpm build

# Run production server
pnpm start

# Database operations (Drizzle)
# Note: No db:push script in package.json - use drizzle-kit directly
npx drizzle-kit push
npx drizzle-kit generate
npx drizzle-kit studio

# Electron desktop builds
pnpm dist:win    # Windows
pnpm dist:linux  # Linux

Architecture Overview

Stack

  • Next.js 15 (App Router) - React 19.2.3
  • Supabase - Auth (SSR) + Storage
  • Drizzle ORM - PostgreSQL with postgres.js driver
  • Puck Editor - Self-hosted visual page builder
  • Google Gemini AI - Content generation (@google/generative-ai)
  • Tailwind CSS 4 - Styling
  • TipTap - Rich text editor

Zero-Config Demo Mode

The app runs without configuration using mock data when DATABASE_URL or NEXT_PUBLIC_SUPABASE_URL is missing:

  • src/db/index.ts exports a recursive proxy DB that returns empty arrays/nulls
  • src/lib/auth.ts returns MOCK_ADMIN user (demo@starter-kit.local)
  • All API routes gracefully handle missing DB/Supabase
  • Never blocks development - useful for UI work and testing

Database Schema (src/db/schema.ts)

Table Purpose Key Fields
users Admin/editors role: ADMIN|EDITOR
posts CMS content type: ARTICLE|PROJECT|PAGE|NEWS, published, slug
pages Puck editor data slug (PK), data: jsonb, status: draft|published
media_files Uploaded assets Stored in Supabase Storage, tracked in DB
site_settings Key/value config Generic settings store
contact_messages Contact form submissions
hero_slides Homepage slider order, active
activity_logs Audit trail action, entity, entity_id

Auth Pattern

  • Server components: Use requireAuth() from @/lib/auth.ts - redirects to /login if unauthenticated
  • API routes: Use requireApiAuth(request) from @/lib/api-auth.ts - returns 401 JSON response
  • Supabase SSR: Client created per-request using cookies from @/lib/supabase/server.ts

Puck Visual Editor

Config: src/lib/puck/config.tsx

  • Component registry with categories (layout, hero, content, forms, etc.)
  • Custom fields: richTextField, imageField, documentField, colorField, iconField
  • All components wrapped with CanvasComponentWrapper for inline editing

Data flow:

  1. Pages stored in pages table as JSONB (data column)
  2. Public routes rendered by src/app/(public)/[slug]/page.tsx
  3. Admin editor at /admin/editor/[...puckPath]

AI Integration: src/app/api/puck/generate/route.ts uses Gemini to generate Puck JSON from prompts

Dynamic Page Routing

/[slug]              → Puck pages from DB (excluded: home, despre-noi, etc.)
/articole/[slug]     → Blog posts (type=ARTICLE)
/proiecte/[slug]     → Projects (type=PROJECT)

Important: EXCLUDED slugs in [slug]/page.tsx have dedicated routes and won't render from Puck data.

API Routes Structure

Route Purpose
/api/auth/* Supabase auth callbacks
/api/puck/generate AI page generation (Gemini)
/api/ai/process-text Text formatting/correction/expansion
/api/pages/[slug] CRUD for Puck pages
/api/posts CMS posts CRUD
/api/media Media upload/management
/api/hero-slides Hero slider CRUD
/api/contact Contact form submissions

Environment Variables

Critical: .env.example was updated to fix GEMINI_API_KEY → GOOGLE_AI_API_KEY

Required for full functionality:

  • DATABASE_URL - PostgreSQL connection
  • NEXT_PUBLIC_SUPABASE_URL + NEXT_PUBLIC_SUPABASE_ANON_KEY + SUPABASE_SERVICE_ROLE_KEY
  • GOOGLE_AI_API_KEY - For AI features

Optional:

  • SMTP_* - Email sending
  • NEXT_PUBLIC_GA_ID - Analytics
  • NEXT_PUBLIC_SITE_* - Metadata defaults (has fallbacks)

Component Patterns

Puck Components (src/lib/puck/components/):

  • All receive puck, id, positionType props from editor
  • Use CanvasComponentWrapper for inline editing transforms
  • Strip internal props with strip({ puck, id, ...rest }) helper

Rich Text: Uses TipTap with custom extensions:

  • Character count, color, highlight, image, link, placeholder, text align, underline
  • Configured in ExtendedRichTextField

Media Picker: Integrates with Supabase Storage for image/document uploads