Zammad Development Guide

You are an expert at developing features and fixing bugs in Zammad, an open-source helpdesk/customer support platform. This skill provides you with the mental model and guidelines needed to work effectively in this codebase.

Project Overview

Zammad is a Ruby on Rails application with three frontend applications:

Tech Stack

Legacy desktop-app

Modern Vue Apps (desktop-view & mobile)

Backend

Project Structure

```

app/

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

│ ├── javascripts/

│ └── stylesheets/

├── frontend/ # Modern Vue + TypeScript frontends

│ ├── apps/

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

│ │ └── mobile/ # Mobile app

│ ├── shared/ # Cross-app code (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/, gitlab/ # External integrations

├── knowledge_base/ # Feature modules

├── password_policy/

├── secure_mailing/

└── [many more helpers and feature modules]

doc/developer_manual/ # Source of truth for setup and standards

config/ # Rails configuration

db/ # Database migrations and schema

spec/ # RSpec tests

test/ # Legacy tests (QUnit)

```

Development Guidelines

1. Always Check Authoritative Sources

Before making changes, consult:

2. Frontend Development

#### Vue Apps (desktop-view & mobile)

#### Legacy desktop-app

3. Backend Development

- Helpers: `email_helper.rb`, `migration_helper.rb`, `sql_helper.rb`, etc.

- Integrations: `github/`, `gitlab/`, `microsoft_graph/`, `facebook.rb`, etc.

- Features: `knowledge_base/`, `password_policy/`, `secure_mailing/`, etc.

- Core extensions: `core_ext/`

4. Testing

5. Pull Requests

Common Tasks

Adding a Vue Component (desktop-view or mobile)

1. Determine if it's app-specific or shared

2. If shared, add to `app/frontend/shared/components/`

3. If app-specific, add to `app/frontend/apps/{desktop|mobile}/components/`

4. Use TypeScript and Composition API

5. Style with Tailwind utilities

6. Add i18n for user-facing text

7. Write component tests with Vitest

Adding a GraphQL Endpoint

1. Define types in `app/graphql/types/`

2. Add resolver in `app/graphql/resolvers/`

3. Wire up in schema

4. Add corresponding backend logic in models/services

5. Write specs for resolver and backend logic

Modifying Legacy desktop-app

1. Locate relevant Spine class in `app/assets/javascripts/`

2. Make minimal, focused changes

3. Update QUnit tests if needed

4. Consider if functionality should migrate to modern apps

Adding Backend Feature

1. Check `lib/` for existing similar functionality

2. Add business logic to `app/services/`

3. Add models/migrations to `app/models/` and `db/migrate/`

4. Add controller endpoints if needed

5. Write RSpec tests in `spec/`

When In Doubt

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

2. **Check config files** for runtime and environment constraints

3. **Prefer existing patterns** - grep for similar code before inventing new approaches

4. **Keep PRs focused** - one concern per PR

5. **Test everything** - no code without tests

Important Reminders