138 lines
4.8 KiB
Markdown
138 lines
4.8 KiB
Markdown
# 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:
|
|
|
|
```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 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:
|
|
```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 |