# marcisbee/exome architecture

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

- Interactive diagram: https://gitdiagram.com/marcisbee/exome
- Repository: https://github.com/marcisbee/exome

## Overview

##### Project Type and Purpose
- Project Type: Exome is a state management library – a core tool that manages deeply nested states and provides integrations for multiple front-end frameworks including React, Preact, Vue, Svelte, Solid, Lit, RxJS, Angular, and even “no framework” usage.
- Purpose: It is designed to be minimal (≈1 KB minizipped), fast (with no diffing), and highly integrated across multiple platforms. Its primary goal is to allow the definition of state stores as classes with actions (methods) that trigger updates in connected views.

##### File Structure
- Top-level Directories & Files:
- The “src” directory holds most of the core library code. This includes the main Exome class, utilities, integrations for different frameworks (files like react.ts, preact.ts, vue.ts, etc.), middleware logic, and state management helpers (e.g., saveState, loadState).
- The “e2e” directory contains end-to-end tests for different integrations (React, Preact, Lit, Angular, etc.). This illustrates how the library’s consumers might interact with the state and verify its behavior.
- The “playground” directory includes sample usage code (like counter examples, various stores, and an example HTML page) which can be a reference for a demo or sandbox usage.
- Additionally, configuration files like tsconfig.json, deno.json, and package.json indicate that the project is written in TypeScript and supports multiple runtimes/environments.
- The “scripts” folder contains build and development scripts.
- Architectural Patterns:
- The library uses a class-based approach where each store is an instance of a class (extending Exome) and each method in the class acts as an action.
- There is clear separation of concerns: the core logic (state management, middleware, utility functions) is isolated in “src”, while different framework integrations are implemented in dedicated files.
- The testing (e2e) structure illustrates integration testing to ensure that the state updates propagate correctly in various frontend environments.

##### Insights from the README
- The README reaffirms that the Exome library supports a variety of integrations with detailed code examples.
- It explains core concepts (stores, state values, actions, middleware) and integration techniques.
- The API reference in the README details functions such as useStore, onAction, saveState, loadState, and middleware management.
- The motivational section highlights that “actions” (methods) are the only way to update state, and that the library is designed for deep states with minimal overhead.

##### Components
a. Core Components:
- Exome Core: Represent the core state management functionality (the Exome class and its state-update logic).
- Middleware Mechanism: Show the addMiddleware function and the pipeline where actions trigger middleware callbacks.
- Utility Functions: Include components for saving and loading state (e.g., saveState, loadState) and helper utilities found in src/utils.
b. Integration Layers:
- Each integration should point to how it subscribes to the Exome core (e.g., using “useStore” in React/Preact, “StoreController” in Lit, and appropriate hooks or wrappers in other frameworks).
c. Testing and Example Implementations:
- E2E Tests: Represent the “e2e” directory as an area that validates integration with real practical examples, showing various tests (like async-action, counter, and recursive tests in different front-end contexts).
- Playground: Include a section for sample applications that demonstrate the library’s usage.

##### Relationships and Data Flow
- How state updates in an Exome store (triggered by an action) flow to connected components via framework integration behaviors.
- Out dependencies among modules such as the core Exome functionality, the integration modules (as adapters), and utility helpers for tasks like state persistence.

##### Final Elements
- Test and playground examples as validation and usage guides.
– Calls from UI components to store actions.
– Middleware intercepting actions.
– Notification pathways from stores to connected components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Layer"
        ExomeCore["Exome Core"]:::core
        Middleware["Middleware Mechanism"]:::middleware
        Utility1["SaveState Utility"]:::utility
        Utility2["LoadState Utility"]:::utility
    end

    %% Integration Adapters
    subgraph "Integration Adapters"
        ReactIntegr["React Integration Adapter"]:::integration
        PreactIntegr["Preact Integration Adapter"]:::integration
        VueIntegr["Vue Integration Adapter"]:::integration
        SvelteIntegr["Svelte Integration Adapter"]:::integration
        SolidIntegr["Solid Integration Adapter"]:::integration
        LitIntegr["Lit Integration Adapter"]:::integration
        RxjsIntegr["RxJS Integration Adapter"]:::integration
        AngularIntegr["Angular Integration Adapter"]:::integration
    end

    %% Testing & Demos
    subgraph "Testing & Demos"
        E2ETests["E2E Tests"]:::testing
        Playground["Playground Examples"]:::testing
    end

    %% Core Interactions
    ExomeCore -->|"triggers"| Middleware
    ExomeCore -->|"persists_state"| Utility1
    ExomeCore -->|"persists_state"| Utility2

    %% Integration bidirectional communication
    ExomeCore <-->|"update_dispatch"| ReactIntegr
    ExomeCore <-->|"update_dispatch"| PreactIntegr
    ExomeCore <-->|"update_dispatch"| VueIntegr
    ExomeCore <-->|"update_dispatch"| SvelteIntegr
    ExomeCore <-->|"update_dispatch"| SolidIntegr
    ExomeCore <-->|"update_dispatch"| LitIntegr
    ExomeCore <-->|"update_dispatch"| RxjsIntegr
    ExomeCore <-->|"update_dispatch"| AngularIntegr

    %% Testing & Demos interactions
    E2ETests -->|"simulate_integration"| ExomeCore
    Playground -->|"sample_usage"| ExomeCore

    %% Click Events
    click ExomeCore "https://github.com/marcisbee/exome/blob/main/src/exome.ts"
    click Middleware "https://github.com/marcisbee/exome/blob/main/src/middleware.ts"
    click Middleware "https://github.com/marcisbee/exome/blob/main/src/on-action.ts"
    click Utility1 "https://github.com/marcisbee/exome/blob/main/src/utils/save-state.ts"
    click Utility2 "https://github.com/marcisbee/exome/blob/main/src/utils/load-state.ts"
    click ReactIntegr "https://github.com/marcisbee/exome/blob/main/src/react.ts"
    click PreactIntegr "https://github.com/marcisbee/exome/blob/main/src/preact.ts"
    click VueIntegr "https://github.com/marcisbee/exome/blob/main/src/vue.ts"
    click SvelteIntegr "https://github.com/marcisbee/exome/blob/main/src/svelte.ts"
    click SolidIntegr "https://github.com/marcisbee/exome/blob/main/src/solid.ts"
    click LitIntegr "https://github.com/marcisbee/exome/blob/main/src/lit.ts"
    click RxjsIntegr "https://github.com/marcisbee/exome/blob/main/src/rxjs.ts"
    click AngularIntegr "https://github.com/marcisbee/exome/blob/main/src/angular.ts"
    click E2ETests "https://github.com/marcisbee/exome/tree/main/e2e"
    click Playground "https://github.com/marcisbee/exome/tree/main/playground"

    %% Styles
    classDef core fill:#FFD1DC,stroke:#333,stroke-width:2px;
    classDef middleware fill:#B3CDE0,stroke:#333,stroke-width:2px;
    classDef utility fill:#CDEAC0,stroke:#333,stroke-width:2px;
    classDef integration fill:#FDEBD0,stroke:#333,stroke-width:2px;
    classDef testing fill:#D6EAF8,stroke:#333,stroke-width:2px;
```
