140 lines
4.5 KiB
Plaintext
140 lines
4.5 KiB
Plaintext
---
|
|
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 |