chore: migrate from Linear to Plane MCP, add .agent/ framework
- Add .agent/ directory with AGENTS.md, steering docs, workflows, references - Replace CLAUDE.md with slim reference pointing to .agent/ - Migrate TODO.md from Linear ZEE-* to Plane MITHOME-* identifiers (26 issues synced) - Add .mcp.json.example with Plane MCP server config - Remove .agents/, .cursor/, .roo/ legacy directories - Update .gitignore: add .mcp.json, remove old IDE dirs - Replace linear-sync.js approach with Plane MCP server (@makeplane/plane-mcp-server)
This commit is contained in:
Do Siki
@@ -1,177 +1,102 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
> **[AI AGENT — OLVASD EL ELŐSZÖR]**
|
||||
> Ez a fájl egy gyors referencia. A teljes szabályrendszer és workflow-ok a `.agent/` mappában találhatók.
|
||||
> **Kötelező elolvasni**: `.agent/AGENTS.md` → `.agent/steering/development-rules.md` → `.agent/steering/architecture.md`
|
||||
|
||||
## 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.
|
||||
## Projekt azonosítás
|
||||
|
||||
## Project Structure
|
||||
- **Projekt**: mozdIT Bt. weboldal (websitedev)
|
||||
- **Plane workspace**: `developments` — `pm.llmdev.mozdit.hu`
|
||||
- **Stack**: Next.js 15, React 19, TypeScript, Tailwind CSS 4, MongoDB, Winston
|
||||
- **Fő könyvtár**: `proto/` — **minden parancsot innen futtatunk**
|
||||
|
||||
---
|
||||
|
||||
## Gyors referencia — Alapszabályok
|
||||
|
||||
1. **Szöveg sosem kerülhet közvetlenül komponensbe** → `proto/src/content/pages/*.json`
|
||||
2. **Feladatok**: `TODO.md` (Linear tükörképe), szinkron: `node linear-sync.js`
|
||||
3. **Tesztek**: minden feature-höz kötelező; commit előtt `npm test` zöld
|
||||
4. **Commit**: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`)
|
||||
5. **Fájlméret**: soft limit 300 sor, hard limit 400 sor
|
||||
6. **Language**: kód+commit = English, kommunikáció+docs = Magyar
|
||||
|
||||
---
|
||||
|
||||
## Kötelező parancsok (`proto/` mappából)
|
||||
|
||||
```bash
|
||||
npm run dev # fejlesztői szerver (Turbopack)
|
||||
npm run build # produkciós build
|
||||
npm run lint # ESLint ellenőrzés
|
||||
npm test # unit tesztek
|
||||
npm run test:coverage # lefedettség riport
|
||||
npm run test:all # teljes test suite
|
||||
node plane-sync.js --list # Plane projektek listázása
|
||||
node plane-sync.js # Plane szinkronizáció
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Projekt struktúra
|
||||
|
||||
```
|
||||
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
|
||||
├── proto/ # Fő Next.js alkalmazás
|
||||
│ └── src/
|
||||
│ ├── app/ # App Router: oldalak és API route-ok
|
||||
│ ├── components/ # React komponensek (PascalCase.tsx)
|
||||
│ ├── content/ # JSON tartalom-kezelő rendszer
|
||||
│ │ ├── common.json # Közös szövegek
|
||||
│ │ └── pages/ # Oldal-specifikus JSONok
|
||||
│ ├── lib/ # MongoDB, Logger, Site Config
|
||||
│ ├── config/ # Statikus site konfiguráció
|
||||
│ └── types/ # TypeScript típusok
|
||||
├── docs/ # Projekt dokumentáció (Magyar)
|
||||
├── .agent/ # AI szabályrendszer ← OLVASD EL
|
||||
│ ├── AGENTS.md # Elsődleges szabályok
|
||||
│ ├── steering/ # Auto-betöltődő irányelvek
|
||||
│ ├── workflows/ # /new-feature, /fix-bug, /review, /deploy
|
||||
│ └── references/ # Accessibility checklist
|
||||
├── TODO.md # Feladatlista (Plane szinkron)
|
||||
└── plane-sync.js # Plane szinkronizáló 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)
|
||||
## Környezeti változók
|
||||
|
||||
## Essential Commands
|
||||
Szükséges változók (`.env` és `proto/.env.local`):
|
||||
- `MONGODB_URI` — MongoDB connection string
|
||||
- `MONGODB_DB` — Adatbázis neve (default: `mozdit`)
|
||||
- `NEXT_PUBLIC_SITE_URL` — Publikus site URL
|
||||
- `NEXT_PUBLIC_WEBMAIL_URL` — Webmail service URL
|
||||
- `NEXT_PUBLIC_CONTACT_EMAIL` — Kapcsolati email cím
|
||||
- `LINEAR_API_KEY` — Linear szinkronizációhoz
|
||||
|
||||
All development commands must be run from the `proto/` directory:
|
||||
---
|
||||
|
||||
```bash
|
||||
# Development server
|
||||
cd proto && npm run dev
|
||||
## API struktúra
|
||||
|
||||
# Production build
|
||||
cd proto && npm run build
|
||||
- `GET /api/health` — Rendszer állapot + MongoDB kapcsolat ellenőrzés
|
||||
- Minden endpoint egységes válasz formátumban: `{ success, data, error }`
|
||||
- Rate limiting érzékeny endpoint-okon (pl. `/api/contact`)
|
||||
|
||||
# Start production server
|
||||
cd proto && npm start
|
||||
---
|
||||
|
||||
# Linting
|
||||
cd proto && npm run lint
|
||||
## Teljes szabályrendszer
|
||||
|
||||
# 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
|
||||
| Dokumentum | Tartalom |
|
||||
| --- | --- |
|
||||
| `.agent/AGENTS.md` | Összes alapelv, Git konvenciók, mikor kérdezz |
|
||||
| `.agent/steering/development-rules.md` | Kódolási szabályok, bugfix módszertan, intent capture |
|
||||
| `.agent/steering/architecture.md` | Rétegek, adatfolyam, design system szabályok |
|
||||
| `.agent/steering/testing.md` | Tesztelési stratégia, coverage elvárások |
|
||||
| `.agent/workflows/new-feature.md` | Új funkció fejlesztési lépései |
|
||||
| `.agent/workflows/fix-bug.md` | Hibajavítás lépései (TDD) |
|
||||
| `.agent/workflows/review.md` | Code review checklist |
|
||||
| `.agent/workflows/deploy.md` | Deployment folyamat |
|
||||
| `.agent/references/accessibility-checklist.md` | WCAG 2.1 AA ellenőrzőlista |
|
||||
Reference in New Issue
Block a user