CLAUDE.md

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

Project Overview

This is a modern personal website built with Next.js 14 App Router, featuring:

Dark-only themed design with custom CSS variables and Tailwind
Internationalization with Turkish (default) and English using next-intl
Interactive side-scrolling experience with scenes and timeline-based animations
Privacy-friendly social media embeds that load content on interaction
Admin panel for content management at
```
/admin
```
MDX content system for rich text content

Development Commands

Essential Scripts

```
npm run dev
```
- Start development server (uses port 3000, falls back to 3001)
```
npm run build
```
- Build for production
```
npm run start
```
- Start production server
```
npm run lint
```
- Run ESLint checks
```
npm run typecheck
```
- Run TypeScript type checking
```
npm run format
```
- Format code with Prettier
```
npm run health
```
- Run comprehensive health checks via dev-manager script

Development Manager

The project includes a comprehensive development manager script at

./scripts/dev-manager.sh

```
npm run health
```
- Runs health checks for Node, dependencies, env vars, TypeScript, ESLint, and build
Sets up
```
.env.local
```
with default admin credentials if missing
Provides continuous monitoring and auto-recovery

Testing & Quality

Always run these commands before committing:

```
npm run typecheck
```
- Must pass without errors
```
npm run lint
```
- Must pass without errors
```
npm run build
```
- Must build successfully

Architecture

App Router Structure

app/
�� layout.tsx          # Root layout with i18n setup
�� page.tsx           # Home page with side-scrolling experience
�� providers.tsx      # Client providers (NextIntlClientProvider)
�� api/               # API routes
   �� health/        # Health check endpoint
   �� metrics/       # Telemetry metrics
   �� og/           # Dynamic OG image generation
   �� admin/        # Admin panel APIs
�� admin/            # Admin panel for content management
�� interactive/      # Interactive side-scrolling page
�� resume/          # Print-optimized resume page
�� now/             # Current focus/status page
�� _scenes/         # Side-scrolling scene components
�� _state/          # Zustand store for side-scroller state
�� _fx/             # Animation and effect utilities
�� _ui/             # Core UI components (HUD, Stage)

State Management

Zustand store (
```
app/_state/store.ts
```
) manages side-scrolling timeline state
Scene system with predefined sections (intro, skills, experience, awards, work, contact)
Timeline-based animations using
```
t
```
(0-1) progress value
Viewport-responsive with automatic resize handling

Component Architecture

UI Components: Located in
```
components/ui/
```
(shadcn/ui based)
Blocks System: Reusable content blocks in
```
components/blocks/
```
Scene Components: Interactive scenes in
```
app/_scenes/
```
Admin Components: Content management in
```
components/admin/
```

Data Management

JSON-based content system in

data/

```
projects.json
```
- Project portfolio data
```
experience.json
```
- Work experience timeline
```
social.json
```
- Social media links
```
embeds.json
```
- Social media embed configurations
```
pages.json
```
- Dynamic page content
```
page_versions.json
```
- Content versioning

Styling System

Tailwind CSS with custom configuration
CSS variables for theme colors in
```
styles/theme.css
```
Dark-only design with custom color palette
Grid-based spacing using CSS custom properties
shadcn/ui components with custom theme integration

Internationalization

next-intl for translations without URL prefixes
Cookie-based locale detection (no route prefixes)
Message files:
```
messages/tr.json
```
and
```
messages/en.json
```
MDX content: Locale-specific content in
```
content/[locale]/
```
Default locale: Turkish (
```
tr
```
)

Admin Panel

Protected route at
```
/admin
```
with HTTP Basic Auth
Environment variables:
```
ADMIN_USERNAME
```
and
```
ADMIN_PASSWORD
```
required
Content management: Edit projects, experience, social links, embeds
File-based storage when
```
CONTENT_STORAGE=FILE
```
(development only)
Production security: Storage operations return 501 by default

Configuration Files

Core Config

```
site.config.ts
```
- Site metadata, social links, contact info
```
next.config.mjs
```
- Next.js configuration with MDX, CSP headers, image domains
```
tailwind.config.ts
```
- Tailwind with custom theme, CSS variables, animations
```
tsconfig.json
```
- TypeScript configuration with path aliases (
```
@/
```
)

Dependencies

Key dependencies to understand:

```
@next/mdx
```
- MDX support for content
```
next-intl
```
- Internationalization
```
zustand
```
- State management
```
framer-motion
```
- Animations
```
@radix-ui/*
```
- UI primitives for components
```
@hello-pangea/dnd
```
- Drag and drop (admin panel)
```
zod
```
- Schema validation
```
@vercel/og
```
- Dynamic OG image generation

Development Guidelines

File Organization

Use absolute imports with
```
@/
```
prefix for all internal imports
Keep scene components in
```
app/_scenes/
```
Place reusable UI in
```
components/ui/
```
Store utilities in
```
lib/
```
Put type definitions close to usage or in component files

Component Patterns

Client components must use
```
'use client'
```
directive
Server components are default, use for data fetching and layout
Zustand selectors for accessing store state efficiently
CSS-in-JS through Tailwind classes, avoid inline styles
Responsive design using Tailwind breakpoints

Content Management

JSON files in
```
data/
```
directory for structured content
MDX files in
```
content/[locale]/
```
for rich text content
Asset optimization for images in
```
public/
```
Admin panel for non-technical content editing

Environment Variables

Required for development:

ADMIN_USERNAME=your_username
ADMIN_PASSWORD=your_password  
CONTENT_STORAGE=FILE

Optional:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
PLAUSIBLE_DOMAIN=your-domain.com

Security Considerations

CSP headers configured in next.config.mjs
Input validation using Zod schemas in API routes
Admin authentication using HTTP Basic Auth
Production restrictions on file system operations
No sensitive data in client-side code or Git

Side-Scrolling System

Timeline Architecture

The interactive experience uses a timeline-based system:

Global progress (
```
t
```
) from 0 to 1 representing full timeline
Scene boundaries defined in
```
SCENES
```
constant with start/end points
Smooth transitions between scenes using custom easing functions
Section progress tracking for individual scene animations

Scene Development

When adding new scenes:

Create scene component in
```
app/_scenes/
```
Export from
```
app/_scenes/index.ts
```
Update
```
SCENES
```
configuration in store
Add scene to timeline in main page
Implement scene-specific animations using progress values

Animation System

Framer Motion for component animations
Custom easing functions in
```
app/_fx/easing.ts
```
Viewport-responsive animations that adapt to screen size
Reduced motion support with automatic detection
Performance optimized with scene activation/deactivation

Viewport Handling

Responsive timeline that adapts to different screen sizes
Touch/mouse/keyboard input handling
Pixel-perfect positioning with device pixel ratio support
Smooth scrolling with momentum and inertia

This architecture supports building rich, interactive experiences while maintaining performance and accessibility standards.

CLAUDE.md

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

Project Overview

This is a modern personal website built with Next.js 14 App Router, featuring:

Dark-only themed design with custom CSS variables and Tailwind
Internationalization with Turkish (default) and English using next-intl
Interactive side-scrolling experience with scenes and timeline-based animations
Privacy-friendly social media embeds that load content on interaction
Admin panel for content management at
```
/admin
```
MDX content system for rich text content

Development Commands

Essential Scripts

```
npm run dev
```
- Start development server (uses port 3000, falls back to 3001)
```
npm run build
```
- Build for production
```
npm run start
```
- Start production server
```
npm run lint
```
- Run ESLint checks
```
npm run typecheck
```
- Run TypeScript type checking
```
npm run format
```
- Format code with Prettier
```
npm run health
```
- Run comprehensive health checks via dev-manager script

Development Manager

The project includes a comprehensive development manager script at

./scripts/dev-manager.sh

```
npm run health
```
- Runs health checks for Node, dependencies, env vars, TypeScript, ESLint, and build
Sets up
```
.env.local
```
with default admin credentials if missing
Provides continuous monitoring and auto-recovery

Testing & Quality

Always run these commands before committing:

```
npm run typecheck
```
- Must pass without errors
```
npm run lint
```
- Must pass without errors
```
npm run build
```
- Must build successfully

Architecture

App Router Structure

app/
�� layout.tsx          # Root layout with i18n setup
�� page.tsx           # Home page with side-scrolling experience
�� providers.tsx      # Client providers (NextIntlClientProvider)
�� api/               # API routes
   �� health/        # Health check endpoint
   �� metrics/       # Telemetry metrics
   �� og/           # Dynamic OG image generation
   �� admin/        # Admin panel APIs
�� admin/            # Admin panel for content management
�� interactive/      # Interactive side-scrolling page
�� resume/          # Print-optimized resume page
�� now/             # Current focus/status page
�� _scenes/         # Side-scrolling scene components
�� _state/          # Zustand store for side-scroller state
�� _fx/             # Animation and effect utilities
�� _ui/             # Core UI components (HUD, Stage)

State Management

Zustand store (
```
app/_state/store.ts
```
) manages side-scrolling timeline state
Scene system with predefined sections (intro, skills, experience, awards, work, contact)
Timeline-based animations using
```
t
```
(0-1) progress value
Viewport-responsive with automatic resize handling

Component Architecture

UI Components: Located in
```
components/ui/
```
(shadcn/ui based)
Blocks System: Reusable content blocks in
```
components/blocks/
```
Scene Components: Interactive scenes in
```
app/_scenes/
```
Admin Components: Content management in
```
components/admin/
```

Data Management

JSON-based content system in

data/

```
projects.json
```
- Project portfolio data
```
experience.json
```
- Work experience timeline
```
social.json
```
- Social media links
```
embeds.json
```
- Social media embed configurations
```
pages.json
```
- Dynamic page content
```
page_versions.json
```
- Content versioning

Styling System

Tailwind CSS with custom configuration
CSS variables for theme colors in
```
styles/theme.css
```
Dark-only design with custom color palette
Grid-based spacing using CSS custom properties
shadcn/ui components with custom theme integration

Internationalization

next-intl for translations without URL prefixes
Cookie-based locale detection (no route prefixes)
Message files:
```
messages/tr.json
```
and
```
messages/en.json
```
MDX content: Locale-specific content in
```
content/[locale]/
```
Default locale: Turkish (
```
tr
```
)

Admin Panel

Protected route at
```
/admin
```
with HTTP Basic Auth
Environment variables:
```
ADMIN_USERNAME
```
and
```
ADMIN_PASSWORD
```
required
Content management: Edit projects, experience, social links, embeds
File-based storage when
```
CONTENT_STORAGE=FILE
```
(development only)
Production security: Storage operations return 501 by default

Configuration Files

Core Config

```
site.config.ts
```
- Site metadata, social links, contact info
```
next.config.mjs
```
- Next.js configuration with MDX, CSP headers, image domains
```
tailwind.config.ts
```
- Tailwind with custom theme, CSS variables, animations
```
tsconfig.json
```
- TypeScript configuration with path aliases (
```
@/
```
)

Dependencies

Key dependencies to understand:

```
@next/mdx
```
- MDX support for content
```
next-intl
```
- Internationalization
```
zustand
```
- State management
```
framer-motion
```
- Animations
```
@radix-ui/*
```
- UI primitives for components
```
@hello-pangea/dnd
```
- Drag and drop (admin panel)
```
zod
```
- Schema validation
```
@vercel/og
```
- Dynamic OG image generation

Development Guidelines

File Organization

Use absolute imports with
```
@/
```
prefix for all internal imports
Keep scene components in
```
app/_scenes/
```
Place reusable UI in
```
components/ui/
```
Store utilities in
```
lib/
```
Put type definitions close to usage or in component files

Component Patterns

Client components must use
```
'use client'
```
directive
Server components are default, use for data fetching and layout
Zustand selectors for accessing store state efficiently
CSS-in-JS through Tailwind classes, avoid inline styles
Responsive design using Tailwind breakpoints

Content Management

JSON files in
```
data/
```
directory for structured content
MDX files in
```
content/[locale]/
```
for rich text content
Asset optimization for images in
```
public/
```
Admin panel for non-technical content editing

Environment Variables

Required for development:

ADMIN_USERNAME=your_username
ADMIN_PASSWORD=your_password  
CONTENT_STORAGE=FILE

Optional:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
PLAUSIBLE_DOMAIN=your-domain.com

Security Considerations

CSP headers configured in next.config.mjs
Input validation using Zod schemas in API routes
Admin authentication using HTTP Basic Auth
Production restrictions on file system operations
No sensitive data in client-side code or Git

Side-Scrolling System

Timeline Architecture

The interactive experience uses a timeline-based system:

Global progress (
```
t
```
) from 0 to 1 representing full timeline
Scene boundaries defined in
```
SCENES
```
constant with start/end points
Smooth transitions between scenes using custom easing functions
Section progress tracking for individual scene animations

Scene Development

When adding new scenes:

Create scene component in
```
app/_scenes/
```
Export from
```
app/_scenes/index.ts
```
Update
```
SCENES
```
configuration in store
Add scene to timeline in main page
Implement scene-specific animations using progress values

Animation System

Framer Motion for component animations
Custom easing functions in
```
app/_fx/easing.ts
```
Viewport-responsive animations that adapt to screen size
Reduced motion support with automatic detection
Performance optimized with scene activation/deactivation

Viewport Handling

Responsive timeline that adapts to different screen sizes
Touch/mouse/keyboard input handling
Pixel-perfect positioning with device pixel ratio support
Smooth scrolling with momentum and inertia

This architecture supports building rich, interactive experiences while maintaining performance and accessibility standards.

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password