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:

# 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:

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:

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