# pmndrs/jotai architecture

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

- Interactive diagram: https://gitdiagram.com/pmndrs/jotai
- Repository: https://github.com/pmndrs/jotai

## Overview

##### Project type and purpose
- Jotai is an open-source, zero-boilerplate state-management library for React (and vanilla JS).
- It provides a minimal core, React bindings, vanilla JS APIs, Babel plugins, utilities, and extensive documentation + examples.

##### File structure
- src/
– core engine entry (src/index.ts)
– react integration (src/react/…)
– vanilla API (src/vanilla/…)
– Babel tooling (src/babel/…)
– shared utilities (src/utils.ts, src/types.d.ts)
- docs/ & website/
– docs/*.mdx → documentation site content
– website/ → Gatsby-based site source + API endpoints
- examples/
– multiple standalone demos (each a Vite/React project consuming the library)
- build & CI
– rollup.config.mjs → bundling to npm artifacts
– babel.config.js → for tests & compiled output
– GitHub Actions workflows → test, lint, publish pipelines
- tests/
– vitest config + test suites for core, react, vanilla, and babel plugins

##### Extract architecture hints from the README
- Core API is atom-based, functional, asynchronous/derived, monadic
- Extensions include async atoms, computed atoms, write-only atoms
- React components use hooks (useAtom, useAtomValue, useSetAtom) that wrap core atoms
- Encourages composability and interoperability (vanilla & React)

a.  Core Library Module
- Atom creation & state storage engine
- Derived/async utilities
b.  React Integration Layer
- Hooks (useAtom, etc.)
- Provider component
c.  Vanilla Integration Layer
- Direct atom APIs (atom, read/write, utils)
d.  Tooling & Build Pipeline
- Babel plugins & preset (debug labels, HMR)
- Rollup bundler → npm packages (cjs, esm)
- GitHub Actions → test, build, publish
e.  Documentation & Website
- Markdown/MDX content → Gatsby → Deployed to Vercel
- API routes (contact form)
f.  Examples & Demos
- Standalone React/Vite projects consuming published package
g.  External Services
- npm registry (package publish)
- GitHub (source repo, CI)
- Vercel/Netlify (website hosting)
- CodeSandbox / StackBlitz (live demos)

##### Relationships & data flows
- React layer → React app components (useAtom hooks)
- Build pipeline: src → Babel → Rollup → npm artifacts
- CI → triggers tests on src, examples, website → on success publishes to npm & deploys website
- Examples/website → import from npm or local package link
- External tooling (CodeSandbox) → live code embeds

##### Architectural patterns & design principles
- Modular, layered architecture: core engine decoupled from framework bindings
- Functional programming / monads: atoms as composable state units
- Separation of concerns:
– Core logic (state management)
– Presentation bindings (React hooks)
– Tooling (build & HMR)
– Documentation (MDX + static site)
- Extensibility via utilities and extensions (cache, optics, reducers, etc.)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Library Module
    subgraph "Core Library Module"
        direction TB
        CoreIndex["Core Entry\n(src/index.ts)"]:::core
        CoreUtils["Shared Utils\n(src/utils.ts)"]:::core
        CoreTypes["Types Definitions\n(src/types.d.ts)"]:::core
    end

    %% React Integration Layer
    subgraph "React Integration Layer"
        direction TB
        ReactProvider["Provider Component\n(src/react/Provider.ts)"]:::react
        ReactUseAtom["useAtom Hook\n(src/react/useAtom.ts)"]:::react
        ReactUseAtomValue["useAtomValue Hook\n(src/react/useAtomValue.ts)"]:::react
        ReactUseSetAtom["useSetAtom Hook\n(src/react/useSetAtom.ts)"]:::react
        ReactUtils["Utils Directory\n(src/react/utils/)"]:::react
    end

    %% Vanilla Integration Layer
    subgraph "Vanilla Integration Layer"
        direction TB
        VanillaEntry["Vanilla API Entry\n(src/vanilla.ts)"]:::vanilla
        VanillaAtom["Atom Factory\n(src/vanilla/atom.ts)"]:::vanilla
        VanillaStore["Store Engine\n(src/vanilla/store.ts)"]:::vanilla
        VanillaUtils["Utils Directory\n(src/vanilla/utils/)"]:::vanilla
    end

    %% Tooling & Build Pipeline
    subgraph "Tooling & Build Pipeline"
        direction TB
        BabelPluginDebug["Babel Debug Label Plugin\n(src/babel/plugin-debug-label.ts)"]:::tooling
        BabelPluginRefresh["React Refresh Plugin\n(src/babel/plugin-react-refresh.ts)"]:::tooling
        BabelPreset["Babel Preset\n(src/babel/preset.ts)"]:::tooling
        BabelUtils["Babel Utils\n(src/babel/utils.ts)"]:::tooling
        RollupConfig["Rollup Config\n(rollup.config.mjs)"]:::tooling
        BabelConfig["Babel Config\n(babel.config.js)"]:::tooling
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows"
        direction TB
        CIWorkflows["GH Actions Workflows\n(.github/workflows/*.yml)"]:::cicd
    end

    %% Documentation & Website
    subgraph "Documentation & Website"
        direction TB
        DocsMDX["Docs Content\n(docs/**/*.mdx)"]:::docs
        GatsbyConfig["Gatsby Config\n(website/gatsby-config.js)"]:::docs
        GatsbyPages["Gatsby Pages\n(website/src/pages)"]:::docs
        GatsbyComponents["Gatsby Components\n(website/src/components)"]:::docs
        GatsbyHooks["Gatsby Hooks\n(website/src/hooks)"]:::docs
        GatsbyUtils["Gatsby Utils\n(website/src/utils)"]:::docs
    end

    %% Examples & Demos
    subgraph "Examples & Demos"
        direction TB
        ExamplesAll["Examples Directory\n(examples/*)"]:::examples
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NPMRegistry["npm Registry"]:::external
        GitHubRepo["GitHub"]:::external
        VercelHost["Vercel/Netlify"]:::external
        LiveDemos["CodeSandbox/StackBlitz"]:::external
    end

    %% Dependencies & Flows
    CoreIndex -->|extends| CoreUtils
    CoreIndex -->|provides types| CoreTypes
    CoreIndex -->|used by| ReactProvider
    CoreIndex -->|used by| VanillaEntry

    ReactUtils -->|supports| ReactProvider
    ReactProvider -->|hooks| ReactUseAtom
    ReactUseAtom -->|reads| CoreIndex
    ReactUseAtomValue -->|reads| CoreIndex
    ReactUseSetAtom -->|writes| CoreIndex

    VanillaUtils -->|supports| VanillaEntry
    VanillaEntry -->|atom creation| VanillaAtom
    VanillaAtom -->|state storage| VanillaStore

    %% Build pipeline flow
    CoreIndex -->|transpile| BabelPluginDebug
    BabelPluginDebug --> BabelPreset
    BabelPluginRefresh --> BabelPreset
    BabelPreset --> BabelUtils
    BabelPreset --> RollupConfig
    RollupConfig -->|bundles| NPMRegistry
    BabelConfig -->|configures tests/build| CIWorkflows

    %% CI triggers
    GitHubRepo -->|on push trigger| CIWorkflows
    CIWorkflows -->|runs tests| CoreIndex
    CIWorkflows -->|on success publish| NPMRegistry
    CIWorkflows -->|on success deploy| VercelHost

    %% Documentation flow
    DocsMDX -->|built by Gatsby| GatsbyConfig
    GatsbyConfig -->|generates| GatsbyPages
    GatsbyPages --> GatsbyComponents
    GatsbyComponents --> GatsbyHooks
    GatsbyHooks --> GatsbyUtils
    GatsbyConfig -->|deploy to| VercelHost

    %% Examples consumption
    ExamplesAll -->|install from| NPMRegistry
    ExamplesAll -->|run demos on| LiveDemos

    %% External connections
    LiveDemos -->|imports| NPMRegistry

    %% Click Events
    click CoreIndex "https://github.com/pmndrs/jotai/blob/main/src/index.ts"
    click CoreUtils "https://github.com/pmndrs/jotai/blob/main/src/utils.ts"
    click CoreTypes "https://github.com/pmndrs/jotai/blob/main/src/types.d.ts"
    click ReactProvider "https://github.com/pmndrs/jotai/blob/main/src/react/Provider.ts"
    click ReactUseAtom "https://github.com/pmndrs/jotai/blob/main/src/react/useAtom.ts"
    click ReactUseAtomValue "https://github.com/pmndrs/jotai/blob/main/src/react/useAtomValue.ts"
    click ReactUseSetAtom "https://github.com/pmndrs/jotai/blob/main/src/react/useSetAtom.ts"
    click ReactUtils "https://github.com/pmndrs/jotai/tree/main/src/react/utils/"
    click VanillaEntry "https://github.com/pmndrs/jotai/blob/main/src/vanilla.ts"
    click VanillaAtom "https://github.com/pmndrs/jotai/blob/main/src/vanilla/atom.ts"
    click VanillaStore "https://github.com/pmndrs/jotai/blob/main/src/vanilla/store.ts"
    click VanillaUtils "https://github.com/pmndrs/jotai/tree/main/src/vanilla/utils/"
    click BabelPluginDebug "https://github.com/pmndrs/jotai/blob/main/src/babel/plugin-debug-label.ts"
    click BabelPluginRefresh "https://github.com/pmndrs/jotai/blob/main/src/babel/plugin-react-refresh.ts"
    click BabelPreset "https://github.com/pmndrs/jotai/blob/main/src/babel/preset.ts"
    click BabelUtils "https://github.com/pmndrs/jotai/blob/main/src/babel/utils.ts"
    click RollupConfig "https://github.com/pmndrs/jotai/blob/main/rollup.config.mjs"
    click BabelConfig "https://github.com/pmndrs/jotai/blob/main/babel.config.js"
    click CIWorkflows "https://github.com/pmndrs/jotai/blob/main/.github/workflows/test.yml"
    click CIWorkflows "https://github.com/pmndrs/jotai/blob/main/.github/workflows/publish.yml"
    click CIWorkflows "https://github.com/pmndrs/jotai/blob/main/.github/workflows/preview-release.yml"
    click DocsMDX "https://github.com/pmndrs/jotai/blob/main/docs/**/*.mdx"
    click GatsbyConfig "https://github.com/pmndrs/jotai/blob/main/website/gatsby-config.js"
    click GatsbyPages "https://github.com/pmndrs/jotai/tree/main/website/src/pages"
    click GatsbyComponents "https://github.com/pmndrs/jotai/tree/main/website/src/components"
    click GatsbyHooks "https://github.com/pmndrs/jotai/tree/main/website/src/hooks"
    click GatsbyUtils "https://github.com/pmndrs/jotai/tree/main/website/src/utils"
    click ExamplesAll "https://github.com/pmndrs/jotai/tree/main/examples/"

    %% Styles
    classDef core fill:#DCEEFB,stroke:#279aff
    classDef react fill:#D5E8D4,stroke:#34a853
    classDef vanilla fill:#FFE6CC,stroke:#f2994a
    classDef tooling fill:#EDEDED,stroke:#9e9e9e
    classDef docs fill:#EAD1DC,stroke:#a55ca5
    classDef examples fill:#FFF2CC,stroke:#fbbc04
    classDef cicd fill:#F5F5F5,stroke:#757575
    classDef external fill:#EFEFEF,stroke:#666666
```
