# nerdslabs/storex architecture

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

- Interactive diagram: https://gitdiagram.com/nerdslabs/storex
- Repository: https://github.com/nerdslabs/storex

## Overview

##### Main Components
- Backend Core (Elixir):
- The main logic is implemented in the lib directory with modules such as storex.ex, storex/diff.ex, storex/store.ex, storex/supervisor.ex, etc.
- There are dedicated handler modules (e.g., storex/handler/cowboy.ex & storex/handler/plug.ex) to handle WebSocket connections using Cowboy or Plug.
- The modules for managing state updates, i.e. mutation functions in the store definition, are also part of this core.
- Frontend Connector (JavaScript/TypeScript):
- Under priv/static there are precompiled client-side assets (CommonJS, ESM, UMD, and TypeScript definition files) that serve as the JavaScript package components.
- package.json and the examples in the README show how to import and use the connector (both the default WebSocket connector and the HTTP-only Node.js option).
- Communication Layer:
- The core communication between the frontend and backend occurs over WebSocket.
- That there is also a fallback HTTP-only Node.js connector (with differences in support for mutations).
- Configuration and Session Management:
- The config directory holds the environment-specific configurations, and the session id generation library is configured via the project’s config (by default with Ecto.UUID).
- Testing Infrastructure:
- The test files (both for browser-based tests and unit tests of handlers/stores) indicate a robust testing suite ensuring each component works as expected.

##### Relationships and Data Flow
- Frontend components (using the provided JavaScript connectors) initiate connections (via WebSocket by default or HTTP) with the backend.
- The connection is managed by the corresponding handler modules in the backend (Storex.Handler.Plug or Storex.Handler.Cowboy).
- Once connected, the frontend can send mutations (e.g., "increase", "decrease", "set") which the backend processes by invoking the corresponding store module functions.
- The backend then computes state diffs and pushes updates back to all connected clients in real-time using the same WebSocket connection.
- Configuration components (from config files) determine aspects like session id generation and default store parameters.

##### Architectural Patterns and Principles
- Unidirectional Data Flow: Similar to Redux, state changes are processed in a predictable way—it is clear which mutations lead to what state changes.
- Decoupled State Management: The logic for state handling is separated from the rendering layer (e.g., not tied directly to Phoenix LiveView).
- Extensibility: There are clear extension points for integrating custom middleware or additional connectors.
- Separation of Concerns: There’s a clear distinction between the server-side state management (backend, supervision trees, store modules) and client-side communication (the JavaScript assets).

##### Relevant Technologies and Libraries
- Elixir and its OTP ecosystem (supervisors, configuration management via mix.exs).
- Cowboy/Plug for WebSocket and HTTP handling.
- WebSocket for real-time communication.
- JavaScript/TypeScript modules for the frontend connector.
- Ecto.UUID for session id generation (configurable).

##### Elements
- Clear labels for every component (e.g., “Frontend Connector”, “WebSocket Handler”, “State Management”, “Supervisory Tree”, “Configuration”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Connector
    subgraph "Frontend Connector"
        F1["JavaScript Connector: Static Assets"]:::frontend
        F2["JavaScript Connector: Package Config"]:::frontend
    end

    %% Communication Layer
    subgraph "Communication Layer"
        C1["Handler: Cowboy"]:::communication
        C2["Handler: Plug"]:::communication
    end

    %% Backend Core
    subgraph "Backend Core"
        B1["Storex Core"]:::backend
        B2["Supervisory Tree"]:::backend
    end

    %% Configuration and Testing
    Cfg["Configuration & Session"]:::config
    Test["Testing Suite"]:::testing

    %% Data Flow Arrows
    F1 -->|"WebSocketConnection"| C1
    F2 -->|"HTTPRequest"| C2
    C1 -->|"MutationRequest"| B1
    C2 -->|"MutationRequest"| B1
    B1 -->|"StateUpdate(diff)"| F1
    B1 -->|"InternalSupervision"| B2
    Cfg -->|"ConfigSettings"| B1

    %% Testing Connections (dashed)
    Test ---|"Tests"| C1
    Test ---|"Tests"| C2
    Test ---|"Tests"| B1

    %% Click Events
    click F1 "https://github.com/nerdslabs/storex/tree/master/priv/static"
    click F2 "https://github.com/nerdslabs/storex/blob/master/package.json"
    click C1 "https://github.com/nerdslabs/storex/blob/master/lib/storex/handler/cowboy.ex"
    click C2 "https://github.com/nerdslabs/storex/blob/master/lib/storex/handler/plug.ex"
    click B1 "https://github.com/nerdslabs/storex/blob/master/lib/storex.ex"
    click B2 "https://github.com/nerdslabs/storex/blob/master/lib/storex/supervisor.ex"
    click Cfg "https://github.com/nerdslabs/storex/blob/master/config/config.exs"
    click Test "https://github.com/nerdslabs/storex/tree/master/test"

    %% Styles
    classDef frontend fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef communication fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef backend fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef config fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef testing fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
