This page documents the Zulip directory structure, where to find things, and how to decide where to put a file.
You may also find the new application feature tutorial helpful for understanding the flow through these files.
Core Python files
Zulip uses the Django web framework, so a lot of these paths will be familiar to Django developers.
zproject/urls.pyMain Django routes file. Defines which URLs are handled by which view functions or templates.
zerver/models.pyMain Django models file. Defines Zulip’s database tables.
zerver/lib/*.pyMost library code.
zerver/actions/*.pyMost code doing writes to user-facing database tables lives here. In particular, we have a policy that all code calling
send_eventto trigger pushing data to clients must live here.
zerver/views/*.pyMost Django views.
zerver/webhooks/Webhook views and tests for Zulip’s incoming webhook integrations.
zerver/lib/markdown/Backend Markdown processor.
See our docs for details on Zulip’s templating systems.
templates/zerver/For Jinja2 templates for the backend (for zerver app; logged-in content is in
web/templates/Handlebars templates for the frontend.
web/styles/Zulip’s own CSS.
web/images/Images bundled with webpack.
static/images/Images served directly to the web.
web/shared/icons/Icons placed in this directory are compiled into an icon font.
web/tests/Node Frontend unit tests.
web/e2e-tests/Puppeteer frontend integration tests.
tools/test-*Developer-facing test runner scripts.
These are distinguished from scripts, below, by needing to run a Django context (i.e. with database access).
zerver/management/commands/Management commands one might run at a production deployment site (e.g. scripts to change a value or deactivate a user properly).
zilencer/management/commands/includes some dev-specific commands such as
populate_db, which are not included in the production distribution.
scripts/Scripts that production deployments might run manually (e.g.,
scripts/lib/Scripts that are needed on production deployments but humans should never run directly.
scripts/setup/Scripts that production deployments will only run once, during installation.
tools/Scripts used only in a Zulip development environment. These are not included in production release tarballs for Zulip, so that we can include scripts here one wouldn’t want someone to run in production accidentally (e.g. things that delete the Zulip database without prompting).
tools/for things only used during the development environment setup process.
tools/for things only used to set up and run our tests in CI. Actual test suites should go in
API and bots
See the Zulip API repository. Zulip’s Python API bindings, a number of Zulip integrations and bots, and a framework for running and testing Zulip bots, used to be developed in the main Zulip server repo but are now in their own repo.
templates/zerver/, above). Documentation for these integrations.
Production Puppet configuration
This is used to deploy essentially all configuration in production.
puppet/zulip/For configuration for production deployments.
puppet/zulip/manifests/profile/standalone.ppMain manifest for Zulip standalone deployments.
Additional Django apps
confirmationEmail confirmation system.
analyticsAnalytics for the Zulip server administrator (needs work to be useful to normal Zulip sites).
corporateThe old Zulip.com website. Not included in production distribution.
zilencerPrimarily used to hold management commands that aren’t used in production. Not included in production distribution.
Jinja2 compatibility files
locale/Backend (Django) and frontend translation data files.
docs/Source for this documentation.
You can consult the repository’s
.gitattributes file to see exactly
which components are excluded from production releases (release
tarballs are generated using