# zulip/zulip-desktop architecture

> Architecture diagram of the GitHub repository zulip/zulip-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zulip/zulip-desktop
- Repository: https://github.com/zulip/zulip-desktop

## Overview

##### Project Type and Purpose
- This is an Electron-based desktop client for accessing Zulip (a chat platform) on Windows, Linux, and Mac.
- Its key features include supporting multiple organizations, handling desktop notifications with inline replies, tray/dock integration, multi-language support via translations, and automatic updates.
- The project shares much of its code with the Zulip web app, implying a close tie with web-based functionalities, but wrapped as a desktop client.

##### Main Architectural Components (from the file tree)
- Main Process (located in app/main): This is the entry point and backbone handling auto-updates, menu creation, external links, notifications, error monitoring (see sentry.ts), and OS-level integrations (e.g., tray/dock).
- Renderer Process (located in app/renderer): This part handles the user interface. It includes HTML files, CSS, and JavaScript components (organized into pages, components, utilities) that render the desktop UI.
- Common / Shared Utilities (located in app/common): Contains configuration utilities, logging, internationalization (translation utility), and helper functions that are used by both the main and renderer processes.
- IPC Mechanisms: The project employs strongly typed IPC (see the typed-ipc files in both main and renderer directories) for communication between the main and renderer processes.
- External Resources and Configurations: The “public” folder provides translations and media resources (sounds, images) while packaging and build directories handle OS-specific build scripts and installers.

##### Relationships and Interactions
- The Main Process initializes and manages the lifecycle of the application, sets up event listeners, handles auto-updates, and communicates with the Renderer Process using IPC.
- The Renderer Process is responsible for rendering HTML pages, handling user interactions, and invoking the main process actions as needed.
- Shared libraries and common utilities are used by both processes for tasks like logging, configuration, and error handling.
- External dependencies such as Sentry for error tracking or auto-updaters are integrated within the main process.
- The translation files (under public/translations) are loaded by the renderer to support multi-language functionality.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division between the Main and Renderer processes to distinctively handle OS-level operations versus UI rendering.
- Modular Design: Code is organized into thematic directories (common, main, renderer) promoting reusability and maintainability.
- IPC-based Communication: The use of typed IPC channels ensures strict and reliable inter-process communication.
- External Integration: The design includes hooks for auto-updating and desktop notifications, showing a blend of local and external service integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Main Process Subgraph
    subgraph "Electron Main Process"
        M1("Entry Point (index.ts)"):::processDetails
        M2("Auto-Updater (autoupdater.ts)"):::processDetails
        M3("Application Menu (menu.ts)"):::processDetails
        M4("Sentry Error Tracking (sentry.ts)"):::processDetails
        M5("External Link Handling (handle-external-link.ts)"):::processDetails
        M_IPC("Typed IPC (typed-ipc-main.ts)"):::ipc
    end

    %% Electron Renderer Process Subgraph
    subgraph "Electron Renderer Process"
        R1("Main HTML (main.html)"):::ui
        R2("Network View (network.html)"):::ui
        R3("Preference View (preference.html)"):::ui
        R4("Renderer JS (main.ts)"):::ui
        R5("Tray Integration (tray.ts)"):::ui
        R_IPC("Typed IPC (typed-ipc-renderer.ts)"):::ipc
    end

    %% Common / Shared Utilities Subgraph
    subgraph "Common / Shared Utilities"
        C1("Config Utility (config-util.ts)"):::common
        C2("Logger Utility (logger-util.ts)"):::common
        C3("Translation Utility (translation-util.ts)"):::common
        C4("Typed IPC Shared (typed-ipc.ts)"):::common
    end

    %% External Resources Subgraph
    subgraph "External Resources"
        E1("Translations & Media (public/translations)"):::external
        E2("Documentation (README.md)"):::external
    end

    %% External Services Subgraph
    subgraph "External Services"
        ES1("Sentry Service"):::externalService
        ES2("Auto-Updater Service"):::externalService
        ES3("Zulip Web API"):::externalService
    end

    %% Relationships & Data Flow

    %% IPC Communication between Renderer and Main
    R_IPC -->|"IPC_Request"| M_IPC
    M_IPC -->|"IPC_Response"| R_IPC

    %% Main Process interactions with Renderer Process and Common Utilities
    M1 -->|"Initializes"| R1
    M1 -->|"Uses"| C1
    M1 -->|"Uses"| C2
    M1 -->|"Uses"| C3

    %% Renderer Process interactions with Common Utilities and External Resources
    R1 -->|"Loads"| E1
    R1 -->|"Uses"| C3
    R1 -->|"Uses"| C4
    R4 -->|"Uses"| C4

    %% Main Process external integrations
    M4 -->|"Reports_to"| ES1
    M2 -->|"Checks_updates_with"| ES2

    %% Renderer Process external integration with Zulip Web API
    R1 -->|"Communicates_with"| ES3

    %% Styling Definitions
    classDef processDetails fill:#f9f,stroke:#333,stroke-width:2px,color:#000;
    classDef ui fill:#9f9,stroke:#333,stroke-width:2px,color:#000;
    classDef ipc fill:#ff9,stroke:#333,stroke-width:2px,color:#000;
    classDef common fill:#9ff,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#f99,stroke:#333,stroke-width:2px,color:#000;
    classDef externalService fill:#fc9,stroke:#333,stroke-width:2px,color:#000;

    %% Click Events for Main Process Components
    click M1 "https://github.com/zulip/zulip-desktop/blob/main/app/main/index.ts"
    click M2 "https://github.com/zulip/zulip-desktop/blob/main/app/main/autoupdater.ts"
    click M3 "https://github.com/zulip/zulip-desktop/blob/main/app/main/menu.ts"
    click M4 "https://github.com/zulip/zulip-desktop/blob/main/app/main/sentry.ts"
    click M5 "https://github.com/zulip/zulip-desktop/blob/main/app/main/handle-external-link.ts"
    click M_IPC "https://github.com/zulip/zulip-desktop/blob/main/app/main/typed-ipc-main.ts"

    %% Click Events for Renderer Process Components
    click R1 "https://github.com/zulip/zulip-desktop/blob/main/app/renderer/main.html"
    click R2 "https://github.com/zulip/zulip-desktop/blob/main/app/renderer/network.html"
    click R3 "https://github.com/zulip/zulip-desktop/blob/main/app/renderer/preference.html"
    click R4 "https://github.com/zulip/zulip-desktop/blob/main/app/renderer/js/main.ts"
    click R5 "https://github.com/zulip/zulip-desktop/blob/main/app/renderer/js/tray.ts"
    click R_IPC "https://github.com/zulip/zulip-desktop/blob/main/app/renderer/js/typed-ipc-renderer.ts"

    %% Click Events for Common Utilities
    click C1 "https://github.com/zulip/zulip-desktop/blob/main/app/common/config-util.ts"
    click C2 "https://github.com/zulip/zulip-desktop/blob/main/app/common/logger-util.ts"
    click C3 "https://github.com/zulip/zulip-desktop/blob/main/app/common/translation-util.ts"
    click C4 "https://github.com/zulip/zulip-desktop/blob/main/app/common/typed-ipc.ts"

    %% Click Events for External Resources
    click E1 "https://github.com/zulip/zulip-desktop/tree/main/public/translations"
    click E2 "https://github.com/zulip/zulip-desktop/blob/main/public/README.md"
```
