Zammad Development Assistant
Expert assistant for developing and maintaining Zammad, an open-source helpdesk/customer support platform.
What This Skill Does
Provides specialized guidance for working with Zammad's codebase, which includes a Ruby on Rails backend, a legacy CoffeeScript/Sprockets desktop-app, and two modern Vue 3 frontends (desktop-view and mobile) powered by GraphQL.
Project Context
**Zammad** is a web-based open-source helpdesk/customer support system with:
Ruby on Rails backend with PostgreSQL, Redis, GraphQLLegacy desktop-app using CoffeeScript, Spine.js, REST APIModern desktop-view and mobile apps using Vue 3, TypeScript, GraphQLInstructions
1. Understand the Architecture
**Three Frontend Applications:**
`app/assets/` — Legacy desktop-app (CoffeeScript, Spine.js, Sprockets, REST API)`app/frontend/apps/desktop` — New desktop-view (Vue 3, TypeScript, GraphQL)`app/frontend/apps/mobile` — Mobile app (Vue 3, TypeScript, GraphQL)**Shared Resources:**
`app/frontend/shared/` — Cross-app components, utils, stores, GraphQL schemas, i18n**Backend Structure (Rails standard):**
`app/controllers/`, `app/models/`, `app/views/``app/jobs/`, `app/mailers/`, `app/helpers/`, `app/channels/`, `app/policies/``app/services/` — Business logic modules`app/graphql/` — GraphQL API definitions and resolvers`lib/` — Core extensions, helpers, integrations (GitHub, GitLab, Microsoft Graph, etc.), business logic modules2. Reference Configuration Files
Always consult these files for authoritative runtime and environment details:
`doc/developer_manual/` (index: `doc/developer_manual/index.md`) — Source of truth for setup, testing, standards`package.json`, `Gemfile`, `config/database.yml``Procfile.dev`, `vite.config.mjs`, `tsconfig.base.json``eslint.config.ts`, `coffeelint.json`3. Tech Stack Reference
**Legacy Desktop-App:**
CoffeeScript, Spine.js (MVC framework), SprocketsREST API endpointsQUnit tests in `test/`Linting: `coffeelint.json`**Modern Vue Apps (desktop-view + mobile):**
Vue 3, TypeScript, Pinia (state), Apollo Client (GraphQL)Tailwind CSS, VueUseTesting: Vitest, Testing Library, CypressBuild: pnpm, vite-plugin-ruby, vite-plugin-pwaLinting: ESLint, Stylelint, Prettier**Backend:**
Ruby on Rails, PostgreSQL, RedisActionCable, Delayed Job, GraphQL4. Development Guidelines
**For Legacy Desktop-App:**
Location: `app/assets/javascripts` and `app/assets/stylesheets`Uses Spine.js for MVC structure (most modules are Spine classes)Uses REST API (see Rails controllers for routes)Keep changes minimal; prefer new work in modern Vue apps**For Vue Apps:**
Use path aliases from `tsconfig.base.json`DO NOT cross-import between desktop/mobile apps (ESLint enforces boundaries)Use shared modules from `app/frontend/shared/`Unit/component tests: Vitest + Testing Library in `app/frontend/tests/`Styling: Tailwind CSS utilities, linted with Stylelint and Prettieri18n: Wrap all user-facing strings (see `eslint.config.ts` for rules)**General Coding Standards:**
Consult Developer Manual (`doc/developer_manual/`) for setup, troubleshooting, testing, lintingCheck `package.json`, `Gemfile`, and config files for tool versions and environment variablesKeep PRs focused; include tests for new codePrefer config file references over assumptions5. Key Directories to Know
**lib/ Directory Contains:**
Helpers/utilities: `email_helper.rb`, `migration_helper.rb`, `sql_helper.rb`, `image_helper.rb`, etc.Integrations: `github/`, `gitlab/`, `microsoft_graph/`, `facebook.rb`, `telegram_helper.rb`, `whatsapp/`Business logic: `auto_wizard.rb`, `calendar_subscriptions/`, `escalation/`, `knowledge_base/`, `password_policy/`, `secure_mailing/`, etc.Core extensions: `core_ext/`Background services: `background_services/`, `operations_rate_limiter.rb`, `sequencer/`, `transaction_dispatcher.rb`6. When Making Changes
1. **Identify the correct layer:**
- Backend logic? → Rails controllers/models/services/GraphQL
- Legacy UI? → `app/assets/` (minimize changes)
- Modern UI? → `app/frontend/apps/desktop` or `app/frontend/apps/mobile`
- Shared frontend code? → `app/frontend/shared/`
2. **Check documentation first:**
- Always reference `doc/developer_manual/` for standards
- Review relevant config files for constraints
3. **Follow testing requirements:**
- Legacy: QUnit tests in `test/`
- Vue apps: Vitest/Testing Library tests
- Backend: RSpec tests in `spec/`
4. **Respect architectural boundaries:**
- No cross-imports between desktop/mobile apps
- Use shared modules for cross-app code
- Follow path aliases from `tsconfig.base.json`
5. **Maintain code quality:**
- Run linters (ESLint, Stylelint, CoffeeLint, Prettier)
- Add i18n wrappers for user-facing text
- Include copyright headers per `eslint.config.ts`
Examples
**Example 1: Adding a new GraphQL query**
Define schema in `app/graphql/`Add resolver logicUpdate Vue app to use Apollo Client queryAdd Vitest tests for frontend componentAdd RSpec tests for backend resolver**Example 2: Fixing a bug in legacy desktop-app**
Locate CoffeeScript file in `app/assets/javascripts/`Apply minimal fix following Spine.js patternsAdd/update QUnit test in `test/`Consider if modern Vue apps need similar fix**Example 3: Creating shared Vue component**
Add component to `app/frontend/shared/components/`Use TypeScript, Tailwind CSSWrite Vitest tests in `app/frontend/tests/`Ensure i18n strings are wrappedDocument in component commentsConstraints
Prefer new development in modern Vue apps over legacy desktop-appNever cross-import between desktop and mobile Vue appsAlways consult Developer Manual for authoritative guidanceReference config files for runtime/environment constraintsInclude tests with all new codeFollow established patterns in each layer (Rails, Vue, CoffeeScript)