Zammad Development Guide

You are working on Zammad, an open-source web-based helpdesk/customer support system. This guide provides the essential mental model to ship changes efficiently.

Architecture Overview

Zammad is a Ruby on Rails application with three distinct frontends:

1. **Legacy desktop-app** (`app/assets/`): Original UI using CoffeeScript, Spine.js MVC framework, Sprockets, and REST API

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

3. **mobile** (`app/frontend/apps/mobile`): Modern mobile UI using Vue 3 + GraphQL

Tech Stack

Legacy Desktop-App

**Language**: CoffeeScript

**Framework**: Spine.js (MVC pattern)

**Build**: Sprockets

**API**: REST endpoints

**Testing**: QUnit (`test/`)

**Linting**: `coffeelint.json`

Modern Vue Apps (desktop-view & mobile)

**Framework**: Vue 3 with Composition API

**Language**: TypeScript

**State**: Pinia stores

**API**: Apollo Client (GraphQL)

**Styling**: Tailwind CSS

**Utilities**: VueUse composables

**Testing**: Vitest + Testing Library (unit/component), Cypress (E2E)

**Build**: Vite with vite-plugin-ruby and vite-plugin-pwa

**Linting**: ESLint, Stylelint, Prettier

**Package manager**: pnpm

Backend

**Framework**: Ruby on Rails

**Database**: PostgreSQL

**Cache/Jobs**: Redis, Delayed Job

**Real-time**: ActionCable (WebSockets)

**API**: GraphQL (`app/graphql/`)

Project Structure

```

app/

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

├── frontend/

│ ├── apps/

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

│ │ └── mobile/ # Modern mobile Vue app

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

│ └── tests/ # Vitest setup and test helpers

├── controllers/ # Rails controllers (REST + standard routes)

├── models/ # ActiveRecord models

├── views/ # Rails views/templates

├── graphql/ # GraphQL schema, types, and resolvers

├── services/ # Business logic modules

├── jobs/ # Background jobs

├── mailers/ # Email templates and logic

├── 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 integrations

├── whatsapp/ # WhatsApp integration

├── knowledge_base/ # KB features

├── secure_mailing/ # Encryption features

├── background_services/ # Background operations

└── [helpers, utilities, and feature modules]

config/ # Rails configuration

db/ # Database migrations and schema

doc/developer_manual/ # **SOURCE OF TRUTH** for setup, standards, testing

spec/ # RSpec tests (backend)

test/ # QUnit tests (legacy frontend)

```

Key Configuration Files

Always consult these files for authoritative runtime and environment details:

**Developer Manual**: `doc/developer_manual/` (index at `doc/developer_manual/index.md`)

**Dependencies**: `package.json`, `Gemfile`

**Build & Dev**: `Procfile.dev`, `vite.config.mjs`

**TypeScript**: `tsconfig.base.json` (path aliases defined here)

**Linting**: `eslint.config.ts`, `.oxlintrc.json`, `coffeelint.json`

**Database**: `config/database.yml`

Working with Legacy Desktop-App

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

Built on **Spine.js** MVC framework

Most modules are Spine classes

Uses **REST API** endpoints (see Rails controllers for routes)

Linting via `coffeelint.json`

Testing with QUnit in `test/`

**Strategy**: Prefer new work in modern Vue apps; keep legacy changes minimal

Working with Modern Vue Apps

Important Rules

1. **Path aliases**: Use aliases defined in `tsconfig.base.json`

2. **No cross-app imports**: Desktop and mobile apps are isolated (ESLint enforces boundaries)

3. **Shared code**: Place reusable code in `app/frontend/shared/`

4. **Testing**: Use Vitest + Testing Library for unit/component tests (`app/frontend/tests/`)

5. **Styling**: Use Tailwind CSS utility classes; lint with Stylelint and Prettier

6. **i18n**: Wrap all user-facing strings (rules in `eslint.config.ts`)

Testing Strategy

**Unit/Component**: Vitest + Testing Library

**E2E**: Cypress

**Test location**: `app/frontend/tests/` for setup and helpers

Always include tests for new code

Backend Development

Standard Rails Structure

**Controllers**: `app/controllers/` (REST endpoints)

**Models**: `app/models/` (ActiveRecord)

**Services**: `app/services/` (business logic modules)

**Jobs**: `app/jobs/` (background jobs via Delayed Job)

**Mailers**: `app/mailers/`

**Policies**: `app/policies/` (authorization)

GraphQL API

**Location**: `app/graphql/`

**Schema**: Type definitions and resolvers

**Used by**: Modern Vue apps (desktop-view and mobile)

lib/ Directory

Contains core extensions, integrations, and non-standard business logic:

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

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

**Features**: `auto_wizard.rb`, `knowledge_base/`, `password_policy/`, `secure_mailing/`, `escalation/`, etc.

**Core extensions**: `core_ext/`

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

Development Workflow

1. **Setup**: Follow `doc/developer_manual/` for environment setup

2. **Run locally**: Use `Procfile.dev` for development server

3. **Path aliases**: Check `tsconfig.base.json` before importing

4. **Linting**: Run ESLint/Stylelint/Prettier before committing

5. **Testing**: Add tests for all new features

6. **PRs**: Keep focused; include test coverage

When in Doubt

1. **Developer Manual** (`doc/developer_manual/`) is the source of truth

2. Check configuration files for runtime constraints

3. Follow existing patterns in the codebase

4. Prefer modern Vue apps for new features

5. Keep legacy changes minimal and isolated

Constraints

Do not cross-import between desktop and mobile apps

Always wrap user-facing strings for i18n

Include copyright headers where required (see `eslint.config.ts`)

Follow Tailwind CSS conventions for styling

Use TypeScript strict mode (configured in `tsconfig.base.json`)

Zammad Development Guide

Zammad Development Guide

Architecture Overview

Tech Stack

Legacy Desktop-App

Modern Vue Apps (desktop-view & mobile)

Backend

Project Structure

Key Configuration Files

Working with Legacy Desktop-App

Working with Modern Vue Apps

Important Rules

Testing Strategy

Backend Development

Standard Rails Structure

GraphQL API

lib/ Directory

Development Workflow

When in Doubt

Constraints

Reviews (0)