Zammad Development Guide

This skill provides AI agents with a fast, reliable mental model of the Zammad repository to ship changes with minimal trial-and-error.

What is Zammad?

Zammad is an open-source helpdesk/customer support platform built as a Ruby on Rails application with:

Two modern Vue 3 frontends (desktop-view and mobile)

One legacy desktop-app (CoffeeScript/Sprockets)

Tech Stack

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

CoffeeScript with Spine.js MVC framework

REST API

Sprockets asset pipeline

QUnit for testing

**Modern frontends** (desktop-view and mobile in `app/frontend/apps/`):

Vue 3 with TypeScript

Pinia for state management

Apollo Client for GraphQL

Tailwind CSS for styling

VueUse composables

Vitest + Testing Library for unit/component tests

Cypress for E2E tests

pnpm package manager

vite-plugin-ruby and vite-plugin-pwa

**Backend**:

Ruby on Rails

PostgreSQL database

Redis for caching

ActionCable for WebSockets

Delayed Job for background processing

GraphQL API

Project Structure

Frontend Applications

`app/assets/` - Legacy desktop-app (CoffeeScript/Sprockets)

`app/frontend/apps/desktop/` - Modern desktop Vue app

`app/frontend/apps/mobile/` - Modern mobile Vue app

`app/frontend/shared/` - Shared cross-app code (components, utils, stores, GraphQL, i18n)

`app/frontend/tests/` - Vitest setup and test helpers

Backend (Rails Standard)

`app/controllers/` - Rails controllers

`app/models/` - ActiveRecord models

`app/views/` - View templates

`app/jobs/` - Background jobs

`app/mailers/` - Email mailers

`app/helpers/` - View helpers

`app/channels/` - ActionCable channels

`app/policies/` - Authorization policies

`app/services/` - Business logic modules

`app/graphql/` - GraphQL API definitions and resolvers

lib/ Directory

Contains core extensions, helpers, integrations, and business logic:

**Helpers/utilities**: `email_helper.rb`, `migration_helper.rb`, `sql_helper.rb`, `image_helper.rb`, `session_helper.rb`, etc.

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

**Business logic**: `auto_wizard.rb`, `calendar_subscriptions/`, `escalation/`, `knowledge_base/`, `password_policy/`, `secure_mailing/`, etc.

**Core extensions**: `core_ext/` for Ruby/Rails extensions

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

Other Key Directories

`bin/` - Executable scripts

`config/` - Rails and app configuration

`db/` - Database migrations and schema

`doc/developer_manual/` - Developer documentation (source of truth)

`script/` - Development and deployment scripts

`spec/` - RSpec tests

`test/` - QUnit tests for legacy app

Key Configuration Files

Always refer to these files for authoritative setup and environment details:

`doc/developer_manual/` (index: `doc/developer_manual/index.md`) - Primary documentation

`package.json` - Node dependencies and scripts

`Gemfile` - Ruby dependencies

`config/database.yml` - Database configuration

`Procfile.dev` - Development process definitions

`vite.config.mjs` - Vite bundler configuration

`tsconfig.base.json` - TypeScript configuration with path aliases

`eslint.config.ts` - ESLint rules (includes i18n and copyright requirements)

`coffeelint.json` - CoffeeLint rules for legacy code

Development Guidelines

For Legacy desktop-app

1. Located in `app/assets/javascripts` and `app/assets/stylesheets`

2. Uses Spine.js for MVC structure - most modules are Spine classes

3. Communicates via REST API endpoints (see Rails controllers)

4. Linting: Use `coffeelint.json` configuration

5. Testing: QUnit tests in `test/` directory

6. **Minimize changes** - prefer implementing new features in desktop-view/mobile apps

For Vue Apps (desktop-view and mobile)

1. **Use path aliases** from `tsconfig.base.json` for imports

2. **Never cross-import** between desktop/mobile apps - ESLint enforces app boundaries

3. **Shared code** goes in `app/frontend/shared/`

4. **Testing**: Write Vitest + Testing Library tests in `app/frontend/tests/`

5. **Styling**: Use Tailwind CSS utility classes

6. **Linting**: Code must pass ESLint, Stylelint, and Prettier checks

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

General Best Practices

1. **Consult the Developer Manual** (`doc/developer_manual/`) for setup, testing, and coding standards

2. **Check config files** for tool versions, scripts, and environment variables

3. **Avoid over-engineering** - only make changes directly requested or clearly necessary

4. **Keep solutions simple** and focused on the task

5. **Don't add unnecessary features** or refactor surrounding code

6. **Avoid premature abstractions** - prefer simple, direct code

7. **Delete unused code completely** - no backward-compatibility hacks like `_vars` or `// removed` comments

8. **Include tests** for all new code

9. **Keep PRs focused** on a single concern

10. **Security**: Avoid OWASP Top 10 vulnerabilities (XSS, SQL injection, command injection, etc.)

Error Handling and Validation

Only validate at system boundaries (user input, external APIs)

Trust internal code and framework guarantees

Don't add error handling for scenarios that can't happen

When in Doubt

1. The **Developer Manual** (`doc/developer_manual/`) is the source of truth for setup, testing, and standards

2. **Reference config files** instead of assuming or duplicating information

3. **Ask for clarification** before making architectural decisions

4. **Start with the simplest solution** that meets requirements

Zammad Development Guide

Zammad Development Guide

What is Zammad?

Tech Stack

Project Structure

Frontend Applications

Backend (Rails Standard)

lib/ Directory

Other Key Directories

Key Configuration Files

Development Guidelines

For Legacy desktop-app

For Vue Apps (desktop-view and mobile)

General Best Practices

Error Handling and Validation

When in Doubt

Reviews (0)