---
description:
globs:
alwaysApply: true
---
RULE-001: API Design Standards
yamlrule_id: API-001
category: API Design
applies_to: All API endpoints
requirements:
  - RESTful design principles
  - Consistent response format (status, message, data, timestamp)
  - Proper HTTP status codes
  - API versioning (v1, v2)
  - OpenAPI/Swagger documentation
validation:
  - Success responses must follow {status, message, data, timestamp}
  - Error responses must include error code and details
  - Version must be in the endpoint path (/api/v1/...)

RULE-002: Authentication & Security
yamlrule_id: AUTH-002
category: Security
applies_to: All protected endpoints
requirements:
  - JWT validation middleware
  - OAuth 2.0 for external service integrations
  - Token refresh mechanism
  - Encrypted storage of OAuth tokens in MySQL
  - Rate limiting by user/IP
validation:
  - All routes must check for valid JWT
  - OAuth tokens refreshed before expiry
  - Failed login attempts logged with user/IP

RULE-003: n8n Integration Standards
yamlrule_id: N8N-003
category: Integration
applies_to: All external system connections via n8n
requirements:
  - Standardized n8n workflows for Zoho, QuickBooks, HubSpot, BambooHR
  - Webhook verification for data pushed into backend
  - Error handling and retry logic in workflows
  - Async processing for heavy sync tasks
  - Logging of workflow execution status
validation:
  - All workflows must use verified webhooks
  - Workflow failures must trigger error events
  - Retry mechanism configured for transient API failures

RULE-004: Database Operations
yamlrule_id: DB-004
category: Database
applies_to: All MySQL interactions
requirements:
  - Use Sequelize ORM (or Prisma) for MySQL operations
  - Strong relational schema with constraints
  - Data validation at model level
  - Indexing for frequently queried fields
  - Soft delete for critical data
  - Audit trail for token and integration logs
validation:
  - All models must define schema + validations
  - Foreign keys must enforce data integrity
  - Sensitive data encrypted at rest
  - Audit tables must log all changes in integrations

RULE-005: Background Jobs & Scheduling
yamlrule_id: JOB-005
category: Background Processing
applies_to: All scheduled tasks
requirements:
  - Job queue implementation (Bull/Agenda/Redis Queue)
  - Scheduled sync jobs with external services
  - Dead letter queue for failed jobs
  - Error handling and retry policies
  - Monitoring + alerting for failed jobs
validation:
  - Jobs must define timeout & retries
  - Failed jobs logged with execution context
  - DLQ retention period configured

RULE-006: Caching Strategy
yamlrule_id: CACHE-006
category: Performance
applies_to: All cache operations
requirements:
  - Redis for session storage and caching API responses
  - TTL-based cache expiration
  - Cache invalidation strategies for sync jobs
  - Cache key naming: {service}:{operation}:{identifier}
validation:
  - Cache entries must always include TTL
  - Sync workflows must invalidate outdated cache
  - Cache hit/miss ratio tracked in monitoring

RULE-007: Error Handling & Logging
yamlrule_id: ERROR-007
category: Reliability
applies_to: All backend services
requirements:
  - Centralized error middleware
  - Structured logging with correlation IDs
  - Error classification: system, integration, validation
  - Log levels: ERROR, WARN, INFO, DEBUG
  - Log rotation & retention policies
validation:
  - Logs must never include sensitive tokens
  - All errors logged with workflow ID (if integration-related)
  - Error responses must mask internal details

RULE-008: Workflow Integration (n8n Specific)
yamlrule_id: WORKFLOW-008
category: Integration
applies_to: All workflows triggered via n8n
requirements:
  - Secure webhook verification
  - Async workflow execution for long tasks
  - Workflow status tracking in MySQL
  - Monitoring for success/failure metrics
  - Recovery mechanisms for failed sync
validation:
  - Workflows must store run status in DB
  - Webhook events verified via signatures
  - Failures trigger retry + alert notification

RULE-009: Environment Configuration
yamlrule_id: CONFIG-009
category: Configuration
applies_to: All environments
requirements:
  - Environment-specific configs (dev/stage/prod)
  - Secrets in Vault/ENV, not in source code
  - Feature flagging for experimental services
  - Health check endpoints
  - Graceful shutdown on service stop
validation:
  - Secrets must be injected at runtime
  - Health checks must validate DB, Redis, and n8n connectivity
  - Feature flags documented per environment