websitedev/CLAUDE.md

# CLAUDE.md

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

## Project Overview

This is the mozdIT Bt. website development project - a Next.js 14 application for a Hungarian IT services company. The codebase includes both frontend and backend functionality for hosting, email services, and DNS administration services.

## Project Structure

```
websitedev/
├── proto/                  # Main Next.js application
│   ├── src/
│   │   ├── app/           # Next.js App Router (pages and API routes)
│   │   ├── components/    # React components (Header, Footer, ThemeProvider)
│   │   ├── content/       # JSON content management system
│   │   │   ├── types.ts   # Content TypeScript definitions
│   │   │   ├── index.ts   # Content loader utility
│   │   │   ├── common.json # Shared texts (buttons, labels)
│   │   │   └── pages/     # Page-specific content JSONs
│   │   ├── lib/          # Utility libraries (MongoDB, Logger, Site Config)
│   │   ├── config/       # Static site configuration
│   │   └── types/        # TypeScript type definitions
│   ├── public/           # Static assets
│   └── package.json
├── docs/                 # Project documentation (Hungarian)
├── TODO.md              # Project task tracking (Hungarian)
└── linear-sync.js       # Linear API synchronization script
```

## Key Architecture

- **Framework**: Next.js 14 with App Router and TypeScript
- **UI**: Tailwind CSS 4 with custom fonts (Geist Sans/Mono)
- **Design System**: CSS Variables, Dark Mode (ThemeProvider), Animations
- **Content Management**: JSON-based structured content in `src/content/`
- **Database**: MongoDB with Mongoose ODM
- **Logging**: Winston with Loki integration
- **Testing**: Jest with React Testing Library
- **Deployment**: Dokploy (staging and production)
- **Project Management**: Linear (primary), TODO.md (local sync)

## Essential Commands

All development commands must be run from the `proto/` directory:

```bash
# Development server
cd proto && npm run dev

# Production build
cd proto && npm run build

# Start production server
cd proto && npm start

# Linting
cd proto && npm run lint

# Testing
cd proto && npm test
cd proto && npm test:watch
cd proto && npm test:coverage
```

## Configuration Files

- `proto/package.json` - Dependencies and scripts
- `proto/tsconfig.json` - TypeScript configuration with path mapping (`@/*` → `./src/*`)
- `proto/eslint.config.mjs` - ESLint configuration extending Next.js rules
- `proto/next.config.ts` - Next.js configuration (currently minimal)
- `proto/jest.config.js` - Jest testing configuration
- `.env` - Environment variables (root level)
- `proto/.env.local` - Local environment overrides

## Environment Variables

Required environment variables (check `.env` and `proto/.env.local`):
- `MONGODB_URI` - MongoDB connection string
- `MONGODB_DB` - Database name (defaults to 'mozdit')
- `NEXT_PUBLIC_SITE_URL` - Public site URL
- `NEXT_PUBLIC_WEBMAIL_URL` - Webmail service URL
- `NEXT_PUBLIC_CONTACT_EMAIL` - Contact email address
- `LINEAR_API_KEY` - For Linear synchronization

## Site Configuration

The site uses a centralized configuration system:
- `src/config/site.ts` - Main site configuration (company info, navigation, services)
- `src/types/site.ts` - TypeScript interfaces for configuration
- `src/lib/site-config.ts` - Runtime configuration utilities

## Content Management System

All page text content is managed through JSON files for easy modification:

```
src/content/
├── types.ts          # TypeScript definitions for content
├── index.ts          # Content loader with getPageContent() helper
├── common.json       # Shared texts (buttons, labels, validation)
└── pages/
    ├── home.json     # Homepage CTA, feature labels
    ├── about.json    # About page (hero, story, mission, team)
    ├── services.json # Services details, support info
    └── contact.json  # Form labels, FAQ, contact info
```

**Usage in components:**
```typescript
import { content, getPageContent } from '@/content'

const { about: pageContent } = content.pages
// or
const servicesContent = getPageContent('services')
```

## Design System

The project includes a comprehensive design system:

- **CSS Variables**: Defined in `globals.css` for colors, shadows, transitions
- **Dark Mode**: ThemeProvider component with system preference + manual toggle
- **Animations**: fadeIn, float, pulse, hover effects (lift, scale, glow)
- **Utility Classes**: `.card`, `.btn`, `.icon-container`, etc.

## Database Integration

MongoDB integration is handled through:
- `src/lib/mongodb.ts` - Connection management with pooling
- Connection health checks available via `/api/health`
- Development mode uses global connection caching
- Production mode creates fresh connections

## Testing Strategy

- Unit tests for all components and utilities
- API endpoint tests for health checks
- Test files follow `.test.ts`/`.test.tsx` naming convention
- Jest configuration includes jsdom environment for React components
- Testing utilities include @testing-library/react and @testing-library/jest-dom

## Project Management Integration

The project uses a dual-tracking system:
- **Primary**: Linear tickets (ZEE-* series)
- **Secondary**: TODO.md for local development tracking

Use `linear-sync.js` to synchronize between the two systems:
```bash
node linear-sync.js --dry-run --verbose  # Test mode
node linear-sync.js                      # Live sync
```

## Language and Content

- **Primary language**: Hungarian (site content, documentation)
- **Code**: English (variable names, comments, technical terms)
- **Target audience**: Hungarian businesses
- Site content focuses on web hosting, email services, and DNS administration

## Development Workflow

1. Check Linear for current sprint tasks
2. Update TODO.md for local tracking
3. Run tests before making changes (`npm test`)
4. Use development server with Turbopack for fast iteration
5. Run linting before committing (`npm run lint`)
6. Sync with Linear using the sync script
7. Deploy via Dokploy when ready

## API Structure

- `/api/health` - System health check endpoint with MongoDB status
- Future API endpoints will follow REST conventions
- API routes include comprehensive error handling and logging