# ngneat/elf architecture

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

- Interactive diagram: https://gitdiagram.com/ngneat/elf
- Repository: https://github.com/ngneat/elf

## Overview

##### Project Type and Purpose
- This is an open-source, monorepo library (“Elf”) providing a reactive, immutable state management solution for JavaScript/TypeScript apps.
- It publishes multiple npm packages (core store + extensions: entities, requests, pagination, persist-state, state-history, devtools) and CLI tools, and includes example Angular and React applications and a Docusaurus-based docs site.

##### File Structure Analysis
- Root: linting, formatting, CI/CD, NX/monorepo config.
- apps/
- ng – Angular example uses `@ngneat/elf` packages.
- react – React/TS example.
- docs/ – Docusaurus site source + built static assets.
- packages/ – each directory is a published package:
- store (core), entities, pagination, requests, persist-state, state-history, devtools, mocks.
- cli & cli-ng – interactive code generators.
- Shared config (tsconfig.base.json), test runner (jest), changelog, CI workflows, CONTRIBUTING, LICENSE, etc.

##### README Insights
- Core pillars: modular design, tree-shakeable, fully typed.
- Highlights features as independent packages.
- CLI for scaffolding state logic.
- Example usage in Angular/React.

##### Detailed Component Breakdown
- Monorepo Root: holds config, CI definitions, workspace settings.
- Core Store (`packages/store`): base reactive store.
- Entities & other feature packages: plug into Core via withEntities(), withRequests(), etc.
- CLI (`packages/cli`, `packages/cli-ng`): generates repository and feature code using builders.
- Devtools: optional runtime tools to inspect store.
- Example Apps (apps/ng, apps/react): demonstration clients illustrating import and usage patterns.
- Docs (docs/): source MDX/content, tooling to publish site.

## Diagram (Mermaid)

```mermaid
flowchart TD
    root["Monorepo Root"]:::root

    subgraph "Packages"
        store["@ngneat/elf-store"]:::package
        entities["@ngneat/elf-entities"]:::package
        requests["@ngneat/elf-requests"]:::package
        pagination["@ngneat/elf-pagination"]:::package
        persistState["@ngneat/elf-persist-state"]:::package
        stateHistory["@ngneat/elf-state-history"]:::package
        devtools["@ngneat/elf-devtools"]:::package
    end

    subgraph "CLI Tools"
        cli["elf-cli"]:::cli
        cliNg["elf-cli-ng"]:::cli
    end

    subgraph "Example Apps"
        ngApp["Angular Example App"]:::app
        reactApp["React Example App"]:::app
    end

    docs["Documentation Site (Docusaurus)"]:::docs

    ciMain["CI Pipeline"]:::ci
    ciDocs["Docs Pipeline"]:::ci

    npm["npm Registry"]:::external

    %% Dependencies: Extensions -> Core
    entities -->|imports| store
    requests -->|imports| store
    pagination -->|imports| store
    persistState -->|imports| store
    stateHistory -->|imports| store
    devtools -->|imports| store

    %% Apps import Core & Extensions
    ngApp -->|imports| store
    ngApp -->|imports| entities
    ngApp -->|imports| requests
    ngApp -->|imports| pagination
    ngApp -->|imports| persistState
    ngApp -->|imports| stateHistory
    ngApp -->|imports| devtools

    reactApp -->|imports| store
    reactApp -->|imports| entities
    reactApp -->|imports| requests
    reactApp -->|imports| pagination
    reactApp -->|imports| persistState
    reactApp -->|imports| stateHistory
    reactApp -->|imports| devtools

    %% CLI code generation
    cli -.->|generates code for| ngApp
    cli -.->|generates code for| reactApp
    cliNg -.->|generates code for| ngApp

    %% Docs imports packages
    docs -->|uses metadata| store
    docs -->|uses metadata| entities
    docs -->|uses metadata| requests
    docs -->|uses metadata| pagination
    docs -->|uses metadata| persistState
    docs -->|uses metadata| stateHistory
    docs -->|uses metadata| devtools

    %% CI/CD pipelines
    ciMain -->|runs build/test| store
    ciMain -->|runs build/test| entities
    ciMain -->|runs build/test| requests
    ciMain -->|runs build/test| pagination
    ciMain -->|runs build/test| persistState
    ciMain -->|runs build/test| stateHistory
    ciMain -->|runs build/test| devtools
    ciMain -->|runs build/test| cli
    ciMain -->|runs build/test| cliNg
    ciMain -->|runs build/test| ngApp
    ciMain -->|runs build/test| reactApp
    ciMain -.->|publishes to| npm

    ciDocs -->|builds & deploys| docs

    %% Click Events
    click root "https://github.com/ngneat/elf/tree/master//"
    click ciMain "https://github.com/ngneat/elf/blob/master/.github/workflows/ci.yml"
    click ciDocs "https://github.com/ngneat/elf/blob/master/.github/workflows/docs.yml"
    click store "https://github.com/ngneat/elf/tree/master/packages/store"
    click entities "https://github.com/ngneat/elf/tree/master/packages/entities"
    click requests "https://github.com/ngneat/elf/tree/master/packages/requests"
    click pagination "https://github.com/ngneat/elf/tree/master/packages/pagination"
    click persistState "https://github.com/ngneat/elf/tree/master/packages/persist-state"
    click stateHistory "https://github.com/ngneat/elf/tree/master/packages/state-history"
    click devtools "https://github.com/ngneat/elf/tree/master/packages/devtools"
    click cli "https://github.com/ngneat/elf/tree/master/packages/cli"
    click cliNg "https://github.com/ngneat/elf/tree/master/packages/cli-ng"
    click ngApp "https://github.com/ngneat/elf/tree/master/apps/ng"
    click reactApp "https://github.com/ngneat/elf/tree/master/apps/react"
    click docs "https://github.com/ngneat/elf/tree/master/docs"

    %% Styles
    classDef package fill:#cce5ff,stroke:#004085
    classDef app fill:#d4edda,stroke:#155724
    classDef docs fill:#fff3cd,stroke:#856404
    classDef cli fill:#e2e3e5,stroke:#6c757d
    classDef ci fill:#e2e3e5,stroke:#6c757d
    classDef root fill:#d1ecf1,stroke:#0c5460
    classDef external fill:#f8d7da,stroke:#721c24
```
