How nerdslabs/storex works
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”).