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)
│   │   ├── 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)
• 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 with all content
• src/types/site.ts - TypeScript interfaces for configuration
• src/lib/site-config.ts - Runtime configuration utilities

This approach enables easy content updates and future CMS integration.

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