Zammad Development Assistant

Expert coding agent for Zammad, an open-source web-based helpdesk/customer support system. Provides fast, reliable guidance for shipping changes across Rails backend, Vue frontends, and legacy CoffeeScript app with minimal trial-and-error.

What This Skill Does

Helps developers navigate and contribute to the Zammad codebase by:

Understanding the multi-frontend architecture (legacy desktop-app, modern desktop-view, mobile)

Following project conventions and coding standards

Referencing authoritative documentation and config files

Maintaining proper boundaries between apps and modules

Writing tests and following quality standards

Architecture Overview

**Three Frontend Applications:**

1. **desktop-app (legacy)**: CoffeeScript + Spine.js MVC + Sprockets, uses REST API

- Location: `app/assets/`

- Testing: QUnit in `test/`

- Lint config: `coffeelint.json`

2. **desktop-view (modern)**: Vue 3 + TypeScript + GraphQL

- Location: `app/frontend/apps/desktop`

- State: Pinia stores

- Styling: Tailwind CSS

3. **mobile**: Vue 3 + TypeScript + GraphQL

- Location: `app/frontend/apps/mobile`

- State: Pinia stores

- Styling: Tailwind CSS

**Backend:**

Ruby on Rails with PostgreSQL, Redis, ActionCable, Delayed Job, GraphQL

Standard Rails structure: `app/controllers/`, `app/models/`, `app/views/`, `app/jobs/`, `app/mailers/`, `app/policies/`, `app/channels/`

Business logic: `app/services/`

GraphQL API: `app/graphql/`

**Shared Frontend Code:**

Location: `app/frontend/shared/`

Contains: components, utilities, stores, GraphQL definitions, i18n

Used by both desktop-view and mobile apps

**Library Directory (`lib/`):**

Core extensions, helpers, integrations, business logic

Key categories:

- 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`, `calendar_subscriptions/`, `escalation/`, `knowledge_base/`, `password_policy/`, `secure_mailing/`, etc.

- Core extensions: `core_ext/`

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

Tech Stack Reference

**Legacy desktop-app:**

CoffeeScript, Spine.js, Sprockets, REST API

Config: `coffeelint.json`

Tests: QUnit

**Modern Vue apps (desktop-view + mobile):**

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

Tailwind CSS, VueUse

Testing: Vitest, Testing Library, Cypress

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

Linting: ESLint, Stylelint, Prettier

Config: `package.json`, `vite.config.mjs`, `tsconfig.base.json`, `eslint.config.ts`

**Backend:**

Ruby on Rails, PostgreSQL, Redis, ActionCable, Delayed Job, GraphQL

Config: `Gemfile`, `config/`, `config/database.yml`, `Procfile.dev`

Step-by-Step Instructions

1. Understand the Task Context

Before making changes:

Identify which app(s) the task affects (legacy desktop-app, desktop-view, mobile, backend, shared)

Check if it's a new feature (prefer modern Vue apps) or maintenance (keep legacy changes minimal)

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

2. Reference Authoritative Config Files

For runtime, environment, and setup details, always check:

`package.json` - npm dependencies, scripts, tool versions

`Gemfile` - Ruby gems, Rails version

`config/database.yml` - database config

`Procfile.dev` - development server setup

`vite.config.mjs` - Vite build config

`tsconfig.base.json` - TypeScript config and path aliases

`eslint.config.ts` - ESLint rules, copyright headers, i18n rules

`.oxlintrc.json` - Additional linting config

3. Navigate the Codebase

**Project structure:**

```

app/

assets/ # Legacy desktop-app (CoffeeScript)

frontend/

apps/

desktop/ # Modern desktop-view (Vue)

mobile/ # Mobile app (Vue)

shared/ # Cross-app modules

tests/ # Vitest setup and helpers

controllers/ # Rails controllers

models/ # Rails models

views/ # Rails views

jobs/ # Background jobs

mailers/ # Email templates

helpers/ # View helpers

channels/ # ActionCable channels

policies/ # Authorization policies

services/ # Business logic

graphql/ # GraphQL API

lib/ # Core extensions, helpers, integrations

bin/ # Executable scripts

config/ # App configuration

db/ # Database migrations and schema

doc/developer_manual/ # Developer documentation

spec/ # RSpec tests

test/ # QUnit tests (legacy)

```

**Path aliases (from `tsconfig.base.json`):**

Use configured aliases for imports in Vue apps

Check `tsconfig.base.json` for current mappings

4. Follow Coding Standards

**For Vue apps (desktop-view/mobile):**

DO NOT cross-import between desktop and mobile apps (ESLint enforces boundaries)

Use Tailwind CSS utilities for styling

Wrap all user-facing strings for i18n (ESLint enforces)

Write unit/component tests with Vitest and Testing Library

Place tests in `app/frontend/tests/`

Follow ESLint and Stylelint rules

Use Prettier for code formatting

**For legacy desktop-app:**

Minimize changes; prefer new work in modern apps

Follow Spine.js MVC patterns

Use REST API endpoints (check Rails controllers for routes)

Follow `coffeelint.json` rules

Write QUnit tests in `test/`

**For backend:**

Follow Rails conventions

Place business logic in `app/services/`

Use GraphQL for new API endpoints

Write RSpec tests in `spec/`

5. Testing Requirements

Include tests for all new code

Use appropriate testing framework:

- Vue components: Vitest + Testing Library

- Backend: RSpec

- Legacy frontend: QUnit

- E2E: Cypress

6. Consult Documentation When Uncertain

The Developer Manual (`doc/developer_manual/`) is the source of truth for:

Setup and installation

Testing procedures

Troubleshooting

Coding standards

Architecture decisions

Reference config files rather than duplicating information.

7. Keep PRs Focused

Make targeted, single-purpose changes

Include relevant tests

Follow existing patterns and conventions

Update documentation if needed

Key Constraints

**App boundaries**: No cross-imports between desktop/mobile apps

**Legacy app**: Keep changes minimal; prefer modern apps for new features

**i18n**: All user-facing strings must be wrapped for translation

**Testing**: New code requires appropriate test coverage

**Styling**: Use Tailwind utilities in Vue apps

**API**: Prefer GraphQL for new endpoints; REST for legacy compatibility

Common Patterns

**Adding a Vue component:**

1. Decide if it's app-specific (desktop/mobile) or shared

2. Place in appropriate directory

3. Use TypeScript and Composition API

4. Apply Tailwind styling

5. Wrap user-facing strings for i18n

6. Write Vitest tests

**Adding a GraphQL endpoint:**

1. Define schema in `app/graphql/`

2. Implement resolver

3. Add to appropriate type/query/mutation

4. Write RSpec tests

5. Update frontend queries if needed

**Modifying backend logic:**

1. Check if it affects GraphQL or REST API

2. Update `app/services/` for business logic

3. Modify models/controllers as needed

4. Write/update RSpec tests

5. Consider impact on all three frontends

Examples

**Example 1: Adding a shared Vue component**

```typescript

// File: app/frontend/shared/components/CommonElements/MyComponent.vue

import { useI18n } from 'vue-i18n'

const { t } = useI18n()

// Component logic

</script>

</div>

</template>

```

**Example 2: Adding a GraphQL query**

```ruby

File: app/graphql/types/query_type.rb

field :my_data, [Types::MyDataType], null: false do

description 'Fetch my data'

end

def my_data

# Resolver logic

end

```

**Example 3: Using path aliases**

```typescript

// Use configured aliases from tsconfig.base.json

import { useStore } from '#shared/stores/myStore'

import MyComponent from '#desktop/components/MyComponent.vue'

```

When to Consult Documentation

**Setup/installation issues** → `doc/developer_manual/`

**Testing procedures** → `doc/developer_manual/`

**Tool versions** → `package.json`, `Gemfile`

**Environment config** → `config/database.yml`, `Procfile.dev`

**Build config** → `vite.config.mjs`, `tsconfig.base.json`

**Linting rules** → `eslint.config.ts`, `coffeelint.json`

**Path aliases** → `tsconfig.base.json`

Notes

Prefer modern Vue apps (desktop-view/mobile) for new features

Keep legacy desktop-app changes minimal and focused

Always reference config files for authoritative runtime/environment details

The `lib/` directory contains essential integrations and business logic not in standard Rails structure

GraphQL is preferred for new API development

All Vue apps share code via `app/frontend/shared/`

Zammad Development Assistant

Safety Concern

Zammad Development Assistant

What This Skill Does

Architecture Overview

Tech Stack Reference

Step-by-Step Instructions

1. Understand the Task Context

2. Reference Authoritative Config Files

3. Navigate the Codebase

4. Follow Coding Standards

5. Testing Requirements

6. Consult Documentation When Uncertain

7. Keep PRs Focused

Key Constraints

Common Patterns

Examples

File: app/graphql/types/query_type.rb

When to Consult Documentation

Notes

Reviews (0)