---
description:
globs:
alwaysApply: true
---
RULE-001: Root Structure
yamlrule_id: FS-001
category: Folder Structure
applies_to: Project Root
requirements:
  - Must include the following top-level folders:
    - /src → All application code
    - /config → Configuration files
    - /scripts → Utility scripts (migrations, seeds)
    - /tests → Unit & integration tests
    - /docs → Documentation & API specs
  - Must include the following root files:
    - package.json
    - .env.example
    - README.md
    - tsconfig.json (if TypeScript)
validation:
  - No business logic in root folder
  - Config files must not include secrets

RULE-002: API Layer
yamlrule_id: FS-002
category: Folder Structure
applies_to: /src/api
requirements:
  - /src/api must contain:
    - /routes → API route definitions
    - /controllers → Request handlers
    - /middlewares → Shared middleware (auth, rate limit, logging)
    - /validators → Request validation schemas
validation:
  - Routes must only delegate to controllers
  - Controllers must not include business logic
  - Middleware must be reusable across services

RULE-003: Authentication
yamlrule_id: FS-003
category: Security
applies_to: /src/auth
requirements:
  - Must include:
    - jwt.service.js (JWT management)
    - oauth.service.js (OAuth 2.0 flows)
    - session.service.js (session handling)
  - Must store provider configs in /config/auth.js
validation:
  - Auth services must not contain route logic
  - Token utilities must be stateless

RULE-004: Business Logic Layer
yamlrule_id: FS-004
category: Application Logic
applies_to: /src/services
requirements:
  - Each domain service in its own folder:
    - /dashboard → Dashboard services
    - /integration → Integration orchestration
    - /reporting → Reporting/aggregation (future BI)
  - Business logic implemented as service classes/functions
validation:
  - Services must not directly access DB models
  - Services must call repository layer

RULE-005: Integration Layer (n8n & APIs)
yamlrule_id: FS-005
category: Integration
applies_to: /src/integrations
requirements:
  - Must include subfolders per integration:
    - /zoho
    - /quickbooks
    - /hubspot
    - /bamboohr
    - /n8n
  - Each integration must contain:
    - client.js → API client
    - mapper.js → Data mapping/transformation
    - handler.js → Webhook/event handler
validation:
  - No direct DB writes inside client files
  - Handlers must go through service layer

RULE-006: Data Persistence Layer
yamlrule_id: FS-006
category: Data Layer
applies_to: /src/data
requirements:
  - Must include:
    - /models → Sequelize/Prisma models
    - /repositories → Data access logic
    - /migrations → Database migrations
    - /seeds → Initial test/demo data
validation:
  - Repositories must be the only layer accessing models
  - No raw queries in services (must go through repository)

RULE-007: Background Jobs
yamlrule_id: FS-007
category: Jobs
applies_to: /src/jobs
requirements:
  - Must include:
    - /workers → Queue processors
    - /schedulers → Cron/scheduled tasks
    - /queues → Job definitions
validation:
  - Jobs must not block main thread
  - Workers must log execution status

RULE-008: Utilities & Shared Modules
yamlrule_id: FS-008
category: Utilities
applies_to: /src/utils
requirements:
  - Must include:
    - logger.js
    - error-handler.js
    - constants.js
    - helpers.js
  - Utilities must not depend on services
validation:
  - Utilities must be stateless
  - Logger must include correlation IDs

RULE-009: Configuration
yamlrule_id: FS-009
category: Configuration
applies_to: /config
requirements:
  - Must include:
    - database.js (MySQL config)
    - redis.js (cache config)
    - auth.js (OAuth provider config)
    - app.js (app-level configs)
  - Must support multiple environments (dev/stage/prod)
validation:
  - No hardcoded secrets
  - Configs must be environment-driven

RULE-010: Testing
yamlrule_id: FS-010
category: Testing
applies_to: /tests
requirements:
  - Must include:
    - /unit → Unit tests per service
    - /integration → API & DB integration tests
    - /mocks → Mock data
  - Must use Jest or Mocha
validation:
  - All controllers must have unit tests
  - Critical integrations must have mock-based tests

  /CentralizedReportingBackend
  /src
    /api
      /routes
      /controllers
      /middlewares
      /validators
    /auth
    /services
      /dashboard
      /integration
    /integrations
      /zoho
      /quickbooks
      /hubspot
      /bamboohr
      /n8n
    /data
      /models
      /repositories
      /migrations
      /seeds
    /jobs
      /workers
      /schedulers
      /queues
    /utils
  /config
  /scripts
  /tests
    /unit
    /integration
    /mocks
  /docs
  package.json
  README.md
  .env.example