Zammad Helpdesk Development

Expert guidance for developing Zammad, an open-source helpdesk/customer support platform.

Overview

Zammad is a Ruby on Rails application with three frontends:

Tech Stack

Legacy Desktop-App

Modern Apps (Desktop-View & Mobile)

Backend

Project Structure

```

app/

├── assets/ # Legacy desktop-app (CoffeeScript/Sprockets)

├── frontend/

│ ├── apps/

│ │ ├── desktop/ # New desktop Vue app

│ │ └── mobile/ # Mobile Vue app

│ ├── shared/ # Cross-app modules (components, utils, stores, graphql, i18n)

│ └── tests/ # Vitest setup and helpers

├── controllers/ # Rails controllers

├── models/ # Rails models

├── views/ # Rails views

├── graphql/ # GraphQL API definitions and resolvers

├── services/ # Business logic modules

├── jobs/ # Background jobs

├── mailers/ # Email mailers

├── channels/ # ActionCable channels

├── policies/ # Authorization policies

└── helpers/ # View helpers

lib/ # Core extensions, integrations, business logic

├── core_ext/ # Ruby/Rails extensions

├── github/, gitlab/ # Git integrations

├── microsoft_graph/ # Microsoft integration

├── whatsapp/ # WhatsApp integration

├── knowledge_base/ # KB functionality

├── secure_mailing/ # Email security

├── background_services/ # Background workers

└── [helpers, utilities, integrations]

config/ # Configuration files

db/ # Database migrations and schema

doc/developer_manual/ # **Source of truth for setup, testing, standards**

spec/ # RSpec tests

test/ # QUnit tests (legacy)

```

Development Instructions

1. Always Consult Documentation First

Before making changes, reference:

2. Legacy Desktop-App Development

When working on `app/assets/`:

3. Vue Apps Development

When working on `app/frontend/apps/desktop` or `app/frontend/apps/mobile`:

**Architecture Rules:**

**Styling:**

**Internationalization:**

**Testing:**

**State Management:**

4. Backend Development

When working on Rails code:

**lib/ Directory:**

5. General Coding Standards

**Pull Requests:**

**File References:**

**When Uncertain:**

Common Tasks

Adding a New Feature

1. Determine which app(s) need changes (legacy vs. desktop-view vs. mobile)

2. For new features, **prefer Vue apps** over legacy

3. Add shared components to `app/frontend/shared/`

4. Add GraphQL types/resolvers to `app/graphql/` if needed

5. Add business logic to `app/services/` or `lib/`

6. Write tests (Vitest for Vue, RSpec for Rails, QUnit for legacy)

Modifying GraphQL API

1. Update schema in `app/graphql/`

2. Update resolvers and mutations

3. Run GraphQL codegen if configured

4. Update frontend queries/mutations in Vue apps

Working with Database

1. Create migrations in `db/migrate/`

2. Check `config/database.yml` for database configuration

3. Update models in `app/models/`

4. Add model tests in `spec/models/`

Styling Changes

1. Use Tailwind utilities in Vue components

2. Legacy styles in `app/assets/stylesheets/`

3. Lint with Stylelint and Prettier

Key Principles

1. **Documentation First**: Always check `doc/developer_manual/` and config files

2. **Modernize**: Prefer Vue apps over legacy for new work

3. **Separation**: Don't cross-import between desktop/mobile apps

4. **Testing**: Include tests with all changes

5. **Focus**: Keep PRs small and focused

6. **Standards**: Follow linting rules and existing patterns