# rocketchat/rocket.chat.apps-engine architecture

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

- Interactive diagram: https://gitdiagram.com/rocketchat/rocket.chat.apps-engine
- Repository: https://github.com/rocketchat/rocket.chat.apps-engine

## Overview

##### Main Components
- Definition Layer (src/definition): Contains all the TypeScript interfaces, classes, enums, and types that define the contracts for apps. This layer includes APIs for events, accessors, handlers, settings, messages, and more. It forms the backbone of how apps declare their integrations.
- Client Module (src/client): Manages the client-side interactions including UI-specific logic, communications, and event dispatching. This might include the AppClientManager, UI host, and associated utilities.
- Server Module (src/server): This is the heart of the engine. It is subdivided into several submodules:
– Accessors (src/server/accessors): These provide APIs for apps to interact with Rocket.Chat functionalities such as messages, rooms, livechat, HTTP, and more.
– Bridges (src/server/bridges): These modules serve as integration points between the Apps-Engine and the Rocket.Chat core. They abstract away direct dependencies and permit things like app activation, API calls, messaging, and environment bridging.
– Managers (src/server/managers): Responsible for orchestrating app lifecycle tasks. They include managers for app licensing, settings, permissions, runtime, and event listeners.
– Compiler (src/server/compiler): Responsible for compiling and packaging apps so that they integrate consistently with Rocket.Chat.
– Runtime (src/server/runtime): Contains the core execution logic. Note the further distinction with a dedicated “deno” branch (src/server/runtime/deno) and a separate “deno-runtime” folder, which provide alternative runtime environments (in this case for Deno) and include their own event handlers and support utilities.
– Storage and Logging (src/server/storage and src/server/logging): Handle persisting app metadata, logs, and various storage aspects for apps within the engine.
- Deno Runtime (deno-runtime): Although separate from the main “src” folder, this directory represents the support for running the Apps-Engine under Deno. It includes its own handler implementations, type declarations, and configuration files.

##### Relationships and Data Flow
- Separation between the client and server components. For instance, the client-side components (UI management, AppServerCommunicator) communicate with the server, which then delegates tasks to the appropriate managers, accessors, or runtime modules.
- How external Rocket.Chat events (e.g., message events, room events) are received (via Bridges) and then processed by Managers that coordinate with the Accessors to push these events to the apps through the defined pre- and post-handlers. Emphasize the ordered chain:
– PreEventPrevent → PreEventExtend → PreEventModify → PostEvent.
- How the Compiler and Runtime components work together to accept a packaged app, validate, and compile it so that it’s ready for execution.
- Make it clear that the Definition layer serves as the central contract that both client and server must adhere to.

##### Additional Elements
- Testing and documentation flows if needed (indicate that a well-integrated testing framework using TypeScript & decorators is in use).
- If space permits, briefly mention the integration with the Rocket.Chat core (as described in the README for development setup) to emphasize that this engine plugs directly into Rocket.Chat’s broader system.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Events
    EX["External Rocket.Chat Events"]:::external

    %% API/Definition Layer
    subgraph "API/Definition Layer"
        DEF["Definition Contracts (Interfaces, Types)"]:::api
    end

    %% Client Layer
    subgraph "Client Layer"
        C1["App Client Manager"]:::client
        C2["App Server Communicator"]:::client
    end

    %% Server Core Engine
    subgraph "Server Core Engine"
        S1["Accessors: Rocket.Chat APIs"]:::server
        S2["Bridges: Integration with Rocket.Chat Core"]:::server
        S3["Managers: App Lifecycle & Event Handlers (PreEventPrevent->PreEventExtend->PreEventModify->PostEvent)"]:::server
        S4["Compiler: App Packaging & Validation"]:::server
        S5["Runtime: Core Execution Logic"]:::server
        S6["Storage: App Metadata Storage"]:::server
        S7["Logging: Logging Services"]:::server
    end

    %% Deno Runtime Environment
    subgraph "Deno Runtime Environment"
        D1["Deno Runtime: Alternative Execution (runtime/deno)"]:::deno
        D2["Standalone Deno Runtime"]:::deno
    end

    %% Flow Connections
    EX -->|"triggers"| S2
    C1 -->|"communicates"| S2
    C2 -->|"communicates"| S2

    S2 -->|"processes"| S3
    S3 -->|"invokes"| S1
    S3 -->|"stores"| S6
    S3 -->|"logs"| S7
    S5 -->|"executes"| S3
    S4 -->|"compiles to"| S5
    S4 -->|"compiles for"| D1
    D1 -->|"alternativeTo"| D2

    %% Definition layer providing contracts to Client and Server modules
    DEF -->|"defines"| C1
    DEF -->|"defines"| S1
    DEF -->|"defines"| S2

    %% Styling
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef client fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef server fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef deno fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click DEF "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/definition"
    click C1 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/client"
    click C2 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/client"
    click S1 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/accessors"
    click S2 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/bridges"
    click S3 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/managers"
    click S4 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/compiler"
    click S5 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/runtime"
    click S6 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/storage"
    click S7 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/logging"
    click D1 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/src/server/runtime/deno"
    click D2 "https://github.com/rocketchat/rocket.chat.apps-engine/tree/alpha/deno-runtime"
```
