Zammad Helpdesk Development

Guide AI agents to effectively contribute to Zammad, an open-source helpdesk/customer support platform built with Ruby on Rails and modern Vue frontends.

Overview

Zammad is a web-based open-source helpdesk/customer support system with:

**Backend:** Ruby on Rails with GraphQL and REST APIs

**New frontends:** Two Vue 3 apps (desktop-view and mobile)

**Legacy frontend:** CoffeeScript/Sprockets desktop-app

**Database:** PostgreSQL with Redis for caching/jobs

Architecture

Three Frontend Applications

1. **desktop-app** (legacy, `app/assets/`): CoffeeScript with Spine.js MVC framework, REST API

2. **desktop-view** (`app/frontend/apps/desktop`): Vue 3 + TypeScript + GraphQL

3. **mobile** (`app/frontend/apps/mobile`): Vue 3 + TypeScript + GraphQL

Tech Stack

**Legacy (desktop-app):**

CoffeeScript, Spine.js, Sprockets, REST API, QUnit tests

Config: `coffeelint.json`

**Modern (desktop-view/mobile):**

Vue 3, TypeScript, Pinia, Apollo Client (GraphQL), Tailwind CSS

VueUse, Vitest, Testing Library, Cypress, pnpm, Vite

Config: `package.json`, `vite.config.mjs`, `tsconfig.base.json`, `eslint.config.ts`

**Backend:**

Ruby on Rails, PostgreSQL, Redis, ActionCable, Delayed Job, GraphQL

Config: `Gemfile`, `config/database.yml`, `Procfile.dev`

Directory Structure

```

app/

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

├── frontend/ # Vue + TypeScript frontends

│ ├── apps/

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

│ │ └── mobile/ # Mobile Vue app

│ ├── shared/ # Cross-app 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 logic

├── channels/ # ActionCable channels

└── policies/ # Authorization policies

lib/ # Core extensions, integrations, helpers

├── core_ext/ # Ruby/Rails extensions

├── github/ # GitHub integration

├── gitlab/ # GitLab integration

├── knowledge_base/ # Knowledge base features

├── secure_mailing/ # Secure email features

└── [many more] # Helpers, integrations, business logic

doc/developer_manual/ # Official setup and development docs

spec/ # RSpec tests

test/ # QUnit tests (legacy)

config/ # Rails configuration

db/ # Database migrations and seeds

```

Step-by-Step Development Workflow

1. Consult Documentation First

Before making changes, check authoritative sources:

**Developer Manual:** `doc/developer_manual/index.md` for setup, testing, standards

**Config files:** `package.json`, `Gemfile`, `config/database.yml`, `vite.config.mjs`, `tsconfig.base.json`, `eslint.config.ts`

**Path aliases:** Defined in `tsconfig.base.json`

2. Determine Which App to Modify

**Legacy desktop-app (`app/assets/`):**

CoffeeScript with Spine.js

REST API endpoints

Keep changes minimal; prefer new work in Vue apps

Lint with `coffeelint.json`

Test with QUnit in `test/`

**Modern Vue apps (`app/frontend/apps/desktop` or `mobile`):**

Vue 3 + TypeScript + GraphQL

Use path aliases from `tsconfig.base.json`

**Do NOT cross-import between desktop/mobile apps** (ESLint enforces boundaries)

Shared code goes in `app/frontend/shared/`

Test with Vitest and Testing Library

Style with Tailwind CSS utilities

3. Backend Changes (Rails)

**Controllers:** `app/controllers/` for REST or GraphQL endpoints

**Models:** `app/models/` for database logic

**Services:** `app/services/` for business logic

**Jobs:** `app/jobs/` for background tasks

**GraphQL:** `app/graphql/` for schema and resolvers

**Lib:** `lib/` for helpers, integrations, core extensions

4. Frontend Changes (Vue Apps)

**Shared code:** `app/frontend/shared/`

Components, utilities, stores (Pinia), GraphQL queries, i18n

**App-specific code:** `app/frontend/apps/desktop` or `mobile`

**Styling:** Use Tailwind CSS utilities; lint with Stylelint and Prettier

**i18n:** Wrap all user-facing strings for translation (see `eslint.config.ts` rules)

**Testing:**

Unit/component tests: Vitest + Testing Library in `app/frontend/tests/`

E2E tests: Cypress

5. Follow Coding Standards

**Linting:**

Vue/TypeScript: `eslint.config.ts`, `.oxlintrc.json`

Legacy CoffeeScript: `coffeelint.json`

Styles: Stylelint, Prettier

**Copyright/i18n:** Follow rules in `eslint.config.ts`

**Testing:** Include tests for all new code

6. Keep PRs Focused

One feature or fix per PR

Reference Developer Manual for standards

Avoid over-engineering or scope creep

Key Integrations and Features (lib/)

The `lib/` directory contains essential non-Rails-standard modules:

**Helpers:** `email_helper.rb`, `migration_helper.rb`, `sql_helper.rb`, `image_helper.rb`, `notification_factory.rb`

**Integrations:** `github/`, `gitlab/`, `microsoft_graph/`, `facebook.rb`, `telegram_helper.rb`, `whatsapp/`

**Features:** `knowledge_base/`, `secure_mailing/`, `calendar_subscriptions/`, `escalation/`, `password_policy/`

**Background services:** `background_services/`, `operations_rate_limiter.rb`, `sequencer/`

**Core extensions:** `core_ext/`

Common Pitfalls

1. **Cross-app imports:** Do NOT import between desktop and mobile apps (use `shared/`)

2. **Legacy over-modification:** Minimize changes to `app/assets/`; prefer Vue apps for new work

3. **Missing i18n:** Always wrap user-facing strings for translation

4. **Ignoring linters:** Run ESLint, Stylelint, Prettier, and RuboCop before committing

5. **Skipping tests:** Always include tests for new features and bug fixes

When in Doubt

**Read `doc/developer_manual/`** for authoritative setup, testing, and coding standards

**Check config files** (`package.json`, `Gemfile`, `tsconfig.base.json`, etc.) for versions and constraints

**Keep changes focused** and follow existing patterns in the codebase

Zammad Helpdesk Development

Zammad Helpdesk Development

Overview

Architecture

Three Frontend Applications

Tech Stack

Directory Structure

Step-by-Step Development Workflow

1. Consult Documentation First

2. Determine Which App to Modify

3. Backend Changes (Rails)

4. Frontend Changes (Vue Apps)

5. Follow Coding Standards

6. Keep PRs Focused

Key Integrations and Features (lib/)

Common Pitfalls

When in Doubt

Reviews (0)