# salsa-rs/salsa architecture

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

- Interactive diagram: https://gitdiagram.com/salsa-rs/salsa
- Repository: https://github.com/salsa-rs/salsa

## Overview

##### Main Components
- Query Definitions – This includes both Input queries (the base inputs) and Function queries (which compute derived values). In salsa, each query is essentially defined as a function mapping a “key” to a “value.”
- Runtime / Database Core – In the src directory you see files like database.rs, database_impl.rs, runtime.rs, and various modules handling dependency graphs and memoization. This forms the core where queries are stored, tracked, and re-executed as needed.
- Dependency Graph & Incrementality – Components inside src (e.g., dependency_graph.rs) and modules in book/src/plumbing indicate that the system uses a dependency graph to determine which memoized results to invalidate.
- Macro Components – The components/salsa-macros and components/salsa-macro-rules directories contain macros that generate boilerplate code to facilitate the query system. These are essential in wiring together the input and tracked computations.
- Testing & Examples – Though not directly part of the runtime, the tests and examples (e.g., in examples/calc and tests/*) illustrate usage patterns and provide validation of the system design.

##### Relationships and Interactions
- The API Layer (Query Definitions): Developers define queries via macros from salsa-macros and salsa-macro-rules. These macros generate the code that interacts with the core runtime.
- The Runtime / Database Core: Once queries are defined and the program is running, the core (database_impl.rs, runtime modules, etc.) maintains a dependency graph, memo table, and incremental update logic. Every query call goes through this layer.

##### Architectural Patterns and Design Principles
- Incremental Computation Pattern: Memoization and selective recomputation are key. Emphasize that the system computes queries on-demand and only recomputes when necessary.
- Separation between Query Definition and Query Execution: There’s a clear boundary between how queries are declared (using macros and annotated functions) and how they are executed/managed by the runtime.
- Dependency Tracking: An explicit dependency graph exists that maintains the relationships between queries, showing how edges exist from an input’s changes to the function queries that need to re-evaluate.
- Extensibility: With components split into multiple Cargo packages (the macros, the core library, etc.), the system is modular and extensible.

##### Relevant Technologies and Tools
- Rust as the implementation language.
- Cargo for dependency management and compilation (highlight Cargo.toml and build scripts).
- GitHub Actions workflows (showing testing and documentation builds) might be noted on the periphery to signal CI integration.
- Book and examples as educational resources for how the architecture is intended to be used.

##### Specific Elements
- A central “Runtime/Database” block responsible for:
– Maintaining memoized results.
– Managing the incremental recomputation.
– Hosting the dependency graph (which can be a subcomponent inside the runtime).
– From the client code into the “Query API.”
– From there into the “Runtime/Database” where the dependency graph is updated.
– Back to the client code when values are returned.
- Optionally, a peripheral block to indicate CI/Build & Testing processes inspired by the workflows and tests directories.

- All major components: query definitions (inputs/functions), macros for code generation, runtime/database core, dependency graph for incremental computations, and supporting examples/tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Define Nodes
    Client["Client Code"]:::client

    subgraph "Query Definitions"
        QueryAPI["Query API (lib.rs & function.rs)"]:::query
    end

    subgraph "Macro Components"
        SalsaMacros["Salsa Macros"]:::macro
        SalsaMacroRules["Salsa Macro Rules"]:::macro
    end

    subgraph "Runtime Layer"
        RuntimeCore["Runtime/Database Core (database.rs, runtime.rs)"]:::runtime
        DepGraph["Dependency Graph & Memoization (dependency_graph.rs)"]:::runtime
    end

    subgraph "CI & Resources"
        Examples["Examples (calc)"]:::external
        Tests["Tests"]:::external
        Documentation["Documentation & Book"]:::external
    end

    %% Define Relationships (Vertical Flow)
    Client -->|"requests"| QueryAPI
    SalsaMacros -->|"generates"| QueryAPI
    SalsaMacroRules -->|"generates"| QueryAPI
    QueryAPI -->|"executes"| RuntimeCore
    RuntimeCore -->|"updates"| DepGraph
    DepGraph -->|"propagates"| QueryAPI
    QueryAPI -->|"returns"| Client

    %% Additional External Relationships
    Examples -->|"demonstrate"| Client
    Tests -->|"validate"| Client
    Documentation -->|"informs"| Client

    %% Click Events
    click QueryAPI "https://github.com/salsa-rs/salsa/blob/master/src/lib.rs"
    click SalsaMacros "https://github.com/salsa-rs/salsa/tree/master/components/salsa-macros"
    click SalsaMacroRules "https://github.com/salsa-rs/salsa/tree/master/components/salsa-macro-rules"
    click RuntimeCore "https://github.com/salsa-rs/salsa/blob/master/src/database.rs"
    click DepGraph "https://github.com/salsa-rs/salsa/blob/master/src/runtime/dependency_graph.rs"
    click Examples "https://github.com/salsa-rs/salsa/tree/master/examples/calc"
    click Tests "https://github.com/salsa-rs/salsa/tree/master/tests"
    click Documentation "https://github.com/salsa-rs/salsa/tree/master/book"

    %% Styles
    classDef client fill:#9FD9FF,stroke:#333,stroke-width:2px;
    classDef query fill:#B3E6B3,stroke:#333,stroke-width:2px;
    classDef runtime fill:#FFCC99,stroke:#333,stroke-width:2px;
    classDef macro fill:#FF99CC,stroke:#333,stroke-width:2px;
    classDef external fill:#FFE699,stroke:#333,stroke-width:2px;
```
