# livebook-dev/livebook architecture

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

- Interactive diagram: https://gitdiagram.com/livebook-dev/livebook
- Repository: https://github.com/livebook-dev/livebook

## Overview

##### Main Components
- Frontend/Client-side: Represented by the assets directory containing JavaScript, CSS, and CodeMirror integrations. This is where the interactive code editor (with autocompletion, inline documentation, and UI hooks) lives.
- Web Server & Phoenix Components: In the lib/livebook_web directory you have controllers, live views, channels, plugs, and router; these routes are the main interface for requests coming from users.
- Application Core and Business Logic: Found in lib/livebook and subdirectories. This includes the notebook management (cells, markdown, state tracking), runtimes, evaluator modules, and deployment supervisors.
- Runtime & Code Evaluation: Modules in lib/livebook/runtime and lib/livebook/runtime/evaluator. These components are responsible for spawning evaluators, managing attached nodes, and handling code execution.
- File System & Storage: The file system modules (under lib/livebook/file_system, local and S3 implementations) handle notebook storage and possibly integrations with external storage.
- Real-time Collaboration: LiveView components, channels (e.g., js_view_channel) and session management modules define how multiple users can work simultaneously on a notebook.
- External Services Integration: Integration with Kino for rich interactive outputs (e.g., charts, tables), along with support for authentication via various methods (basic_auth, cloudflare, google_iap, tailscale, custom modules).
- Deployment & Packaging Tools: Several directories (rel/app/macos, rel/app/windows, Dockerfile, .github workflows) indicate that the project is packaged as both a Docker image and desktop standalone apps for macOS/Windows. There’s also clustering support noted via environment variables and OTP-based distribution.

##### Component Relationships and Data Flow
- Live views and channels coordinate real-time interactions (such as collaborative notebook editing) between multiple users.
- Controllers invoke business logic from the core “livebook” modules for notebook state changes, file system actions, and runtimes.
- The runtime layer receives code snippets and dispatches them to evaluator processes (which may run on local or attached nodes) and then streams back results.
- The file system layer (local or S3) persists and loads notebooks. This is used by components in both the web server and runtime layers.
- Deployment packaging components show how the application can be built and deployed in different runtime environments (Docker, standalone desktop apps, and clustering setups).

##### Architectural Patterns and Principles
- MVC with Phoenix: Clearly split between controllers/views (web logic) and business logic (domain modules in lib/livebook).
- Real-time, event-driven design: Use of LiveView and Phoenix Channels to push and receive updates.
- Supervision Trees: The Elixir/OTP architecture (application, supervisor trees) is used for fault-tolerance and managing evaluator processes.
- Extensibility and Customization: The use of configuration files (config/*) and environment variables allow a highly customizable runtime behavior (e.g., custom runtimes, authentication configuration).
- Packaging and Deployment: Separate build scripts and deployment descriptors (Dockerfiles, rel/ directories, GitHub workflows) document various deployment methods.

##### Relevant Technologies & Frameworks
- Elixir, Phoenix Framework, and OTP-based applications.
- CodeMirror (for rich code editor support), Kino (for interactive visualizations).
- Docker (for container deployments) and native build scripts for macOS/Windows desktop apps.
- Testing frameworks and protocols (protobuf files in the proto folder) suggest that message-driven or inter-process communication may also be depicted.

##### Capturing Essential Architectural Elements
- To capture the boundaries between user interaction, business logic, and code execution.
- Supporting development & deployment directories (like rel/, Dockerfile, GitHub workflows) as contextual components, perhaps in an “Infrastructure & Deployment” section.
- How environment variables and the configuration files (under config/) control various runtime behaviors.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Frontend Subgraph
    subgraph "Client/Frontend"
        B("Browser Client"):::frontend
        FA("Assets (Interactive Code Editor)"):::frontend
    end

    %% Server/Backend Subgraph
    subgraph "Server/Backend"
        WS("Phoenix Web Server (Livebook Web)"):::backend
        AC("Application Core & Business Logic"):::backend
        RE("Runtime & Code Evaluation"):::runtime
        FS("File System & Storage"):::storage
        EI("External Services Integration"):::integration
        RTC("Real-time Collaboration"):::integration
    end

    %% Deployment & Packaging Subgraph
    subgraph "Deployment & Packaging"
        DI("Deployment & Packaging Tools"):::deployment
    end

    %% Runtime and File System children
    subgraph "Runtime Layer"
        EP("Evaluator Processes"):::runtime
    end

    subgraph "Storage Implementations"
        LS("Local Storage Implementation"):::storage
        S3("S3 Storage Implementation"):::storage
    end

    %% Real-time Collaboration children
    subgraph "Collaboration Components"
        LV("LiveView Components"):::integration
        JC("JS View Channel"):::integration
    end

    %% Deployment children
    subgraph "Deployment Artifacts"
        DI1("Docker Image"):::deployment
        DI2("Desktop Apps (macOS/Windows)"):::deployment
        DI3("Server Deployment"):::deployment
        DI4("GitHub Workflows"):::deployment
    end

    %% Connections between subgraphs/ nodes
    B --> FA
    FA --> WS
    WS --> AC
    WS --> RTC
    AC --> RE
    RE --> EP
    AC --> FS
    FS --> LS
    FS --> S3
    AC --> EI
    RTC --> LV
    RTC --> JC
    AC --> DI

    %% Click Events
    click FA "https://github.com/livebook-dev/livebook/tree/main/assets"
    click WS "https://github.com/livebook-dev/livebook/tree/main/lib/livebook_web"
    click AC "https://github.com/livebook-dev/livebook/tree/main/lib/livebook"
    click RE "https://github.com/livebook-dev/livebook/tree/main/lib/livebook/runtime"
    click EP "https://github.com/livebook-dev/livebook/tree/main/lib/livebook/runtime/evaluator"
    click FS "https://github.com/livebook-dev/livebook/tree/main/lib/livebook/file_system"
    click LS "https://github.com/livebook-dev/livebook/blob/main/lib/livebook/file_system/local.ex"
    click S3 "https://github.com/livebook-dev/livebook/blob/main/lib/livebook/file_system/s3.ex"
    click LV "https://github.com/livebook-dev/livebook/tree/main/lib/livebook_web/live"
    click JC "https://github.com/livebook-dev/livebook/blob/main/lib/livebook_web/channels/js_view_channel.ex"
    click EI "https://github.com/livebook-dev/livebook/tree/main/lib/livebook/zta"
    click DI1 "https://github.com/livebook-dev/livebook/tree/main/Dockerfile"
    click DI2 "https://github.com/livebook-dev/livebook/tree/main/rel/app"
    click DI3 "https://github.com/livebook-dev/livebook/tree/main/rel/server"
    click DI4 "https://github.com/livebook-dev/livebook/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef backend fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef runtime fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef storage fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef integration fill:#fce4ec,stroke:#c2185b,stroke-width:2px;
    classDef deployment fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
```
