# iliasbhal/statebuild architecture

> Architecture diagram of the GitHub repository iliasbhal/statebuild, 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/iliasbhal/statebuild
- Repository: https://github.com/iliasbhal/statebuild

## Overview

##### Main components
- Core Engine (src/core)
– Atom, Selector, Reaction, State, Track, base Entity
– Implements the observer/graph-based state model
- Query Layer (src/query)
– Exposes programmatic query APIs on top of core entities
- React Integration (src/react)
– Custom hooks (useAtom, useSelector, useReaction, useBuild, useInstance, useEntity)
– Enables automatic re-rendering via makeRenderable & enableAutoRendering
- Utilities (src/utils + src/core/utils)
– DependencyGraph, EventBus, MapSet, disposable, Generator, convertToCallback, useForceRender
– Support data structures, event dispatching, and helper functions
- Build & Test Infrastructure
– Configuration: tsconfig.json, babel, jest.config.js
– Build scripts: scripts/playground.ts
– CI workflows: .github/workflows/*.yml

##### Relationships & data flow
- Core Engine is central. Query and React modules depend on it.
- React hooks invoke core Atom/Selector APIs, subscribe to updates via EventBus/DependencyGraph, then trigger component re-render.
- Query layer wraps core APIs to expose higher-level querying functions.
- Utility modules are shared dependencies consumed by Core, Query, and React layers.
- Build/Test infrastructure orchestrates bundling and validation but does not ship in runtime.

##### Architectural patterns
- Observer/Reactive pattern: Atoms/Sels/Reactions form a dependency graph tracked by Track & DependencyGraph.
- Adapter pattern: Query and React modules adapt the core engine to different usage contexts.
- Modular “layered library” approach: clear separation between engine, adapters, and helpers.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Core Engine Layer
  subgraph "Core Engine" 
    direction TB
    Atom["Atom"]:::core
    Selector["Selector"]:::core
    Reaction["Reaction"]:::core
    State["State"]:::core
    Track["Track"]:::core
    Entity["Entity (base)"]:::core
    CoreIndex["index.ts"]:::core
  end

  %% Query Layer
  subgraph "Query Layer"
    direction TB
    QueryAPI["Query API"]:::query
  end

  %% React Integration Layer
  subgraph "React Integration"
    direction TB
    ReactEntry["index.tsx"]:::react
    subgraph "Hooks"
      direction TB
      HooksIndex["index.ts"]:::react
      useAtom["useAtom"]:::react
      useSelector["useSelector"]:::react
      useReaction["useReaction"]:::react
      useBuild["useBuild"]:::react
      useInstance["useInstance"]:::react
    end
    subgraph "React Utils"
      direction TB
      enableAutoRendering["enableAutoRendering"]:::react
      makeRenderable["makeRenderable"]:::react
    end
  end

  %% Utilities Layer
  subgraph "Utilities"
    direction TB
    DependencyGraph["DependencyGraph"]:::util
    EventBus["EventBus"]:::util
    MapSet["MapSet"]:::util
    disposable["disposable"]:::util
    useForceRender["useForceRender"]:::util
    Generator["Generator"]:::util
    convertToCallback["convertToCallback"]:::util
  end

  %% Build/Test Infrastructure
  subgraph "Build & Test Infrastructure"
    direction TB
    TSConfig["tsconfig.json"]:::infra
    Babel[".babelrc"]:::infra
    JestConfig["jest.config.js"]:::infra
    PlaygroundScript["playground.ts"]:::infra
    CIWorkflows["CI Workflows"]:::infra
  end

  %% Dependencies
  ReactEntry -->|"calls Atom()/Selector() API & subscribes via EventBus"| Atom
  ReactEntry -->|"calls Atom()/Selector() API & subscribes via EventBus"| Selector
  ReactEntry -->|"uses enableAutoRendering & makeRenderable"| enableAutoRendering
  ReactEntry -->|"uses enableAutoRendering & makeRenderable"| makeRenderable
  ReactEntry -->|"uses EventBus & DependencyGraph"| EventBus
  ReactEntry -->|"uses EventBus & DependencyGraph"| DependencyGraph

  QueryAPI -->|"wraps core query functions"| Atom
  QueryAPI -->|"wraps core query functions"| Selector

  Atom -->|"tracks deps via Track & DependencyGraph"| Track
  Selector -->|"tracks deps via Track & DependencyGraph"| Track
  Reaction -->|"observes State/Entity changes"| State
  Reaction -->|"observes State/Entity changes"| Entity

  Atom -->|"uses Generator & convertToCallback"| Generator
  Selector -->|"uses Generator & convertToCallback"| convertToCallback
  Atom -->|"publishes via EventBus"| EventBus
  Reaction -->|"publishes via EventBus"| EventBus

  %% Packaging Boundary (npm exports)
  subgraph "NPM Package Exports"
    direction TB
    CoreExport["statebuild/core"]:::boundary
    QueryExport["statebuild/query"]:::boundary
    ReactExport["statebuild/react"]:::boundary
  end
  CoreExport --> CoreIndex
  QueryExport --> QueryAPI
  ReactExport --> ReactEntry

  %% Tests grouping
  subgraph "Tests"
    direction TB
    CoreTests["Core Engine Tests"]:::test
    QueryTests["Query Tests"]:::test
    ReactTests["React Integration Tests"]:::test
    UtilTests["Utility Tests"]:::test
  end
  CoreTests -.-> Atom
  CoreTests -.-> Selector
  CoreTests -.-> Reaction
  QueryTests -.-> QueryAPI
  ReactTests -.-> ReactEntry
  UtilTests -.-> enableAutoRendering

  %% Build/Test links
  CIWorkflows -.-> CoreTests
  CIWorkflows -.-> QueryTests
  CIWorkflows -.-> ReactTests
  CIWorkflows -.-> UtilTests

  %% Legend omitted for brevity

  %% Click Events
  click Atom "https://github.com/iliasbhal/statebuild/blob/main/src/core/Atom.ts"
  click Selector "https://github.com/iliasbhal/statebuild/blob/main/src/core/Selector.ts"
  click Reaction "https://github.com/iliasbhal/statebuild/blob/main/src/core/Reaction.ts"
  click State "https://github.com/iliasbhal/statebuild/blob/main/src/core/State.ts"
  click Track "https://github.com/iliasbhal/statebuild/blob/main/src/core/Track.ts"
  click Entity "https://github.com/iliasbhal/statebuild/blob/main/src/core/base/Entity.ts"
  click CoreIndex "https://github.com/iliasbhal/statebuild/blob/main/src/core/index.ts"
  click QueryAPI "https://github.com/iliasbhal/statebuild/blob/main/src/query/index.ts"
  click ReactEntry "https://github.com/iliasbhal/statebuild/blob/main/src/react/index.tsx"
  click HooksIndex "https://github.com/iliasbhal/statebuild/blob/main/src/react/hooks/index.ts"
  click useAtom "https://github.com/iliasbhal/statebuild/blob/main/src/react/hooks/useAtom.ts"
  click useSelector "https://github.com/iliasbhal/statebuild/blob/main/src/react/hooks/useSelector.ts"
  click useReaction "https://github.com/iliasbhal/statebuild/blob/main/src/react/hooks/useReaction.ts"
  click useBuild "https://github.com/iliasbhal/statebuild/blob/main/src/react/hooks/useBuild.ts"
  click useInstance "https://github.com/iliasbhal/statebuild/blob/main/src/react/hooks/useInstance.ts"
  click enableAutoRendering "https://github.com/iliasbhal/statebuild/blob/main/src/react/utils/enableAutoRendering.ts"
  click makeRenderable "https://github.com/iliasbhal/statebuild/blob/main/src/react/utils/makeRenderable.ts"
  click DependencyGraph "https://github.com/iliasbhal/statebuild/blob/main/src/utils/DependencyGraph.ts"
  click EventBus "https://github.com/iliasbhal/statebuild/blob/main/src/utils/EventBus.ts"
  click MapSet "https://github.com/iliasbhal/statebuild/blob/main/src/utils/MapSet.ts"
  click disposable "https://github.com/iliasbhal/statebuild/blob/main/src/utils/disposable.ts"
  click useForceRender "https://github.com/iliasbhal/statebuild/blob/main/src/utils/useForceRender.ts"
  click Generator "https://github.com/iliasbhal/statebuild/blob/main/src/core/utils/Generator.ts"
  click convertToCallback "https://github.com/iliasbhal/statebuild/blob/main/src/core/utils/convertToCallback.ts"
  click QueryTests "https://github.com/iliasbhal/statebuild/blob/main/src/query/index.test.ts"
  click ReactTests "https://github.com/iliasbhal/statebuild/blob/main/src/react/tests/index.test.tsx"
  click PlaygroundScript "https://github.com/iliasbhal/statebuild/blob/main/scripts/playground.ts"
  click CIWorkflows "https://github.com/iliasbhal/statebuild/blob/main/.github/workflows/main.yml"
  classDef core fill:#e0ffe0,stroke:#2b8a3e,color:#2b8a3e
  classDef query fill:#e0f0ff,stroke:#1f6feb,color:#1f6feb
  classDef react fill:#e0f7f7,stroke:#0a9aa1,color:#0a9aa1
  classDef util fill:#fff9c4,stroke:#e6c229,color:#e6c229
  classDef infra fill:#f2f2f2,stroke:#8c8c8c,color:#8c8c8c
  classDef boundary fill:#ffffff,stroke:#000000,stroke-dasharray: 5 5
  classDef test fill:#ffffff,stroke:#cccccc,stroke-dasharray: 2 2
```
