feat: update Linear issue tracking with project query and workflow state handling

2025-09-05 03:44:04 +02:00
parent b6365543ef
commit 578a85ec1a
8 changed files with 501 additions and 247 deletions
@@ -0,0 +1,138 @@
+# 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