Zammad Helpdesk Development

AI coding agent instructions for contributing to Zammad, an open-source helpdesk/customer support platform.

What is Zammad?

Zammad is a web-based open-source helpdesk/customer support system. It's a Ruby on Rails application with:

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

One legacy desktop-app under `app/assets`

Architecture Overview

Applications

1. **desktop-app (legacy)** - `app/assets`

- Legacy UI using REST API + CoffeeScript/Sprockets

- Uses Spine.js MVC framework for frontend structure and state management

2. **desktop-view** - `app/frontend/apps/desktop`

- New UI using Vue + GraphQL

3. **mobile** - `app/frontend/apps/mobile`

- New UI using Vue + GraphQL

Tech Stack

**Legacy desktop-app:**

CoffeeScript, Spine.js, Sprockets, REST API

Config: `coffeelint.json`

Tests: QUnit in `test/`

**New desktop-view and mobile apps:**

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

Tailwind CSS, VueUse, Vitest, Testing Library, Cypress

Build: pnpm, vite-plugin-ruby, vite-plugin-pwa

Linting: ESLint, Stylelint, Prettier

**Backend:**

Ruby on Rails, PostgreSQL, Redis

ActionCable, Delayed Job, GraphQL

Project Structure

```

app/

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

├── frontend/ # Vue + TypeScript frontends

│ ├── apps/

│ │ ├── desktop/ # Desktop-view app

│ │ └── mobile/ # Mobile 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

├── helpers/ # View helpers

├── 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 more)

config/ # Configuration files

db/ # Database migrations and seeds

doc/developer_manual/ # Developer documentation

spec/ # RSpec tests

test/ # Legacy tests

```

Key Configuration Files

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

`doc/developer_manual/` (index: `doc/developer_manual/index.md`)

`package.json` - Node dependencies and scripts

`Gemfile` - Ruby dependencies

`config/database.yml` - Database configuration

`Procfile.dev` - Development process configuration

`vite.config.mjs` - Vite build configuration

`tsconfig.base.json` - TypeScript configuration

`eslint.config.ts` - ESLint configuration

`.oxlintrc.json` - Oxlint configuration

Development Instructions

General Guidelines

1. **Always consult the Developer Manual** (`doc/developer_manual/`) for:

- Setup instructions

- Testing guidelines

- Coding standards

- Troubleshooting

2. **Check configuration files** for:

- Tool versions

- Environment variables

- Path aliases (see `tsconfig.base.json`)

- Linting rules

3. **Keep PRs focused** and include tests for new code

Working with Legacy Desktop-App

**Location:** `app/assets/javascripts` and `app/assets/stylesheets`

**Guidelines:**

Uses Spine.js for MVC structure (most modules are Spine classes)

Uses REST API endpoints (see Rails controllers for routes)

Linting: `coffeelint.json`

Testing: QUnit in `test/`

**Important:** Prefer new work in desktop-view/mobile; keep legacy changes minimal

Working with Vue Apps

**Guidelines:**

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

2. **Do not cross-import** between desktop/mobile apps (ESLint enforces boundaries)

3. **Testing:**

- Use Vitest and Testing Library for unit/component tests

- Test setup in `app/frontend/tests/`

4. **Styling:**

- Use Tailwind CSS utilities

- Lint with Stylelint and Prettier

5. **Internationalization:**

- Wrap user-facing strings

- See `eslint.config.ts` for i18n rules

6. **Shared code:**

- Place cross-app modules in `app/frontend/shared/`

- Includes: components, utils, stores, GraphQL, i18n

Working with Backend (Rails)

**Key directories:**

`app/controllers/` - HTTP endpoints

`app/models/` - Data models

`app/services/` - Business logic

`app/graphql/` - GraphQL API

`lib/` - Core extensions, helpers, integrations

**lib/ directory:**

Contains essential backend functionality:

**Helpers:** email, migration, SQL, image, session, etc.

**Integrations:** GitHub, GitLab, Microsoft Graph, Facebook, Telegram, WhatsApp, etc.

**Business logic:** escalation, knowledge base, password policy, secure mailing, stats, etc.

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

**Background services:** Operations rate limiter, sequencer, transaction dispatcher

Testing

**Frontend (Vue):** Vitest + Testing Library + Cypress

**Frontend (Legacy):** QUnit

**Backend:** RSpec (in `spec/`)

Linting and Formatting

**Frontend:** ESLint, Stylelint, Prettier

**Legacy:** CoffeeLint

**Copyright/i18n:** See `eslint.config.ts` for rules

Common Workflows

Adding a new feature

1. Determine if it belongs in desktop-view, mobile, or backend

2. If frontend, place shared code in `app/frontend/shared/`

3. Add tests (Vitest for Vue, RSpec for Rails)

4. Follow coding standards in Developer Manual

5. Ensure i18n for user-facing strings

Modifying legacy code

1. Understand Spine.js MVC pattern

2. Keep changes minimal

3. Consider migrating to Vue if substantial work needed

4. Add/update QUnit tests

Working with GraphQL

1. Define schema in `app/graphql/`

2. Add resolvers

3. Use Apollo Client in Vue apps

4. Test with RSpec

Integrating external services

1. Add integration code to `lib/`

2. Follow existing patterns (see `lib/github/`, `lib/gitlab/`, etc.)

3. Add configuration in `config/`

4. Document in Developer Manual

When in Doubt

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

2. **Reference config files** - don't duplicate information

3. **Look at existing code** - follow established patterns

4. **Ask maintainers** - open an issue or discussion if unclear

Important Constraints

**App boundaries:** Do not cross-import between desktop/mobile apps

**Legacy vs. new:** Prefer new Vue apps for new features

**Testing:** Always include tests for new code

**i18n:** Wrap all user-facing strings

**Focus:** Keep PRs focused on single concerns

Zammad Helpdesk Development

Zammad Helpdesk Development

What is Zammad?

Architecture Overview

Applications

Tech Stack

Project Structure

Key Configuration Files

Development Instructions

General Guidelines

Working with Legacy Desktop-App

Working with Vue Apps

Working with Backend (Rails)

Testing

Linting and Formatting

Common Workflows

Adding a new feature

Modifying legacy code

Working with GraphQL

Integrating external services

When in Doubt

Important Constraints

Reviews (0)