Zammad Helpdesk Development

Expert guidance for developing Zammad, an open-source web-based helpdesk/customer support platform built with Ruby on Rails and modern Vue 3 frontends.

Overview

Zammad is a comprehensive customer support system with three distinct frontends:

Tech Stack

Legacy Desktop-App

New Vue Apps (desktop-view & mobile)

Backend

Project Structure

Frontend Organization

```

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

app/frontend/

apps/

desktop/ # New desktop-view app

mobile/ # New mobile app

shared/ # Cross-app modules (components, utils, stores, graphql, i18n)

tests/ # Vitest setup and helpers

```

Backend Organization

```

app/

controllers/ # Rails controllers (REST & GraphQL)

models/ # ActiveRecord 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 schema, types, and resolvers

```

lib/ Directory

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

Other Key Directories

Development Guidelines

Always Consult Official Documentation

For authoritative setup, runtime, environment details, and coding standards, refer to:

Working with Legacy Desktop-App

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

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

3. **API**: Uses REST API endpoints (check Rails controllers for routes)

4. **Linting**: Follow `coffeelint.json` rules

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

6. **Best practice**: Minimize changes to legacy code - prefer implementing new features in desktop-view/mobile apps

Working with Vue Apps

1. **Path aliases**: Use aliases defined in `tsconfig.base.json` (e.g., `@shared/`, `@/`)

2. **App boundaries**: DO NOT cross-import between desktop/mobile apps - ESLint enforces this

3. **Shared code**: Use `app/frontend/shared/` for components, utils, stores, GraphQL queries, i18n

4. **Testing**: Write unit/component tests with Vitest and Testing Library in `app/frontend/tests/`

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

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

7. **Type safety**: Leverage TypeScript strictly - fix type errors, don't suppress them

8. **State management**: Use Pinia stores for app state

9. **GraphQL**: Use Apollo Client composables for data fetching

Code Quality Standards

1. **Linting**: Run ESLint for TypeScript/Vue, CoffeeLint for CoffeeScript, Stylelint for CSS

2. **Formatting**: Use Prettier for consistent code formatting

3. **Testing**: Include tests for all new code - unit tests for logic, component tests for UI

4. **PRs**: Keep pull requests focused on a single feature or fix

5. **Copyright/licensing**: Follow header requirements in `eslint.config.ts`

Configuration Files Reference

Common Tasks

Setting Up Development Environment

1. Consult `doc/developer_manual/` for authoritative setup instructions

2. Install Ruby, Node.js, PostgreSQL, Redis per version requirements in config files

3. Run `bundle install` for Ruby dependencies

4. Run `pnpm install` for Node dependencies

5. Set up database per `config/database.yml`

6. Start development server using `Procfile.dev` processes

Adding a New Feature

1. **Determine target app**: Choose legacy desktop-app, desktop-view, or mobile

2. **For Vue apps**:

- Add GraphQL queries/mutations in `app/graphql/`

- Create components in app-specific `components/` or `shared/components/`

- Add routes in app-specific router

- Create Pinia stores if needed

- Write Vitest tests

- Style with Tailwind utilities

3. **For legacy app**:

- Add Spine.js controllers/models in `app/assets/javascripts/`

- Add REST endpoints in Rails controllers

- Write QUnit tests

4. **Backend**:

- Add models, services, jobs as needed

- Write RSpec tests

Working with GraphQL

1. Define types, queries, mutations in `app/graphql/`

2. Implement resolvers with proper authorization checks

3. Generate TypeScript types for frontend

4. Use Apollo Client composables in Vue components

5. Test GraphQL resolvers with RSpec

Troubleshooting

1. Check `doc/developer_manual/` for common issues

2. Review relevant config files for environment constraints

3. Check logs in development console

4. Verify database migrations are up to date

5. Clear cache if seeing stale data

Key Principles

1. **Developer Manual is source of truth** - Always reference `doc/developer_manual/` for setup, testing, and standards

2. **Config files over assumptions** - Prefer referencing config files over duplicating information

3. **Prefer modern stack** - Implement new features in desktop-view/mobile apps when possible

4. **Respect app boundaries** - Don't cross-import between desktop and mobile apps

5. **Test everything** - Include tests for all new code

6. **Focus PRs** - Keep pull requests focused on single concerns

7. **Type safety first** - Leverage TypeScript fully, fix type errors properly

Integration Points

External Services (lib/ directory)

Zammad integrates with numerous external services via modules in `lib/`:

Background Processing

Real-time Features