Zammad Helpdesk Development
Expert guide for contributing to Zammad, an open-source web-based helpdesk and customer support system.
What This Skill Does
Provides comprehensive context for AI agents working on the Zammad codebase, including architecture overview, tech stack details, project structure, coding standards, and development workflows. Helps developers quickly understand the dual-frontend architecture (legacy + modern Vue apps) and make effective contributions.
System Architecture
Zammad consists of three frontend applications sharing a Rails backend:
1. **Legacy desktop-app** (`app/assets/`): CoffeeScript/Sprockets UI using Spine.js MVC framework with REST API
2. **Modern desktop-view** (`app/frontend/apps/desktop`): Vue 3 + TypeScript + GraphQL
3. **Modern mobile** (`app/frontend/apps/mobile`): Vue 3 + TypeScript + GraphQL
Tech Stack
Backend
Ruby on RailsPostgreSQL databaseRedis for cachingActionCable for WebSocketsDelayed Job for background processingGraphQL API (new apps)REST API (legacy app)Modern Frontend (desktop-view & mobile)
Vue 3 with Composition APITypeScriptPinia for state managementApollo Client for GraphQLTailwind CSS for stylingVueUse composablesVite for bundling (via vite-plugin-ruby)Vitest + Testing Library for unit testsCypress for E2E testsESLint, Stylelint, Prettier for code qualitypnpm for package managementLegacy Frontend (desktop-app)
CoffeeScriptSpine.js MVC frameworkSprockets asset pipelineREST APIQUnit for testingCoffeeLint for lintingProject Structure
Key Directories
**Frontend:**
`app/assets/` - Legacy CoffeeScript desktop app`app/frontend/` - Modern Vue frontends - `apps/desktop/` - Desktop Vue app
- `apps/mobile/` - Mobile Vue app
- `shared/` - Cross-app components, utils, stores, GraphQL, i18n
- `tests/` - Vitest setup and test helpers
**Backend (Rails standard):**
`app/controllers/` - Request handlers`app/models/` - Data models`app/views/` - View templates`app/jobs/` - Background jobs`app/mailers/` - Email handling`app/helpers/` - View helpers`app/channels/` - ActionCable channels`app/policies/` - Authorization policies`app/services/` - Business logic modules`app/graphql/` - GraphQL schema and resolvers**Library Code:**
`lib/` - Core extensions, helpers, integrations, business logic - Helpers: `email_helper.rb`, `migration_helper.rb`, `sql_helper.rb`, etc.
- Integrations: `github/`, `gitlab/`, `microsoft_graph/`, `facebook.rb`, `telegram_helper.rb`, `whatsapp/`
- Features: `auto_wizard.rb`, `knowledge_base/`, `password_policy/`, `secure_mailing/`, `stats/`, etc.
- Extensions: `core_ext/` for Ruby/Rails patches
- Background: `background_services/`, `transaction_dispatcher.rb`, `sequencer/`
**Configuration & Documentation:**
`config/` - Rails configuration files`doc/developer_manual/` - **Authoritative development documentation**`db/` - Database migrations and schema`spec/` - RSpec tests`test/` - QUnit tests (legacy)`bin/` - Executable scripts`script/` - Utility scriptsConfiguration Files Reference
**Always check these for authoritative details:**
`package.json` - Node dependencies and scripts`Gemfile` - Ruby dependencies`config/database.yml` - Database configuration`Procfile.dev` - Development server processes`vite.config.mjs` - Frontend build configuration`tsconfig.base.json` - TypeScript path aliases and compiler options`eslint.config.ts` - Linting rules (includes copyright/i18n requirements)`.oxlintrc.json` - Additional linting configuration`coffeelint.json` - Legacy CoffeeScript lintingDevelopment Workflow
Step 1: Consult Documentation
**Before making changes, always refer to:**
`doc/developer_manual/` (start with `doc/developer_manual/index.md`)Relevant configuration files listed aboveStep 2: Choose the Right Frontend
**For new features:**
Prefer `desktop-view` or `mobile` apps (Vue 3)Only touch `desktop-app` for bug fixes or minor updates to existing legacy features**Architecture boundaries:**
Do NOT cross-import between desktop/mobile apps (ESLint enforces this)Shared code goes in `app/frontend/shared/`Step 3: Follow Coding Standards
**Vue Apps:**
Use TypeScript path aliases from `tsconfig.base.json` (e.g., `@shared/components`)Style with Tailwind CSS utilitiesWrap all user-facing strings for i18n (ESLint enforces this)Write unit tests with Vitest + Testing Library in `app/frontend/tests/`Run linters: ESLint, Stylelint, Prettier**Legacy App:**
Follow Spine.js MVC patternsUse CoffeeLint for code qualityWrite QUnit tests in `test/` directoryKeep changes minimal - prefer migrating features to Vue apps**Backend:**
Follow Rails conventionsBusiness logic goes in `app/services/` or `lib/`Write RSpec tests in `spec/`Use GraphQL for new API endpoints (legacy REST for compatibility)Step 4: Testing
**Frontend:**
Unit/component tests: Vitest + Testing LibraryE2E tests: CypressRun tests before submitting PRs**Backend:**
RSpec for model/controller/service testsInclude tests for all new codeStep 5: Code Review
Keep PRs focused on single features/fixesEnsure all tests passRun linters and formattersVerify i18n strings are properly wrappedCheck that copyright headers are present (ESLint enforces this)Common Tasks
Adding a New Vue Component
1. Determine if it's desktop-specific, mobile-specific, or shared
2. Place in appropriate directory (`apps/desktop/`, `apps/mobile/`, or `shared/`)
3. Use TypeScript and Composition API
4. Style with Tailwind utilities
5. Write unit tests
6. Ensure i18n compliance
Creating a GraphQL Endpoint
1. Define schema in `app/graphql/`
2. Implement resolver with authorization checks
3. Add to Apollo Client queries/mutations in `app/frontend/shared/graphql/`
4. Write backend tests in `spec/graphql/`
5. Write frontend tests for components using the endpoint
Modifying Legacy Code
1. Locate file in `app/assets/javascripts/`
2. Understand Spine.js patterns in use
3. Make minimal, focused changes
4. Update QUnit tests if present
5. Consider filing an issue to migrate the feature to Vue
Adding an Integration
1. Create module in `lib/` (e.g., `lib/new_service/`)
2. Implement API client and helpers
3. Add configuration options in `config/`
4. Write RSpec tests in `spec/lib/`
5. Document in Developer Manual
Key Constraints
**Do not duplicate environment/runtime info** - always reference config files**Respect app boundaries** - no cross-imports between desktop/mobile**Prefer modern stack** - use Vue apps for new work**Test everything** - no PRs without tests**Follow linting rules** - especially i18n and copyright headers**Consult Developer Manual** - it's the source of truth for setup, testing, and standardsWhen You're Stuck
1. Check `doc/developer_manual/` for setup and troubleshooting
2. Review relevant config files for environment details
3. Search `spec/` and `app/frontend/tests/` for similar test patterns
4. Look at recent commits for examples of similar changes
5. Check `lib/` for existing integrations and business logic modules
Important Reminders
Always wrap user-facing strings for i18n in Vue appsUse path aliases from `tsconfig.base.json` in TypeScript filesKeep legacy app changes minimal - prefer Vue migrationInclude copyright headers as enforced by ESLintRun all linters before committingWrite tests for every new feature or bug fixFocus PRs on single, well-defined changes