frontend.porwoll.de/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

## Project Overview

porwoll.de frontend — a Next.js 16 application for Martin Porwoll (Whistleblower, Unternehmer, Mensch). Consumes Payload CMS as a headless backend.

**Tenant:** porwoll (ID: 1, Slug: porwoll)
**Tech Stack:** Next.js 16, React 19, TypeScript, Tailwind CSS 4
**Backend API:** https://cms.c2sgmbh.de/api
**Package Manager:** pnpm
**Design System:** Definity Template (light, professional)

## Commands

```bash
pnpm dev          # Development server
pnpm build        # Production build
pnpm start        # Start production server
pnpm lint         # ESLint
```

## Environment Variables

Create `.env.local`:

```env
NEXT_PUBLIC_PAYLOAD_URL=https://cms.c2sgmbh.de
NEXT_PUBLIC_TENANT_ID=1
NEXT_PUBLIC_TENANT_SLUG=porwoll
NEXT_PUBLIC_SITE_URL=https://porwoll.de
NODE_ENV=production
```

## Shared Contracts Package

This project uses `@c2s/payload-contracts` for the API client and types.

**Architecture:**
- `src/lib/cms.ts` — Shared PayloadClient instance (tenant: porwoll, ID: 1)
- `src/lib/api.ts` — API functions powered by contracts client

**Contracts Repo:** `github:complexcaresolutions/payload-contracts`

**Types:** Imported directly from `@c2s/payload-contracts/types`. No local type overrides.

**Updating Contracts:**
```bash
pnpm update @c2s/payload-contracts
pnpm build  # Verify types still compile
```

## Design System (Definity Template)

Full guidelines: `docs/DESIGN.md`

### Key Tokens

| Token | Value | Usage |
|-------|-------|-------|
| `dark` | #111111 | Headings, dark backgrounds |
| `accent` | #2CAADF | Links, highlights |
| `gray` | #777777 | Body text |
| `light-bg` | #f4f4f4 | Section backgrounds |

### Fonts

- **Headings:** Montserrat Bold, UPPERCASE, letter-spacing 2-5px
- **Body:** Open Sans Light (300), 14px, letter-spacing 0.2px
- Loaded via `next/font/google` (CSS variables --font-montserrat, --font-open-sans)

### Key Patterns

- All headings are UPPERCASE with generous letter-spacing
- Cards: material shadow, hover lift (-10px translateY)
- Navigation: transparent-to-solid on scroll (100px threshold)
- Animations: framer-motion, viewport-triggered (once: true)
- Section padding: ws-s (50px), ws-m (100px), ws-l (160px)
- Tailwind v4: theme config in globals.css via @theme, no tailwind.config.ts

### Component Library

- `src/components/ui/Button.tsx` — 6 variants, 3 sizes
- `src/components/ui/Container.tsx` — 4 width options
- `src/components/ui/SectionHeader.tsx` — title + subtitle
- `src/components/Navigation.tsx` — fixed, transparent/solid
- `src/components/Footer.tsx` — social bar, widgets, copyright
- `src/lib/typography.ts` — heading classes, prose styles
- `src/lib/animations.ts` — framer-motion variants
- `src/lib/utils.ts` — cn() utility (clsx + tailwind-merge)

## Architecture

### Directory Structure

```
src/
├── app/
│   ├── layout.tsx          # Root layout (Montserrat + Open Sans)
│   ├── template.tsx        # Page transitions (framer-motion)
│   ├── globals.css         # Tailwind v4 @theme config
│   ├── page.tsx            # Homepage (CMS page: "home")
│   └── [slug]/page.tsx     # Dynamic CMS pages
├── components/
│   ├── Navigation.tsx      # Transparent-to-solid nav
│   ├── Footer.tsx          # Dark footer with widgets
│   ├── ui/                 # Design system primitives
│   │   ├── Button.tsx
│   │   ├── Container.tsx
│   │   └── SectionHeader.tsx
│   └── blocks/             # CMS block components
│       ├── index.tsx        # Block renderer
│       ├── HeroBlock.tsx
│       ├── TextBlock.tsx
│       ├── CardGridBlock.tsx
│       ├── QuoteBlock.tsx
│       ├── ImageTextBlock.tsx
│       ├── CTABlock.tsx
│       ├── ContactFormBlock.tsx
│       ├── TimelineBlock.tsx
│       └── DividerBlock.tsx
└── lib/
    ├── cms.ts              # PayloadClient instance
    ├── api.ts              # API functions
    ├── utils.ts            # cn() utility
    ├── typography.ts       # Typography class strings
    └── animations.ts       # framer-motion variants
```

### Block System

Pages from Payload contain a `layout` array of blocks. The BlockRenderer maps `blockType` to components.

**Implemented Blocks (9):**

| Block Type | Component | Key Features |
|------------|-----------|--------------|
| `hero-block` | HeroBlock | Full-screen, parallax, overlay, bounce arrow |
| `text-block` | TextBlock | Prose styling, 3 widths |
| `card-grid-block` | CardGridBlock | Material cards, hover lift, stagger |
| `quote-block` | QuoteBlock | Parallax or simple style |
| `image-text-block` | ImageTextBlock | 50/50 split, slide-in |
| `cta-block` | CTABlock | Fixed height, dark overlay |
| `contact-form-block` | ContactFormBlock | Underline inputs, card container |
| `timeline-block` | TimelineBlock | Alternating, vertical line |
| `divider-block` | DividerBlock | Line or whitespace |

**Not yet implemented:** testimonials-block, faq-block, services-block, team-block, locations-block, stats-block, image-slider-block (render as dev-only placeholders).

### API Endpoints

| Endpoint | Purpose |
|----------|---------|
| `GET /api/pages` | Pages |
| `GET /api/posts` | Blog posts |
| `GET /api/navigations` | Navigation menus |
| `GET /api/site-settings` | Site configuration |
| `GET /api/social-links` | Social media links |
| `GET /api/testimonials` | Customer testimonials |
| `GET /api/bookings` | Photography bookings |
| `POST /api/newsletter/subscribe` | Newsletter signup |
| `POST /api/form-submissions` | Contact form |

**API Documentation:** https://cms.c2sgmbh.de/api/docs

## Git Workflow

| Branch | Purpose | Deployment |
|--------|---------|------------|
| `develop` | Active development | Staging |
| `main` | Production-ready | Plesk auto-deploy |

**Commit conventions:** `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`

## Import Alias

`@/*` maps to `./src/*` (configured in tsconfig.json)