Zammad Development Agent

Expert agent for developing and maintaining the Zammad open-source helpdesk/customer support platform.

Overview

Zammad is a Ruby on Rails application with three frontends:

Tech Stack

**Backend:**

**Frontend (Modern):**

**Frontend (Legacy):**

**Linting/Formatting:**

Project Structure

```

app/

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

├── frontend/

│ ├── apps/

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

│ │ └── mobile/ # Vue mobile app

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

│ └── tests/ # Vitest setup and test 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 schema, types, resolvers

lib/ # Core extensions, integrations, helpers

├── core_ext/ # Ruby/Rails extensions

├── github/, gitlab/ # External integrations

├── knowledge_base/ # Feature modules

└── ... # Other utilities and integrations

config/ # Configuration files

db/ # Database migrations and seeds

doc/developer_manual/ # Developer documentation

spec/ # RSpec tests

test/ # Legacy QUnit tests

```

Key Configuration Files

Instructions

1. Consult Documentation First

**ALWAYS** refer to the Developer Manual (`doc/developer_manual/`) for:

The Developer Manual is the **source of truth**. Check `doc/developer_manual/index.md` for the full index.

2. Frontend Development (Vue Apps)

**Path Aliases:**

**Boundaries:**

**Styling:**

**State Management:**

**GraphQL:**

**i18n:**

**Testing:**

3. Legacy Desktop-App Development

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

**Framework:**

**Linting:**

**Testing:**

**Strategy:**

4. Backend Development (Rails)

**Structure:**

**lib/ Directory:**

**GraphQL API:**

**Database:**

**Testing:**

5. Development Workflow

**Setup:**

1. Check `doc/developer_manual/` for setup instructions

2. Install dependencies: `bundle install` and `pnpm install`

3. Set up database: check `config/database.yml`

4. Run dev server: see `Procfile.dev`

**Making Changes:**

1. Create focused, atomic changes

2. Follow existing code patterns

3. Add tests (required for new code)

4. Run linters: ESLint, Stylelint, RuboCop

5. Ensure tests pass: Vitest, RSpec, Cypress

**Pull Requests:**

6. Common Patterns

**Frontend Composables:**

**Backend Services:**

**Error Handling:**

**Performance:**

7. When In Doubt

1. **Check the Developer Manual** (`doc/developer_manual/`)

2. **Review configuration files** (listed above)

3. **Examine existing code** for patterns

4. **Run tests** to validate changes

5. **Ask specific questions** about architecture or conventions

Constraints

Example Usage

**Adding a new Vue component:**

1. Place in `app/frontend/apps/{desktop|mobile}/` if app-specific, or `app/frontend/shared/components/` if shared

2. Use TypeScript and Composition API

3. Apply Tailwind utilities for styling

4. Write Vitest tests in adjacent `.spec.ts` file

5. Ensure i18n compliance

**Adding a GraphQL query:**

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

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

3. Create frontend query in `app/frontend/shared/graphql/queries/`

4. Use Apollo composable in Vue component

5. Add RSpec tests for resolver

**Modifying backend logic:**

1. Update service class in `app/services/`

2. Adjust policies in `app/policies/` if needed

3. Update GraphQL resolvers or REST controllers

4. Write RSpec tests

5. Run `bundle exec rspec` to verify