Zammad Codebase Guide
This skill helps you navigate and contribute to Zammad, an open-source helpdesk/customer support platform built with Ruby on Rails and modern Vue 3 frontends.
What This Skill Does
Provides you with a comprehensive mental model of the Zammad codebase structure, tech stack, coding standards, and workflow practices to enable efficient contributions with minimal trial-and-error.
Project Overview
Zammad is a web-based open-source helpdesk/customer support system consisting of:
**Backend**: Ruby on Rails with PostgreSQL, Redis, ActionCable, GraphQL**Legacy desktop-app**: CoffeeScript, Spine.js MVC framework, REST API (in `app/assets/`)**New desktop-view**: Vue 3, TypeScript, GraphQL (in `app/frontend/apps/desktop`)**New mobile**: Vue 3, TypeScript, GraphQL (in `app/frontend/apps/mobile`)Tech Stack Reference
Backend
Ruby on RailsPostgreSQL databaseRedis for caching/background jobsActionCable for WebSocketsDelayed Job for background processingGraphQL API (in `app/graphql/`)Legacy Desktop App (`app/assets/`)
CoffeeScriptSpine.js MVC frameworkSprockets asset pipelineREST API communicationQUnit for testingConfigured via `coffeelint.json`Modern Vue Apps (`app/frontend/apps/`)
Vue 3 with Composition APITypeScriptPinia for state managementApollo Client for GraphQLTailwind CSS for stylingVueUse utilitiesVitest + Testing Library for unit/component testsCypress for E2E testspnpm package managervite-plugin-ruby for Rails integrationESLint, Stylelint, Prettier for code qualityDirectory Structure
Key Locations
**Frontend:**
`app/assets/` - Legacy desktop-app (CoffeeScript/Sprockets)`app/frontend/apps/desktop` - New Vue desktop application`app/frontend/apps/mobile` - New Vue mobile application`app/frontend/shared/` - Shared code (components, utils, stores, GraphQL, i18n)`app/frontend/tests/` - Vitest setup and test helpers**Rails Backend:**
`app/controllers/` - HTTP request handlers`app/models/` - Database models and business logic`app/views/` - View templates`app/jobs/` - Background job definitions`app/mailers/` - Email handling`app/helpers/` - View helpers`app/channels/` - ActionCable channels`app/policies/` - Authorization policies`app/services/` - Business logic modules (custom convention)`app/graphql/` - GraphQL schema, types, and resolvers**Library Code (`lib/` directory):**
Helpers and utilities (email, migration, SQL, image, time range, session, notifications)External integrations (GitHub, GitLab, Microsoft Graph, Facebook, Telegram, WhatsApp)Business features (auto wizard, bulk import, calendar, escalation, Excel, knowledge base, password policy, secure mailing, stats, tasks)Core extensions (`core_ext/`)Background services and operationsVersion and exception handling**Other Important Directories:**
`bin/` - Executable scripts`config/` - Application configuration`db/` - Database schema and migrations`doc/developer_manual/` - **Authoritative developer documentation**`script/` - Utility scripts`spec/` - RSpec tests`test/` - Legacy tests (QUnit)Configuration Files Reference
**Always consult these files for authoritative information:**
`doc/developer_manual/index.md` - Main developer documentation index`package.json` - Node dependencies and scripts`Gemfile` - Ruby dependencies`config/database.yml` - Database configuration`Procfile.dev` - Development process definitions`vite.config.mjs` - Vite build configuration`tsconfig.base.json` - TypeScript configuration and path aliases`eslint.config.ts` - Linting rules (includes copyright/i18n rules)`.oxlintrc.json` - Additional linting configuration`coffeelint.json` - Legacy CoffeeScript lintingCoding Guidelines
General Principles
1. **Reference, don't duplicate** - Always point to config files and documentation rather than repeating information
2. **Focused changes** - Keep pull requests small and targeted
3. **Test coverage** - Include tests for all new code
4. **Documentation** - The Developer Manual (`doc/developer_manual/`) is the source of truth
Legacy Desktop App
**Location**: `app/assets/javascripts` and `app/assets/stylesheets`**Framework**: Spine.js MVC classes**API**: REST endpoints (check Rails controllers for routes)**Testing**: QUnit tests in `test/`**Linting**: Follow `coffeelint.json` rules**Strategy**: Prefer new work in modern Vue apps; keep legacy changes minimalModern Vue Apps
1. **Path aliases** - Use TypeScript path aliases from `tsconfig.base.json`
2. **App boundaries** - Do NOT cross-import between desktop/mobile apps (ESLint enforces this)
3. **Shared code** - Place reusable code in `app/frontend/shared/`
4. **Testing** - Use Vitest + Testing Library (see `app/frontend/tests/`)
5. **Styling** - Use Tailwind CSS utility classes; lint with Stylelint
6. **i18n** - Wrap all user-facing strings; follow `eslint.config.ts` rules for internationalization
7. **Formatting** - Prettier handles code formatting automatically
GraphQL
Schema definitions in `app/graphql/`Apollo Client in frontend appsFollow existing resolver patternsDevelopment Workflow
Setup and Environment
1. Consult `doc/developer_manual/` for setup instructions
2. Check `package.json` and `Gemfile` for tool versions
3. Review `Procfile.dev` for development processes
4. Use environment variables as documented in config files
Testing Strategy
**Backend**: RSpec tests in `spec/`**Legacy frontend**: QUnit tests in `test/`**Vue apps**: Vitest + Testing Library for unit/component tests**E2E**: Cypress for integration testsLinting and Code Quality
**JavaScript/TypeScript**: ESLint with `eslint.config.ts`**CoffeeScript**: Coffeelint with `coffeelint.json`**Styles**: Stylelint for CSS/SCSS**Formatting**: Prettier for consistent code styleWhen You Need Help
1. **Start here**: Developer Manual at `doc/developer_manual/index.md`
2. **Configuration questions**: Check relevant config files listed above
3. **Architecture questions**: Review directory structure and existing patterns
4. **Uncertain about approach**: Look for similar existing implementations in the codebase
Important Constraints
Do not cross-import between desktop and mobile Vue appsPrefer modern Vue apps for new features over legacy desktop-appAlways include tests with new codeFollow existing patterns for GraphQL schema and resolversRespect app boundaries enforced by ESLint rulesUse shared code appropriately in `app/frontend/shared/`Quick Reference: Where to Find Things
| Need | Location |
|------|----------|
| Setup instructions | `doc/developer_manual/` |
| TypeScript paths | `tsconfig.base.json` |
| Dependencies | `package.json`, `Gemfile` |
| Database schema | `db/schema.rb` |
| GraphQL schema | `app/graphql/` |
| Shared Vue code | `app/frontend/shared/` |
| Desktop Vue app | `app/frontend/apps/desktop` |
| Mobile Vue app | `app/frontend/apps/mobile` |
| Legacy app | `app/assets/` |
| Business logic | `app/services/`, `lib/` |
| Test helpers | `app/frontend/tests/`, `spec/` |