# hotwired/stimulus architecture

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

- Interactive diagram: https://gitdiagram.com/hotwired/stimulus
- Repository: https://github.com/hotwired/stimulus

## Overview

##### Project type and purpose
- Stimulus is an open-source JavaScript framework/library for enhancing existing HTML with behavior.
- It is not a full-stack app but a client-side library packaged for NPM, with example apps, docs, tests, and CI/CD.

##### File structure
- Top-level directories:
– src/             → Core framework code
- core/          → Primary application/controller/router abstractions
- multimap/      → Supporting data structure module
- mutation-observers/ → DOM mutation listener abstractions
– packages/stimulus → Packaged distribution with build configs (Rollup, Webpack helpers, type definitions)
– examples/        → Sample Express-EJS app to demonstrate usage
– docs/            → Handbook and Reference materials
– src/tests/       → Unit and integration tests organized by module
- Config & tooling:
– rollup.config.js, webpack.config.js → Bundlers
– karma.conf.cjs                        → Test runner
– CI workflows under .github/workflows

##### Insights from the README
- Stimulus watches the DOM, instantiates Controller classes when data-controller attributes appear, binds actions, targets, and values.
- Dependencies: vanilla JS, optional Turbo integration, bundlers.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Runtime Flow
    DOM("Browser DOM"):::external
    subgraph "Core Engine" 
        ApplicationCore["Application"]:::core
        ControllerCore["Controller"]:::core
        BindingCore["Binding & Dispatcher"]:::core
        ObserversCore["Observers"]:::observer
        DataMapCore["Data Structures"]:::data
    end
    DOM -->|"detect mutations"| ObserversCore
    ObserversCore -->|"notify binding"| BindingCore
    BindingCore -->|"invoke methods"| ControllerCore
    ControllerCore -->|"read/write"| DataMapCore
    ApplicationCore -->|"manage controllers"| ControllerCore

    %% API Entry
    PublicAPI["Developer-facing API (src/index)"]:::api
    PublicAPI -->|"imports"| ApplicationCore

    %% Build & Packaging Flow
    subgraph "Build & Packaging"
        BuildRoot["rollup.config.js / webpack.config.js"]:::build
        PackageBuild["packages/stimulus Build Configs"]:::build
        DistPackage["Dist Package"]:::build
    end
    PublicAPI -->|"source code"| BuildRoot
    BuildRoot --> PackageBuild
    PackageBuild --> DistPackage

    %% Example App
    Examples["Examples App"]:::example
    DistPackage -->|"consumed by"| Examples

    %% Support Artifacts
    subgraph "Support Artifacts"
        Docs["Documentation (docs/)"]:::support
        Tests["Tests (src/tests/)"]:::support
    end

    %% Click Events
    click PublicAPI "https://github.com/hotwired/stimulus/blob/main/src/index.ts"
    click ApplicationCore "https://github.com/hotwired/stimulus/blob/main/src/core/application.ts"
    click ControllerCore "https://github.com/hotwired/stimulus/blob/main/src/core/controller.ts"
    click BindingCore "https://github.com/hotwired/stimulus/blob/main/src/core/binding.ts"
    click ObserversCore "https://github.com/hotwired/stimulus/blob/main/src/mutation-observers/index.ts"
    click DataMapCore "https://github.com/hotwired/stimulus/blob/main/src/core/data_map.ts"
    click BuildRoot "https://github.com/hotwired/stimulus/blob/main/rollup.config.js"
    click PackageBuild "https://github.com/hotwired/stimulus/blob/main/packages/stimulus/rollup.config.js"
    click DistPackage "https://github.com/hotwired/stimulus/blob/main/packages/stimulus/index.js"
    click Examples "https://github.com/hotwired/stimulus/blob/main/examples/server.js"
    click Docs "https://github.com/hotwired/stimulus/tree/main/docs/handbook"
    click Tests "https://github.com/hotwired/stimulus/blob/main/src/tests/index.ts"

    %% Styles
    classDef core fill:#AEDFF7,stroke:#0366D6,stroke-width:1px
    classDef observer fill:#FFF5BA,stroke:#D99A00,stroke-width:1px
    classDef data fill:#D6F5D6,stroke:#28A745,stroke-width:1px
    classDef api fill:#FDD7E4,stroke:#D73A49,stroke-width:1px
    classDef build fill:#E3E4FA,stroke:#6F42C1,stroke-width:1px
    classDef example fill:#FFDCDC,stroke:#CB2431,stroke-width:1px
    classDef support fill:#F0F0F0,stroke:#6A737D,stroke-dasharray: 5 5
    classDef external fill:#FFFFFF,stroke:#0366D6,stroke-dasharray: 5 5
```
