# rerun-io/rerun architecture

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

- Interactive diagram: https://gitdiagram.com/rerun-io/rerun
- Repository: https://github.com/rerun-io/rerun

## Overview

##### Project type and purpose
- Rerun is an open-source, multimodal data-logging and visualization toolchain. It provides language-specific SDKs (Rust, Python, C++, JS), a CLI, a networked viewer (native & web), a file-based recording format (RRD), and query APIs.
- It’s neither a single standalone app nor a classic front-end/back-end web service; it’s a modular toolkit that spans clients, libraries, storage, services, and interactive viewers.

##### Top-level components
a. SDK clients (language bindings)
- rerun_py (Python)
- rerun_cpp (C++)
- rerun (Rust CLI & SDK)
- rerun_js (TypeScript/JS bindings & web viewer)
b. Core crates (“crates/store”, “crates/build”, “crates/utils”)
- Serialization & binary or protobuf encoding
- Chunked store & file sink (RRD)
- Dataframe query, loader, and store abstractions
- Code-generation tools (re_types_builder, re_protos_builder)
c. Data path & storage
- Streaming to disk: ci snapshot “.rrd” format via re_log_encoding & re_chunk_store
- In-memory store & query engine via re_entity_db, re_dataframe, re_datafusion
d. Transport & services
- gRPC server and client (crates/store/re_grpc_server, re_grpc_client)
- Binary stream sink over TCP/Unix socket (“spawn()” API)
e. CLI
- rerun-cli (top/rerun-cli) for launching viewer, recording, file operations, migration, verification
f. Viewer
- Native Rust viewer (crates/viewer/re_viewer & companion crates for panels, UI, context, renderer)
- Web viewer (rerun_js/web-viewer) loaded via WASM or remote gRPC

##### Relationships & data flow
1. Application code imports SDK →
2. SDK marshals logs to a RecordingStream →
3a. Direct to viewer process via IPC/gRPC or spawn()
3b. To file sink (RRD) on disk → later replay
4. Viewer process ingests logs via re_viewer_context →
5. Query & store context builds in-memory state →
6. re_renderer draws primitives →
7. UI crates (re_time_panel, re_selection_panel, re_blueprint_tree, etc.) compose panels, menus, interactions

##### Architectural patterns & principles
- Modular crates by concern: build-time codegen, runtime store, rendering, UI, utilities
- Client-server decoupling: SDK ↔ Viewer over well-defined protocols (binary, gRPC)
- Plug-in-style UI: each view type (2D, 3D, graph, dataframe, map, text) is a separate crate
- Layered design: serialization layer → storage layer → query layer → rendering layer → application/UI layer

##### Technologies & frameworks
- Rust cargo workspace with many sub-crates
- FlatBuffers & Protobuf codegen for type definitions
- wgpu / WebGPU via re_renderer for cross-platform GPU
- clap for CLI parsing
- gRPC via tonic (server & client)
- WASM for web viewer
- Node.js & rollup scripts in rerun_js

##### Essential architectural elements
- SDK clients and language boundaries
- RecordingStream (binary & Protobuf)
- re_log_encoding & re_chunk_store (file sink)
- gRPC server & client
- In-memory store & query engine
- Viewer process & UI modules
- Renderer and GPU abstraction
- Build-time codegen crates
- CLI entrypoint

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% SDK Clients
    subgraph "SDK Clients"
        direction TB
        SDK_PY["rerun_py"]:::sdk
        SDK_CPP["rerun_cpp"]:::sdk
        SDK_RS["re_sdk (Rust CLI & SDK)"]:::sdk
        SDK_JS["rerun_js (JS/Web)"]:::sdk
    end

    %% RecordingStream
    RecordingStream["RecordingStream"]:::core

    %% File Storage
    subgraph "File Storage"
        direction TB
        LogEncoding["re_log_encoding"]:::core
        ChunkStore["re_chunk_store"]:::core
        RRDFile[".rrd File"]:::storage
    end

    %% Transport & Services
    subgraph "Transport & Services"
        direction TB
        GRPC_Client["gRPC Client"]:::service
        GRPC_Server["gRPC Server"]:::service
        BinarySink["Binary Stream Sink"]:::service
    end

    %% CLI
    CLI["CLI Orchestrator (rerun-cli)"]:::service

    %% Viewer Process
    subgraph "Viewer Process"
        direction TB
        re_viewer_context["re_viewer_context"]:::core
        subgraph "In-Memory Store & Query"
            direction TB
            EntityDB["re_entity_db"]:::core
            DataFrame["re_dataframe"]:::core
            DataFusion["re_datafusion"]:::core
        end
        Renderer["re_renderer"]:::core
        subgraph "UI Modules"
            direction TB
            TimePanel["re_time_panel"]:::ui
            SelectionPanel["re_selection_panel"]:::ui
        end
    end

    %% Web Viewer
    WebViewer["Web Viewer UI"]:::ui
    WebViewerServer["re_web_viewer_server"]:::service

    %% Build Tools & Utils
    subgraph "Build Tools & Utilities"
        direction TB
        ProtosBuilder["re_protos_builder"]:::core
        TypesBuilder["re_types_builder"]:::core
        Utils["crates/utils"]:::core
    end

    %% Relationships
    SDK_PY -->|"logs"| RecordingStream
    SDK_CPP -->|"logs"| RecordingStream
    SDK_RS -->|"logs"| RecordingStream
    SDK_JS -->|"logs"| RecordingStream

    RecordingStream -->|"file I/O"| LogEncoding
    LogEncoding --> ChunkStore
    ChunkStore -->|"writes"| RRDFile

    RecordingStream -->|"gRPC"| GRPC_Client
    GRPC_Client --> GRPC_Server
    GRPC_Server --> ViewerProcess

    RecordingStream -->|"spawn()"| BinarySink
    BinarySink --> ViewerProcess

    CLI -->|"spawn viewer"| ViewerProcess
    CLI -->|"replay file"| RRDFile
    CLI -->|"record"| RecordingStream

    ViewerProcess --> re_viewer_context
    re_viewer_context --> EntityDB
    EntityDB --> DataFrame
    DataFrame --> DataFusion
    DataFusion --> Renderer
    Renderer --> TimePanel
    Renderer --> SelectionPanel

    WebViewerServer --> WebViewer
    GRPC_Server --> WebViewerServer

    ProtosBuilder --> TypesBuilder

    %% Click Events
    click SDK_PY "https://github.com/rerun-io/rerun/tree/main/rerun_py/rerun_sdk"
    click SDK_CPP "https://github.com/rerun-io/rerun/blob/main/rerun_cpp/src/rerun.hpp"
    click SDK_RS "https://github.com/rerun-io/rerun/blob/main/crates/top/re_sdk/src/lib.rs"
    click SDK_JS "https://github.com/rerun-io/rerun/tree/main/rerun_js/web-viewer"
    click LogEncoding "https://github.com/rerun-io/rerun/tree/main/crates/store/re_log_encoding"
    click ChunkStore "https://github.com/rerun-io/rerun/tree/main/crates/store/re_chunk_store"
    click EntityDB "https://github.com/rerun-io/rerun/tree/main/crates/store/re_entity_db"
    click DataFrame "https://github.com/rerun-io/rerun/tree/main/crates/store/re_dataframe"
    click DataFusion "https://github.com/rerun-io/rerun/tree/main/crates/store/re_datafusion"
    click GRPC_Client "https://github.com/rerun-io/rerun/tree/main/crates/store/re_grpc_client"
    click GRPC_Server "https://github.com/rerun-io/rerun/tree/main/crates/store/re_grpc_server"
    click BinarySink "https://github.com/rerun-io/rerun/blob/main/crates/top/re_sdk/src/binary_stream_sink.rs"
    click CLI "https://github.com/rerun-io/rerun/blob/main/crates/top/rerun-cli/src/bin/rerun.rs"
    click ProtosBuilder "https://github.com/rerun-io/rerun/tree/main/crates/build/re_protos_builder"
    click TypesBuilder "https://github.com/rerun-io/rerun/tree/main/crates/build/re_types_builder"
    click Utils "https://github.com/rerun-io/rerun/tree/main/crates/utils"
    click ViewerProcess "https://github.com/rerun-io/rerun/blob/main/crates/viewer/re_viewer/src/app.rs"
    click Renderer "https://github.com/rerun-io/rerun/blob/main/crates/viewer/re_renderer/src/lib.rs"
    click WebViewerServer "https://github.com/rerun-io/rerun/tree/main/crates/viewer/re_web_viewer_server"
    click TimePanel "https://github.com/rerun-io/rerun/blob/main/crates/viewer/re_time_panel/src/time_panel.rs"
    click SelectionPanel "https://github.com/rerun-io/rerun/blob/main/crates/viewer/re_selection_panel/src/selection_panel.rs"

    %% Styles
    classDef sdk fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#FFA500,stroke:#000,stroke-width:1px
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ui fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef storage fill:#F0E68C,stroke:#000,stroke-width:1px
```
