Zammad Development Assistant
This skill helps you contribute to Zammad, an open-source helpdesk/customer support platform built with Ruby on Rails and modern Vue 3 frontends.
What Zammad Is
Zammad is a web-based open-source helpdesk/customer support system with:
Rails backend with PostgreSQL, Redis, ActionCable, Delayed Job, GraphQLLegacy desktop-app (`app/assets/`) using CoffeeScript, Spine.js, Sprockets, REST APIModern desktop-view (`app/frontend/apps/desktop`) using Vue 3, TypeScript, GraphQLModern mobile app (`app/frontend/apps/mobile`) using Vue 3, TypeScript, GraphQLProject Structure
**Frontend:**
`app/assets/` - Legacy desktop-app (CoffeeScript/Sprockets)`app/frontend/apps/desktop` - New Vue desktop UI`app/frontend/apps/mobile` - New Vue mobile UI`app/frontend/shared/` - Cross-app modules (components, utils, stores, GraphQL, i18n)`app/frontend/tests/` - Vitest setup and helpers**Backend (Rails standard):**
`app/controllers/` - HTTP controllers`app/models/` - ActiveRecord models`app/graphql/` - GraphQL API definitions and resolvers`app/services/` - Business logic modules`app/jobs/` - Background jobs`app/channels/` - ActionCable channels`app/policies/` - Authorization policies`lib/` - Core extensions, helpers, integrations (GitHub, GitLab, Microsoft Graph, Telegram, WhatsApp, etc.)**Configuration & Docs:**
`doc/developer_manual/` - Authoritative setup, testing, and coding standards`config/` - Rails configuration`db/` - Database migrations and seeds`spec/`, `test/` - Test suitesTech Stack Details
**Legacy desktop-app:**
CoffeeScript, Spine.js MVC framework, Sprockets, REST APILinting: `coffeelint.json`Testing: QUnit in `test/`**Modern Vue apps (desktop-view & mobile):**
Vue 3, TypeScript, Pinia (state), Apollo Client (GraphQL), Tailwind CSS, VueUseTesting: Vitest, Testing Library, CypressBuild: Vite (vite-plugin-ruby, vite-plugin-pwa), pnpmLinting: ESLint, Stylelint, Prettier**Backend:**
Ruby on Rails, PostgreSQL, Redis, ActionCable, Delayed Job, GraphQLSee `Gemfile`, `config/database.yml`, `Procfile.dev`Step-by-Step Instructions
1. Understand the Codebase
**First, consult the Developer Manual:** `doc/developer_manual/index.md` is the authoritative source for setup, testing, and standards**Check config files for runtime details:** `package.json`, `Gemfile`, `config/database.yml`, `Procfile.dev`, `vite.config.mjs`, `tsconfig.base.json`, `eslint.config.ts`**Identify which app you're working in:** - Legacy desktop-app? → `app/assets/`
- New desktop UI? → `app/frontend/apps/desktop`
- Mobile UI? → `app/frontend/apps/mobile`
- Shared code? → `app/frontend/shared/`
- Backend? → Rails standard folders + `lib/`
2. Working with the Legacy Desktop-App
Located in `app/assets/javascripts` and `app/assets/stylesheets`Uses Spine.js for MVC structure (most modules are Spine classes)Communicates via REST API endpoints (see Rails controllers)Lint with `coffeelint.json`, test with QUnit in `test/`**Prefer new work in desktop-view/mobile** - keep legacy changes minimal3. Working with Vue Apps
**Use path aliases** from `tsconfig.base.json` (e.g., `@shared`, `@mobile`, `@desktop`)**Do NOT cross-import** between desktop/mobile apps (ESLint enforces boundaries)**Shared code goes in** `app/frontend/shared/`**Use Tailwind CSS utilities** for styling**Wrap user-facing strings** for i18n (see `eslint.config.ts` for rules)**Write tests** with Vitest and Testing Library (`app/frontend/tests/`)4. Working with the Backend
Follow Rails conventions for controllers, models, views**Business logic** → `app/services/`**GraphQL** → `app/graphql/` (types, resolvers, mutations, queries)**Integrations & core extensions** → `lib/` (GitHub, GitLab, Microsoft Graph, Telegram, WhatsApp, helpers, etc.)**Background jobs** → `app/jobs/`**Tests** → RSpec in `spec/`5. Development Workflow
**Always reference config files** for tool versions and environment setup**Run linters and tests** before submitting PRs (see Developer Manual for commands)**Keep PRs focused** on a single feature or fix**Include tests** for new code (unit, component, or integration as appropriate)**Consult the Developer Manual** for setup, troubleshooting, testing, and coding standards6. Common Tasks
**Add a new Vue component:**
Place in `app/frontend/apps/[desktop|mobile]/components/` or `app/frontend/shared/components/`Use TypeScript, Tailwind CSS, and Pinia for stateWrite tests in adjacent `__tests__` folder**Add a GraphQL query/mutation:**
Define type in `app/graphql/types/`Add resolver in `app/graphql/resolvers/`Use in Vue apps via Apollo Client**Add a REST endpoint (legacy):**
Add route in `config/routes.rb`Create controller action in `app/controllers/`Use in legacy desktop-app via AJAX**Add backend business logic:**
Create service class in `app/services/`Call from controller or jobWrite RSpec tests in `spec/services/`**Add an integration (external API):**
Create module in `lib/[service_name]/`Add helper methods and API client logicDocument usage and write testsImportant Constraints
**Do not cross-import between desktop and mobile apps** - ESLint will enforce boundaries**Always consult `doc/developer_manual/` for authoritative setup and standards****Prefer new work in desktop-view/mobile** - legacy app is maintenance mode**All runtime constraints are in config files** - refer to them, don't duplicate here**Follow i18n rules** - wrap user-facing strings (see `eslint.config.ts`)When in Doubt
1. Check the Developer Manual (`doc/developer_manual/index.md`)
2. Review relevant config files (`package.json`, `Gemfile`, `vite.config.mjs`, etc.)
3. Look at existing code in the same area for patterns
4. Keep changes focused and include tests