Zammad Helpdesk Development

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

Overview

Zammad is an open-source helpdesk/customer support platform built with Ruby on Rails. It features:

Tech Stack

Legacy Desktop App

Modern Vue Apps (Desktop & Mobile)

Backend

Project Structure

```

app/

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

├── frontend/ # Vue + TypeScript frontends

│ ├── apps/

│ │ ├── desktop/ # 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

├── jobs/ # Background jobs

├── mailers/ # Email mailers

├── channels/ # ActionCable channels

├── policies/ # Authorization policies

├── services/ # Business logic modules

└── graphql/ # GraphQL API definitions and resolvers

lib/ # Core extensions, helpers, integrations

├── core_ext/ # Ruby/Rails extensions

├── github/ # GitHub integration

├── gitlab/ # GitLab integration

├── microsoft_graph/ # Microsoft Graph integration

├── whatsapp/ # WhatsApp integration

├── knowledge_base/ # Knowledge base features

├── secure_mailing/ # Secure email features

└── [many other modules]

config/ # Application configuration

db/ # Database migrations and seeds

doc/developer_manual/ # **PRIMARY DOCUMENTATION SOURCE**

spec/ # RSpec tests

test/ # QUnit tests (legacy)

```

Step-by-Step Instructions

1. Always Reference Documentation First

**Before making any changes**, consult these authoritative sources:

2. Determine Which App to Modify

3. Working with Legacy Desktop App

When modifying legacy code:

1. Navigate to `app/assets/javascripts` or `app/assets/stylesheets`

2. Understand Spine.js MVC structure (most modules are Spine classes)

3. Use REST API endpoints (check Rails controllers for routes)

4. Lint with `coffeelint.json` rules

5. Add QUnit tests in `test/` directory

6. **Keep changes minimal** - prefer moving features to Vue apps

4. Working with Vue Apps

When developing Vue features:

1. **Use path aliases** from `tsconfig.base.json` (e.g., `@shared/`, `@/`)

2. **Never cross-import** between desktop and mobile apps (ESLint enforces boundaries)

3. **Place shared code** in `app/frontend/shared/`

4. **Use Tailwind CSS utilities** for styling

5. **Wrap user-facing strings** in i18n helpers (see `eslint.config.ts` for rules)

6. **Write tests** using Vitest and Testing Library in `app/frontend/tests/`

7. **Follow GraphQL patterns** using Apollo Client

8. **Use Pinia stores** for state management

5. Backend Development

When modifying Rails backend:

1. **Follow Rails conventions** for controllers, models, views, jobs, mailers

2. **Business logic** goes in `app/services/`

3. **GraphQL API** definitions in `app/graphql/`

4. **Integrations and helpers** in `lib/`

5. **Write RSpec tests** in `spec/`

6. **Use PostgreSQL** as primary database

7. **Background jobs** with Delayed Job

6. Testing

7. Code Quality

8. Key lib/ Directory Modules

When working with backend integrations or utilities:

Important Constraints

1. **No cross-app imports**: Desktop and mobile Vue apps must not import from each other

2. **Prefer modern stack**: New features should use Vue 3 apps, not legacy CoffeeScript

3. **Test coverage required**: All new code must include appropriate tests

4. **Follow i18n rules**: All user-facing strings must be internationalized

5. **Use path aliases**: Defined in `tsconfig.base.json`

6. **Config is source of truth**: Always defer to config files for versions, environment, and tooling

When in Doubt

1. Check the **Developer Manual** (`doc/developer_manual/`) first

2. Reference **config files** over assumptions

3. Keep **PRs focused** on specific changes

4. **Include tests** for all new functionality

5. **Ask for clarification** if requirements are ambiguous

Examples

Adding a Vue Component to Desktop

```typescript

// app/frontend/apps/desktop/components/MyFeature.vue

<script setup lang="ts">

import { ref } from 'vue'

import { useI18n } from '@shared/composables/useI18n'

const { t } = useI18n()

const count = ref(0)

</script>

<template>

<div class="flex items-center gap-2">

<button @click="count++" class="btn-primary">

{{ t('Click me') }}

</button>

<span>{{ count }}</span>

</div>

</template>

```

Adding a GraphQL Query

```typescript

// app/frontend/shared/graphql/queries/myFeature.api.ts

import { gql } from '@apollo/client'

export const MY_FEATURE_QUERY = gql`

query MyFeature($id: ID!) {

myFeature(id: $id) {

id

name

description

}

}

`

```

Adding a Rails Service

```ruby

app/services/my_feature_service.rb

class MyFeatureService

def self.perform(params)

# Business logic here

new(params).perform

end

def initialize(params)

@params = params

end

def perform

# Implementation

end

end

```

This skill enables efficient navigation and development across Zammad's multi-frontend, Rails-backed architecture.