CLAUDE.md - AI Assistant Instructions

This file provides guidance to Claude or other AI assistants when working with the SaaS CRM documentation and codebase.

🎯 Project Context

You are assisting with a SaaS CRM application that uses: - Frontend: Nuxt 4 (Vue 3, TypeScript, Tailwind CSS) - Backend: PHP Phalcon (MVC framework) - Database: MySQL 8.0 - Infrastructure: Docker, Kubernetes, AWS

📋 Documentation Standards

When Creating Documentation

1. Use Clear Headers: Structure with H2 (##) for main sections, H3 (###) for subsections
2. Include Examples: Always provide code examples for technical documentation
3. Add Tables: Use tables for comparing options, listing properties, or showing metrics
4. Include Diagrams: Use Mermaid diagrams for workflows and architecture
5. Version Everything: Include version numbers and last updated dates

Documentation Template

# [Topic Name]

## Overview
Brief description of what this document covers.

## [Main Section]

### [Subsection]
Content with examples...

## Best Practices
- Point 1
- Point 2

## Common Issues
| Issue | Solution |
|-------|----------|
| ... | ... |

---
*Last Updated: [Date] | Version: X.X.X*

💻 Code Guidelines

Frontend (Nuxt/Vue)

// Use Composition API
<script setup lang="ts">
import { ref, computed } from 'vue'

// Type everything
interface Props {
  modelValue: string
  disabled?: boolean
}

// Use proper naming
const props = defineProps<Props>()
const emit = defineEmits<{
  'update:modelValue': [value: string]
}>()

// Prefer computed over methods
const formattedValue = computed(() => {
  return props.modelValue.toUpperCase()
})
</script>

Backend (PHP Phalcon)

<?php
// Follow PSR standards
namespace App\Controllers;

use Phalcon\Mvc\Controller;

class CustomerController extends Controller
{
    /**
     * Always document methods
     * @param int $id
     * @return Response
     */
    public function showAction($id)
    {
        // Validate input
        if (!is_numeric($id)) {
            return $this->errorResponse('Invalid ID', 400);
        }

        // Use service layer
        $customer = $this->customerService->find($id);

        // Return structured response
        return $this->successResponse($customer);
    }
}

Database (MySQL)

-- Use clear naming conventions
CREATE TABLE customers (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    -- Always add indexes for foreign keys
    INDEX idx_customers_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- Include rollback scripts
-- Rollback: DROP TABLE IF EXISTS customers;

🔄 Development Process

When assisting with development tasks, follow this process:

1. Requirements First: Always clarify requirements before implementing
2. Check Competitors: Research if similar features exist in other CRMs
3. Impact Analysis: Consider performance, security, and UX impacts
4. Design Before Code: Create UI mockups and database schemas first
5. Test Everything: Write tests before or alongside implementation
6. Document Changes: Update relevant documentation

🚨 Important Rules

NEVER Do These:

1. Work on main branch - Always use draft or feature branches
2. Skip tests - Every feature needs tests
3. Ignore errors - Handle all error cases properly
4. Hardcode values - Use environment variables
5. Commit secrets - Never include API keys, passwords, etc.
6. Create without checking - Always check if similar code exists first

ALWAYS Do These:

1. Follow existing patterns - Check how similar features are implemented
2. Validate input - Never trust user input
3. Use type hints - In TypeScript and PHP
4. Add error handling - Every function should handle errors
5. Write meaningful commits - Use conventional commit format
6. Update documentation - Keep docs in sync with code

📊 Key Metrics to Consider

When implementing features, optimize for:

Metric	Target	Priority
Page Load Time	<2s	High
API Response Time	<200ms	High
Code Coverage	>80%	High
Bundle Size	<500KB	Medium
Database Queries	<10 per page	Medium

🗂️ File Organization

Where to Put Things:

Frontend:
- Components: /components/[feature]/[Component].vue
- Composables: /composables/use[Feature].ts
- API calls: /composables/useApi.ts
- Types: /types/[feature].d.ts

Backend:
- Controllers: /app/controllers/[Feature]Controller.php
- Services: /app/services/[Feature]Service.php
- Models: /app/models/[Model].php
- Migrations: /migrations/YYYY_MM_DD_description.sql

Documentation:
- Development: /docs-pramoth/development/
- Architecture: /docs-pramoth/architecture/
- Operations: /docs-pramoth/operations/

🔍 Research Resources

When researching features or solutions:

1. Competitor CRMs: Salesforce, HubSpot, Pipedrive, Zoho
2. Documentation: Vue.js docs, Phalcon docs, MySQL docs
3. Best Practices: OWASP for security, Google Web Vitals for performance
4. Design Systems: Material Design, Ant Design for UI patterns

📝 Communication Templates

Bug Report

**Issue**: [Brief description]
**Environment**: Production/Staging/Dev
**Steps to Reproduce**: 
1. ...
**Expected**: [What should happen]
**Actual**: [What happens]
**Impact**: [Users affected]

Feature Request

**Feature**: [Name]
**Problem**: [What problem does it solve]
**Solution**: [Proposed solution]
**Impact**: [Business value]
**Effort**: [Estimation]

🆘 When Stuck

If you're unsure about something:

1. Check existing code - Look for similar implementations
2. Review documentation - Check both internal and external docs
3. Consider impact - Think about performance, security, UX
4. Ask for clarification - Better to ask than assume
5. Suggest alternatives - Provide multiple solutions when possible

🎨 UI/UX Guidelines

• Consistency: Follow existing UI patterns
• Accessibility: Ensure WCAG 2.1 AA compliance
• Mobile-first: Design for mobile, enhance for desktop
• Loading states: Always show loading indicators
• Error messages: Make them clear and actionable
• Empty states: Design for when there's no data

🔐 Security Considerations

Always consider: - Input validation: Server-side validation is mandatory - SQL injection: Use parameterized queries - XSS prevention: Sanitize all output - CSRF protection: Use tokens for state-changing operations - Authentication: Use JWT with proper expiration - Authorization: Check permissions for every action

📚 Learning Resources

To better understand the codebase: 1. Start with /docs-pramoth/README.md 2. Review /docs-pramoth/development/workflow.md 3. Check architecture docs in /docs-pramoth/architecture/ 4. Look at existing code examples in the repository

---

This document helps AI assistants provide consistent, high-quality assistance for the SaaS CRM project.

Last Updated: January 2025 | Version: 1.0.0