# jotai-labs/jotai-devtools architecture

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

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

## Overview

##### Project’s core purpose and components
- The README shows that it is a debugging tool for the Jotai state management library. It offers various features such as atom value inspection, a time-travel debugger, JSON tree view for atom values, and integration hooks.
- Files and folders under src/ (especially under src/DevTools and its nested Extension folder) confirm that the project is built as a UI-based devtools extension with multiple React components and hooks.

##### Break down the major architectural components to be depicted
a. DevTools Core (Container)
- The entry point is in src/index.ts.
- The central module (src/DevTools) encapsulates the core logic, including global configuration and integration with Jotai-based state.
b. UI Components (View Layer)
- The “Extension” directory (within src/DevTools/Extension) holds the main UI components such as Shell, AtomViewer, TimeTravel, Header, JSONTree, and related subcomponents.
- Separate components exist for different debug viewpoints (e.g., AtomViewer and TimeTravel) that allow developers to inspect atom states, view snapshots, and perform diffing.
c. Hooks and Atoms (State and Business Logic)
- Custom hooks (found under src/DevTools/hooks and src/utils/hooks) manage state interactions (like useAtomsSnapshot, useGotoAtomsSnapshot, etc.).
- Atom definitions in src/DevTools/atoms represent the core configuration and state elements.
d. Integration and Provider Mode
e. Build, Testing, and Other Infrastructure
- Although primarily UI-focused, note the existence of a robust testing architecture (with __tests__ directory and snapshots), configuration files for ESLint, Babel, Storybook, and deployment scripts.
- Tools like Storybook (in the .storybook folder) indicate an isolated environment for developing/testing UI components.

##### Relationships and interactions
- Integration links where the custom hooks and atoms (under src/DevTools/atoms and hooks) feed data into the UI components.
- “provider” option as a separate branch that wraps the DevTools component and routes state changes via a custom store.
- Test modules (from __tests__) as peripheral components that validate interactions between these modules.

##### Architectural patterns and design principles
- Separation of concerns: the project cleanly distinguishes state management (atoms and hooks), UI rendering (React components inside the Extension folder), and integration (provider vs. provider-less setups).
- Modular composition: many small components (each in its own file) make up the overall UI, which is in line with modern React and component-based design.
- Integration of build and test infrastructure using tools like tsup, Storybook, Jest, and its configuration files.

##### Final touches
- Every major block/component is clearly labeled with its role (e.g., “Debug UI”, “Atom state management”, “Time-Travel Engine”, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% DevTools Core Subgraph
    subgraph "DevTools Core"
        DT1["Entry Point"]:::core
        DT2["Core Logic"]:::core
        DT3["Core Index"]:::core
        DT1 --> DT2
        DT2 --> DT3
    end

    %% UI Components Subgraph
    subgraph "UI Components"
        EXT["Extension Container"]:::ui
        subgraph "Shell Components"
            SHELL["Shell"]:::ui
            AV["AtomViewer"]:::ui
            TT["TimeTravel"]:::ui
            HDR["Header"]:::ui
            JT["JSONTree"]:::ui
            SHELL --> AV
            SHELL --> TT
            SHELL --> HDR
            SHELL --> JT
        end
        EXT --> SHELL
    end

    %% State & Business Logic Subgraph
    subgraph "State & Business Logic"
        HOOKS["Custom Hooks"]:::logic
        ATOMS["Atoms & State"]:::logic
    end

    %% Integration Options Subgraph
    subgraph "Integration Options"
        PROV["Provider Integration"]:::integration
        NPROV["Provider-less Integration"]:::integration
    end

    %% Development Infrastructure Subgraph
    subgraph "Dev Infrastructure"
        TEST["Testing Modules"]:::infra
        STORY["Storybook"]:::infra
        CONFIG["Build & Config"]:::infra
    end

    %% Main Connections
    DT3 --> EXT
    HOOKS --> EXT
    ATOMS --> EXT
    EXT --> PROV
    EXT --> NPROV

    %% Peripheral Connections to Infrastructure
    DT1 --- TEST
    DT1 --- STORY
    DT1 --- CONFIG

    %% Click Events
    click DT1 "https://github.com/jotai-labs/jotai-devtools/blob/main/src/index.ts"
    click DT2 "https://github.com/jotai-labs/jotai-devtools/blob/main/src/DevTools/DevTools.tsx"
    click DT3 "https://github.com/jotai-labs/jotai-devtools/blob/main/src/DevTools/index.ts"
    click EXT "https://github.com/jotai-labs/jotai-devtools/blob/main/src/DevTools/Extension/Extension.tsx"
    click SHELL "https://github.com/jotai-labs/jotai-devtools/tree/main/src/DevTools/Extension/components/Shell"
    click AV "https://github.com/jotai-labs/jotai-devtools/tree/main/src/DevTools/Extension/components/Shell/components/AtomViewer"
    click TT "https://github.com/jotai-labs/jotai-devtools/tree/main/src/DevTools/Extension/components/Shell/components/TimeTravel"
    click HDR "https://github.com/jotai-labs/jotai-devtools/tree/main/src/DevTools/Extension/components/Shell/components/Header"
    click JT "https://github.com/jotai-labs/jotai-devtools/tree/main/src/DevTools/Extension/components/Shell/components/JSONTree"
    click HOOKS "https://github.com/jotai-labs/jotai-devtools/tree/main/src/DevTools/hooks"
    click ATOMS "https://github.com/jotai-labs/jotai-devtools/tree/main/src/DevTools/atoms"
    click PROV "https://github.com/jotai-labs/jotai-devtools/blob/main/src/DevTools/atoms/user-custom-store.ts"
    click NPROV "https://github.com/jotai-labs/jotai-devtools/tree/main/src/stories/ProviderLess"
    click TEST "https://github.com/jotai-labs/jotai-devtools/tree/main/__tests__"
    click STORY "https://github.com/jotai-labs/jotai-devtools/blob/main/.storybook"
    click CONFIG "https://github.com/jotai-labs/jotai-devtools/blob/main/tsconfig.json"

    %% Styles
    classDef core fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef ui fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef logic fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef integration fill:#577590,stroke:#333,stroke-width:2px;
    classDef infra fill:#277da1,stroke:#333,stroke-width:2px;
```
