This document outlines the backend development guidelines specific to Chatwoot. All contributors are expected to follow these guidelines to ensure consistency, readability, and maintainability of the codebase.

> **Note**: We follow the general Ruby on Rails development guidelines as mentioned in the official guide: [Ruby on Rails Contributing Guide](https://guides.rubyonrails.org/contributing_to_ruby_on_rails.html#follow-the-coding-conventions).

## **Project Structure**

* Follow Rails' default conventions and directory structure.

* Organize code using service objects, concerns, and modules to keep controllers and models lean.

## **Design Principles**

### **1. Single Responsibility Principle (SRP)**

Each class or module should focus on a single responsibility.

**✅ Good:**

```
class AccountBuilder
  def initialize(user); @user = user; end

  def perform
    create_account
    setup_inbox
  end

  private

  def create_account
    # account creation logic
  end

  def setup_inbox
    # inbox setup logic
  end
end
```

**❌ Bad:**

```
class SetupEverything
  def execute
    create_account
    setup_inbox
    create_contact
    seed_conversations
  end
end
```

### **2. Minimal Namespace Pollution**

Group helper classes and utilities under a shared namespace to avoid cluttering top-level modules.

**✅ Good:**

```
module TestData
  class AccountCreator
    def self.create; end
  end
end
```

**❌ Bad:**

```
class AccountCreator
  def self.create; end
end
```

### **3. Extract Long Methods**

Split large methods into smaller private methods to improve readability and testability.

**✅ Good:**

```
def process_account_data
  validate_data
  transform_data
  persist_data
end
```

**❌ Bad:**

```
def process_account_data
  # 100+ lines of logic in one place
end
```

### **4. Avoid Side Effects in lib/tasks**

Rake tasks should only serve as an orchestrator. Move core logic to services or jobs.

**✅ Good:**

```
# lib/tasks/seed.rake
namespace :db do
  task seed: :environment do
    Seed::AccountSeeder.new.run
  end
end
```

**❌ Bad:**

```
# lib/tasks/seed.rake
namespace :db do
  task seed: :environment do
    Account.create!(...) # all logic directly in rake task
  end
end
```

### **5. Clear Naming**

Name variables and methods in a way that clearly communicates their purpose.

**✅ Good:**

```
def generate_contact_for_account(account_id); end
```

**❌ Bad:**

```
def gen_contact(id); end
```

## **Code Style**

* Use 2 spaces for indentation.

* Use snake_case for methods and variables.

* Use CamelCase for class and module names.

* Avoid trailing whitespace.

* Run `rubocop` before committing changes.

## **Pull Request Guidelines**

Refer to our [Pull Request Guidelines](https://www.chatwoot.com/hc/handbook/articles/pull-request-guidelines-32) for best practices on how to structure, describe, and submit your changes.

## **API Design**

* Follow RESTful conventions.

* Use JSON:API specification for consistency.

* Version APIs (e.g., `/api/v1/...`).

* Use proper status codes and include error messages in a standard format.

* Document all new endpoints by following the [Swagger Documentation Guide](https://www.chatwoot.com/hc/handbook/articles/swagger-documentation-31).

## **Background Jobs**

* Use Sidekiq for background processing.

* Name jobs with the `Job` suffix (e.g., `ContactMergeJob`).

* Keep jobs idempotent and retry-safe.

## **Database**

* Use migrations for schema changes.

* Avoid writing raw SQL unless necessary.

* Use PostgreSQL features (e.g., JSONB, GIN indexes) when beneficial.

* Index foreign keys and columns used in queries.

## **Testing**

* Use RSpec for all tests.

* Write unit, request, and system tests.

* Aim for high test coverage, especially on critical paths.

* Use FactoryBot for setting up test data.

## **Security**

* Never trust user input; sanitize and validate.

* Use `strong_parameters` in controllers.

* Avoid dynamic `eval`, `send`, or string interpolation in SQL.

## **Performance**

* Profile slow endpoints using tools like rack-mini-profiler or Skylight.

* Use N+1 detection tools (e.g., Bullet) during development.

* Cache where appropriate, but invalidate caches correctly.

## **Documentation**

* Document all new endpoints in the API reference.

* Add inline comments for complex logic.

* Update the handbook or README if behavior changes.

---

By adhering to these practices, we ensure that Chatwoot remains a scalable, maintainable, and developer-friendly codebase.