igny8/.cursorrules

# IGNY8 Development Rules
# ========================
# These rules MUST be followed for all code changes.
# Version: 1.8.4 | Last Updated: January 20, 2026

## 📋 MANDATORY CHECKLIST (Every Change)

Before submitting ANY code change:

1. [ ] Documentation updated (if behavior changed)
2. [ ] CHANGELOG.md updated (if user-facing)
3. [ ] Design guide followed (frontend changes)
4. [ ] Types/interfaces match API responses
5. [ ] No hardcoded values (use constants/settings)

---

## 🗂️ Project Structure

```
/
├── INDEX.md                    # Start here
├── DESIGN-GUIDE.md             # UI/UX standards (MANDATORY)
├── CHANGELOG.md                # All notable changes
├── README.md                   # Setup & overview
├── docs/                       # Detailed documentation
│   ├── 00-SYSTEM/              # Architecture & core concepts
│   ├── 10-MODULES/             # Business logic modules
│   ├── 20-API/                 # API endpoints
│   ├── 30-FRONTEND/            # React components & stores
│   ├── 40-WORKFLOWS/           # Business processes
│   ├── 50-DEPLOYMENT/          # DevOps & infrastructure
│   ├── 60-PLUGINS/             # Plugin system
│   └── 90-REFERENCE/           # Models, enums, glossary
├── backend/                    # Django app
└── frontend/                   # React app
```

---

## 📝 Documentation Rules

### When to Update Docs

| Change Type | Update Required |
|-------------|-----------------|
| New API endpoint | `docs/20-API/ENDPOINTS.md` |
| New model | `docs/90-REFERENCE/MODELS.md` |
| New route/page | `docs/30-FRONTEND/PAGES.md` |
| New store | `docs/30-FRONTEND/STORES.md` |
| UI component | `docs/30-FRONTEND/COMPONENT-SYSTEM.md` |
| Settings change | `docs/00-SYSTEM/ARCHITECTURE.md` |
| New module | `docs/10-MODULES/<module>.md` |
| New Celery task | Document in module's backend docs |

### Documentation Standards

```markdown
# Document Title

> Brief one-line description

**Version:** X.Y.Z
**Last Updated:** YYYY-MM-DD

## Section 1
Content...

## Section 2
Content...
```

---

## 🎨 Frontend Rules

### MUST Follow Design Guide

All frontend code MUST adhere to `DESIGN-GUIDE.md`:

1. **Components**: Use our component library, NEVER raw HTML
2. **Colors**: Only semantic colors (brand, success, warning, error, purple, gray)
3. **Icons**: Import from central `icons/` directory only
4. **Forms**: Use standardized form components

### File Organization

```
src/
├── components/
│   ├── ui/           # Reusable UI components
│   ├── form/         # Form-specific components
│   ├── layout/       # Layout components
│   └── [module]/     # Module-specific components
├── pages/            # Route pages
├── stores/           # Zustand stores
├── services/         # API service functions
├── hooks/            # Custom React hooks
├── types/            # TypeScript type definitions
└── utils/            # Utility functions
```

### TypeScript Standards

```typescript
// ✅ CORRECT: Use interfaces for API responses
interface Site {
  id: string;
  name: string;
  domain: string;
}

// ✅ CORRECT: Type all props
interface ComponentProps {
  title: string;
  onClose: () => void;
  children?: React.ReactNode;
}

// ❌ WRONG: No any types
const data: any = response;
```

---

## 🐍 Backend Rules

### Django/DRF Standards

1. **Serializers**: Must match model fields exactly
2. **Views**: Use DRF ViewSets where possible
3. **URLs**: Follow RESTful conventions
4. **Models**: Document all fields with help_text

### Serializer Field Validation

```python
# ✅ CORRECT: Fields match model
class SettingsSerializer(serializers.ModelSerializer):
    class Meta:
        model = Settings
        fields = ['id', 'key', 'value']  # 'value' exists on model

# ❌ WRONG: Field doesn't exist on model
class SettingsSerializer(serializers.ModelSerializer):
    config = serializers.JSONField()  # 'config' doesn't exist!
    class Meta:
        model = Settings
        fields = ['id', 'key', 'config']
```

### API Response Format

```python
# Standard success response
{
    "data": { ... },
    "message": "Operation successful"
}

# Standard error response
{
    "error": "Error message",
    "details": { ... }
}

# Paginated response
{
    "count": 100,
    "next": "http://...",
    "previous": null,
    "results": [ ... ]
}
```

---

## 📊 CHANGELOG Rules

### When to Update

- New features (user-visible)
- Bug fixes (user-affecting)
- API changes
- Breaking changes
- Performance improvements

### Format

```markdown
## [1.8.4] - 2026-01-21

### Added
- New feature description

### Changed
- Changed behavior description

### Fixed
- Bug fix description

### Deprecated
- Deprecated feature warning

### Removed
- Removed feature notice

### Security
- Security fix description
```

---

## ✅ Code Review Checklist

### Before Creating PR

- [ ] Code compiles/runs without errors
- [ ] All tests pass
- [ ] No console.log or print statements (unless intentional)
- [ ] Documentation updated
- [ ] CHANGELOG updated (if applicable)
- [ ] No hardcoded secrets/URLs
- [ ] Follows design guide (frontend)
- [ ] Serializers match models (backend)

### Review Focus Areas

1. **Logic**: Does the code do what it's supposed to?
2. **Types**: Are TypeScript types correct and complete?
3. **Security**: Any security concerns?
4. **Performance**: Any obvious performance issues?
5. **Consistency**: Follows existing patterns?

---

## 🔧 Development Workflow

### Making Changes

1. Understand the context (read relevant docs first)
2. Make the change
3. Update documentation
4. Update CHANGELOG (if user-facing)
5. Test thoroughly
6. Submit for review

### Adding New Features

1. Document the feature design first
2. Implement backend (if needed)
3. Update API docs
4. Implement frontend
5. Update frontend docs
6. Add to CHANGELOG

---

## 🚨 Common Mistakes to Avoid

### Frontend

- Using raw HTML instead of components
- Using default Tailwind colors
- Importing icons from wrong source
- Not typing API responses
- Hardcoding API URLs

### Backend

- Serializer fields not matching models
- Missing model validations
- Not handling edge cases in views
- Forgetting to add URLs to router

### Documentation

- Not updating docs after changes
- Outdated version numbers
- Missing new endpoints/pages
- Inconsistent formatting

---

## 📚 Key Documentation Files

| Purpose | Location |
|---------|----------|
| Quick start | `/INDEX.md` |
| UI standards | `/DESIGN-GUIDE.md` |
| Change history | `/CHANGELOG.md` |
| Architecture | `/docs/00-SYSTEM/ARCHITECTURE.md` |
| API reference | `/docs/20-API/ENDPOINTS.md` |
| Data models | `/docs/90-REFERENCE/MODELS.md` |
| Frontend routes | `/docs/30-FRONTEND/PAGES.md` |
| State stores | `/docs/30-FRONTEND/STORES.md` |
| Components | `/docs/30-FRONTEND/COMPONENT-SYSTEM.md` |

---

## 🔄 Maintenance Scripts

### Verify Documentation Accuracy

```bash
./scripts/verify-docs.sh
```

### Update API Schema

```bash
cd backend && python manage.py spectacular --file schema.yml
```

### Check for Unused Code

```bash
cd frontend && npm run lint
```

---

## Version Info

- **App Version:** 1.8.3
- **Backend:** Django 5.1, DRF 3.15
- **Frontend:** React 19, TypeScript 5
- **Database:** PostgreSQL 16
- **Cache:** Redis 7