docs/overview/directory-structure.md
This page documents the directory structure of the Zulip server and web app project. You may also find the new application feature tutorial helpful for understanding the flow through these files.
Zulip uses the Django web framework, so a lot of these paths will be familiar to Django developers.
zproject/urls.py Main
Django routes file.
Defines which URLs are handled by which view functions or templates.
zerver/models/*.py
Django models
files. Defines Zulip's database tables.
zerver/lib/*.py Most library code.
zerver/actions/*.py Most code doing writes to user-facing
database tables lives here. In particular, we have a policy that
all code calling send_event_on_commit to trigger pushing data to
clients must live here.
zerver/views/*.py Most Django views.
zerver/webhooks/ Webhook views and tests for Zulip's incoming webhook integrations.
zerver/tornado/views.py Tornado views.
zerver/worker/ Queue workers.
zerver/lib/markdown/ Backend Markdown processor.
zproject/backends.py Authentication backends.
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 templates/zerver/app).
web/templates/ Handlebars templates for the frontend.
web/src/ Zulip's own JavaScript and TypeScript sources.
web/styles/ Zulip's own CSS.
web/images/ Images bundled with webpack.
static/images/ Images served directly to the web.
web/third/ Third-party JavaScript and CSS that has been vendored.
node_modules/ Third-party JavaScript installed via pnpm.
web/icons/ Icons placed in this directory are compiled
into an icon font.
zerver/tests/ Backend tests.
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., restart-server).
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/setup/ Subdirectory of tools/ for things only used during
the development environment setup process.
tools/ci/ Subdirectory of tools/ for things only used to
set up and run our tests in CI. Actual test suites should
go in tools/.
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/integrations/ (within templates/zerver/, above).
Documentation for these integrations.
This is used to deploy essentially all configuration in production.
puppet/zulip/ For configuration for production deployments.
puppet/zulip/manifests/profile/standalone.pp Main manifest for Zulip standalone deployments.
confirmation Email confirmation system.
analytics Analytics for the Zulip server administrator (needs work to
be useful to normal Zulip sites).
corporate The old Zulip.com website. Not included in production
distribution.
zilencer Primarily used to hold management commands that aren't
used in production. Not included in production distribution.
zproject/jinja2/__init__.py Jinja2 environment.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 tools/build-release-tarball).