# legendapp/legend-state architecture

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

- Interactive diagram: https://gitdiagram.com/legendapp/legend-state
- Repository: https://github.com/legendapp/legend-state

## Overview

##### Main Components

a) Core State Management Layer
- Observable System
- ObservableObject
- ObservablePrimitive
- Computed Observables
- Tracking System
- Batching System
- Event System

b) React Integration Layer
- React Hooks
- React Components
- Reactive Components
- Observer System

c) Sync/Persistence Layer
- Sync Engine
- Persistence Plugins
- Sync Plugins
- Retry/Recovery System

**┌─────────────────────────────────────────┐**
- Application Layer            │
- (React Components & Custom Hooks)      │
- ┘
- ↕️
**┌─────────────────────────────────────────┐**
- State Management Core           │
- (Observables, Computed, Tracking)      │
- ┘
- ↕️
**┌─────────────────────────────────────────┐**
- Sync & Persistence Layer        │
- (Storage Plugins, Sync Providers)      │
- ┘

##### Detailed Component Relationships

a) State Management Core:
- Observable system at the center
- Tracking system with connections to all observable types
- Batching system interaction with state updates

b) React Integration:
- Hooks connecting to the core observable system
- Reactive components with their update paths
- Observer pattern implementation

c) Sync/Persistence:
- Plugin architecture for different storage solutions (IndexedDB, LocalStorage, etc.)
- Sync providers (Keel, Supabase, TanStack Query)
- Retry/recovery flow with optimistic updates

##### Special Features to Highlight

- Fine-grained reactivity system
- Optimistic updates in sync layer
- Plugin architecture for storage/sync
- Performance optimization paths

##### Elements

- State update cycle visualization
- Plugin connection points
- Error handling/retry paths
- Storage/sync plugin options

##### Additional Notes

- Version information
- Performance optimization points
- Integration points with React ecosystem

- Minimal boilerplate
- High performance
- Fine-grained reactivity
- Flexible sync/persistence system

Remember to maintain a balance between showing the sophisticated architecture while keeping it clear and understandable. Focus on the three main layers (Application, State Management, Sync/Persistence) while showing how they interact seamlessly.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef core fill:#2196F3,color:white
    classDef react fill:#4CAF50,color:white
    classDef sync fill:#FF9800,color:white
    classDef external fill:#9E9E9E,color:white

    subgraph Application["Application Layer"]
        ReactComponents["React Components"]:::react
        ReactHooks["React Hooks"]:::react
        ReactiveComponents["Reactive Components"]:::react
    end

    subgraph Core["State Management Core"]
        ObservableSystem["Observable System"]:::core
        TrackingSystem["Tracking System"]:::core
        BatchingSystem["Batching System"]:::core
        EventSystem["Event System"]:::core
        
        subgraph ObservableTypes["Observable Types"]
            ObservableObject["Observable Object"]:::core
            ObservablePrimitive["Observable Primitive"]:::core
            ComputedObservables["Computed Observables"]:::core
        end
    end

    subgraph SyncLayer["Sync & Persistence Layer"]
        SyncEngine["Sync Engine"]:::sync
        
        subgraph Plugins["Plugin Systems"]
            PersistencePlugins["Persistence Plugins"]:::sync
            SyncPlugins["Sync Plugins"]:::sync
        end
        
        RetrySystem["Retry/Recovery System"]:::sync
    end

    %% Relationships
    ReactComponents --> ObservableSystem
    ReactHooks --> ObservableSystem
    ReactiveComponents --> ObservableSystem
    
    ObservableSystem --> ObservableTypes
    ObservableTypes --> TrackingSystem
    TrackingSystem --> BatchingSystem
    BatchingSystem --> EventSystem
    
    ObservableSystem --> SyncEngine
    SyncEngine --> Plugins
    SyncEngine --> RetrySystem
    RetrySystem --> ObservableSystem

    %% Click events
    click ObservableSystem "https://github.com/LegendApp/legend-state/blob/main/src/observable.ts"
    click ObservableObject "https://github.com/LegendApp/legend-state/blob/main/src/ObservableObject.ts"
    click ObservablePrimitive "https://github.com/LegendApp/legend-state/blob/main/src/ObservablePrimitive.ts"
    click TrackingSystem "https://github.com/LegendApp/legend-state/blob/main/src/tracking.ts"
    click BatchingSystem "https://github.com/LegendApp/legend-state/blob/main/src/batching.ts"
    click EventSystem "https://github.com/LegendApp/legend-state/blob/main/src/event.ts"
    click ReactComponents "https://github.com/LegendApp/legend-state/tree/main/src/react"
    click ReactHooks "https://github.com/LegendApp/legend-state/tree/main/src/react-hooks"
    click ReactiveComponents "https://github.com/LegendApp/legend-state/tree/main/src/react-reactive"
    click SyncEngine "https://github.com/LegendApp/legend-state/blob/main/src/sync/syncObservable.ts"
    click PersistencePlugins "https://github.com/LegendApp/legend-state/tree/main/src/persist-plugins"
    click SyncPlugins "https://github.com/LegendApp/legend-state/tree/main/src/sync-plugins"
    click RetrySystem "https://github.com/LegendApp/legend-state/blob/main/src/sync/retry.ts"

    %% Legend
    subgraph Legend
        CoreLegend["Core Components"]:::core
        ReactLegend["React Integration"]:::react
        SyncLegend["Sync Components"]:::sync
        ExternalLegend["External Systems"]:::external
    end
```
