# reagent-project/reagent architecture

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

- Interactive diagram: https://gitdiagram.com/reagent-project/reagent
- Repository: https://github.com/reagent-project/reagent

## Overview

##### Project Type and Purpose
- This is an open-source Clojure/ClojureScript library called Reagent that provides a minimal interface between ClojureScript and React.
- It’s structured as a component library (not a standalone application) with example apps, documentation, test harnesses, and build tool integrations.

##### Top-Level Component Analysis
- Core library modules (src/reagent, src/clj-kondo): ClojureScript and Clojure namespaces implementing:
- reagent.core – public API
- reagent.dom – renderer bindings
- impl/* – batching, component lifecycle, template processing, utilities
- interop – raw JS interop
- ratom – reactive atom implementation
- Build and configuration:
- project.clj, deps.edn, bb.edn – Clojure build tools
- shadow-cljs.edn, package.json – ClojureScript bundler and npm dependencies
- .github/workflows, CI scripts (run-tests.sh, prepare-tests.sh)
- Documentation and examples:
- doc/, README.md, ROADMAP.md, CHANGELOG.md
- demo/, examples/ – live demos and sample apps built with Reagent
- Pre-rendering and site generation:
- prerender/ and outsite/, site/ – scripts and static assets for documentation site
- Testing environments: test-environments/ and test/ folders – various CLJS/JS runners and Karma setups

##### Key Architectural Patterns and Relationships
- Library core → React renderer:
- The core namespace defines Hiccup-style syntax and component lifecycle abstractions that compile to React.createElement calls.
- dom namespace connects to ReactDOM (client/server).
- Reactive data flow:
- ratom implements reactive atoms that, upon swap! or reset!, enqueue updates in impl/batching → trigger component re-render.
- Build pipeline:
- Source → shadow-cljs/Lein/CLI build → npm/CLJSJS React dependency → produced JS bundle → examples or docs site
- Extensibility:
- The impl and interop namespaces expose hooks for adding custom renderers or integrations (see doc/ReactRenderers.md).

##### Detail Level
- Every top-level directory as a component or sub-component.
- Relationships between:
- src/ → build → examples/
- src/ → tests/ → CI
- src/ → prerender/site generation
- Avoid overgeneralization: explicitly label ratom, impl, core, dom, interop.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Third-Party Dependencies Layer
    subgraph "Third-Party Dependencies" 
        direction TB
        React[(React)]:::third
        ReactDOM[(ReactDOM)]:::third
    end

    %% Library Core Modules Layer
    subgraph "Library Core Modules"
        direction TB
        core["reagent.core"]:::core
        dom["reagent.dom"]:::core
        interop["reagent.interop"]:::core
        ratom["reagent.ratom"]:::core
        subgraph "reagent.impl"
            direction TB
            batching["impl.batching"]:::core
            component["impl.component"]:::core
            input["impl.input"]:::core
            protocols["impl.protocols"]:::core
            template["impl.template"]:::core
            util["impl.util"]:::core
        end
    end

    %% Build Tools Layer
    subgraph "Build Tools"
        direction TB
        Lein["Leiningen (project.clj)"]:::build
        Deps["deps.edn"]:::build
        BB["Babashka (bb.edn)"]:::build
        Shadow["Shadow-CLJS (shadow-cljs.edn)"]:::build
        NPM["npm (package.json)"]:::build
    end

    %% Examples & Demos Layer
    subgraph "Examples & Demos"
        direction TB
        Demo["demo/"]:::docs
        Examples["examples/"]:::docs
    end

    %% Documentation & Site Generation Layer
    subgraph "Docs & Site"
        direction TB
        Doc["doc/"]:::docs
        README["README.md"]:::docs
        Roadmap["ROADMAP.md"]:::docs
        Changelog["CHANGELOG.md"]:::docs
        Prerender["prerender/"]:::docs
        Outsite["outsite/"]:::docs
        Site["site/"]:::docs
    end

    %% Test Harness Layer
    subgraph "Testing Infrastructure"
        direction TB
        TestEnv["test-environments/"]:::test
        Tests["test/"]:::test
        CI["CI Workflows"]:::test
    end

    %% Dataflow and Relationships
    ratom -->|updates| batching
    batching -->|triggers| core
    core -->|"Hiccup→React"| React
    React -->|render| ReactDOM
    dom -->|binds| ReactDOM

    %% Build Pipeline
    src["src/"]:::core -->|compile| Shadow
    src -->|compile| Lein
    src -->|compile| Deps
    src -->|compile| BB
    src -->|bundle| NPM
    Shadow -->|produces| Demo
    Shadow -->|produces| Examples
    Shadow -->|produces| Site
    Prerender -->|generates| Outsite
    Outsite -->|hosts| Site

    %% Testing Flow
    src -->|tested by| TestEnv
    TestEnv -->|runs| Tests
    Tests -->|reports to| CI

    %% Extensibility
    interop -->|hooks| React
    protocols -->|define| interop

    %% Click Events
    click core "https://github.com/reagent-project/reagent/blob/master/src/reagent/core.cljs"
    click dom "https://github.com/reagent-project/reagent/blob/master/src/reagent/dom.cljs"
    click dom "https://github.com/reagent-project/reagent/blob/master/src/reagent/dom/client.cljs"
    click dom "https://github.com/reagent-project/reagent/blob/master/src/reagent/dom/server.cljs"
    click batching "https://github.com/reagent-project/reagent/blob/master/src/reagent/impl/batching.cljs"
    click component "https://github.com/reagent-project/reagent/blob/master/src/reagent/impl/component.cljs"
    click input "https://github.com/reagent-project/reagent/blob/master/src/reagent/impl/input.cljs"
    click protocols "https://github.com/reagent-project/reagent/blob/master/src/reagent/impl/protocols.cljs"
    click template "https://github.com/reagent-project/reagent/blob/master/src/reagent/impl/template.cljs"
    click util "https://github.com/reagent-project/reagent/blob/master/src/reagent/impl/util.cljs"
    click interop "https://github.com/reagent-project/reagent/blob/master/src/reagent/interop.cljs"
    click ratom "https://github.com/reagent-project/reagent/blob/master/src/reagent/ratom.cljs"
    click Lein "https://github.com/reagent-project/reagent/blob/master/project.clj"
    click Deps "https://github.com/reagent-project/reagent/blob/master/deps.edn"
    click BB "https://github.com/reagent-project/reagent/blob/master/bb.edn"
    click Shadow "https://github.com/reagent-project/reagent/blob/master/shadow-cljs.edn"
    click NPM "https://github.com/reagent-project/reagent/blob/master/package.json"
    click CI "https://github.com/reagent-project/reagent/blob/master/.github/workflows/clojure.yml"
    click CI "https://github.com/reagent-project/reagent/blob/master/prepare-tests.sh"
    click CI "https://github.com/reagent-project/reagent/blob/master/run-tests.sh"
    click Doc "https://github.com/reagent-project/reagent/tree/master/doc/"
    click README "https://github.com/reagent-project/reagent/blob/master/README.md"
    click Roadmap "https://github.com/reagent-project/reagent/blob/master/ROADMAP.md"
    click Changelog "https://github.com/reagent-project/reagent/blob/master/CHANGELOG.md"
    click Demo "https://github.com/reagent-project/reagent/tree/master/demo/reagentdemo/"
    click Examples "https://github.com/reagent-project/reagent/tree/master/examples/"
    click Prerender "https://github.com/reagent-project/reagent/blob/master/prerender/sitetools/prerender.cljs"
    click Outsite "https://github.com/reagent-project/reagent/tree/master/outsite/public/"
    click Site "https://github.com/reagent-project/reagent/tree/master/site/public/"
    click TestEnv "https://github.com/reagent-project/reagent/tree/master/test-environments/"
    click Tests "https://github.com/reagent-project/reagent/tree/master/test/reagent/"
    click Tests "https://github.com/reagent-project/reagent/tree/master/test/reagenttest/"
    click Tests "https://github.com/reagent-project/reagent/blob/master/test/runners/karma.conf.js"

    %% Styles
    classDef core fill:#cce5ff,stroke:#0062cc,color:#004085;
    classDef build fill:#d4edda,stroke:#155724,color:#155724;
    classDef third fill:#ffe5b4,stroke:#ff8c00,color:#8b4513;
    classDef docs fill:#fff3cd,stroke:#856404,color:#856404;
    classDef test fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
