# migueldelmazo/wu architecture

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

- Interactive diagram: https://gitdiagram.com/migueldelmazo/wu
- Repository: https://github.com/migueldelmazo/wu

## Overview

##### Project type and purpose
- This is a **JavaScript framework library** (usable in browser or Node.js), not a deployed application.  Its goal is to provide a **reactive data model** and a **declarative API** (ensurer, watcher, getter, setter, router, api) for building web apps.
- The README confirms this: it’s a proof-of-concept framework in beta, focused on model consistency and functional programming.

##### File structure
- Top-level directories:
- `src/` – all core modules
- `docs/` – user documentation
- `resources/` – static assets (logo)
- `src/tests/` – unit tests
- Core files in `src/`:
- **Core orchestration**: `index.js`, `definition.js`, `common.js`, `model.js`
- **Item implementations**:
– `ensurer.js`
– `watcher.js`
– `getter.js`
– `setter.js`
– `router.js`
– `api.js` plus related submodules (`api-cache.js`, `api-queue.js`, `api-flags.js`, `api-online.js`, `api-handlers.js`)
- Utility: `lodash.js` (embedded dependency)

##### Key insights from README
- **Reactive Data Model** (`wu.model`): central “state store” with watchable paths.
- **Declarative Items**: 6 types, each defined via `wu.create(type, name, props)`.
- **Event‐Driven Flow**: changes in model → trigger ensurers, watchers, api, router → those may update model again or call externals.
- **Public API**: `wu.create()`, `wu.start()`, `wu.getter()`, `wu.setter()`, plus `wu.model.*`.

##### Main components & interactions
1. **Public API Layer** (exposed to app code)
- wu.create(), wu.start(), wu.getter(), wu.setter(), wu.model.{get,set,watch,stopWatching,populate}
2. **Definition & Bootstrapping**
- `definition.js` – reads `create()` calls, registers items
- `index.js` – initialises the model, starts the watcher loop
3. **Core Reactive Data Model**
- `model.js` – in-memory store, path-based getter/setter, event bus for onChange
4. **Item Handlers**
- Ensurer (`ensurer.js`)
- Watcher (`watcher.js`)
- Getter (`getter.js`)
- Setter (`setter.js`)
- Router (`router.js`)
- API (`api.js` + `api-cache`, `api-queue`, `api-flags`, `api-online`, `api-handlers`)
5. **Utilities**
- `common.js` – shared helper functions
- `lodash.js` – third-party util functions
6. **External Environment**
- Browser/Node runtime
- HTTP endpoints (API server)
- Third‐party libraries (e.g. React via watcher)
b. Relationships & data flow
- **App code** calls `wu.create()` → registers item in Definition
- **Model** emits “change” events when `wu.model.set()` is invoked
- **Item Handler** subscribes to model paths (`onChange`):
- Ensurer/getter/setter/router/api/watchers all register callbacks
- **When triggered**:
- **Ensurer** runs pure function → calls `model.set(updatePath)`
- **Watcher** runs impure function → calls external API or DOM/React
- **Getter** defines read-only function for app to call (`wu.getter()`)
- **Setter** accepts app input, runs pure function → `model.set(updatePath)`
- **Router** listens to URL changes, updates model
- **API** pipeline: onChange → request (via `api-handlers`) → queue/cache → network → response → `model.set()` on success or error
- The cycle may repeat if those `model.set()` calls trigger other items.
c. Architectural patterns & principles
- **Observer pattern**: model as subject, items as observers
- **Functional/reactive style**: pure functions except watchers, single source of truth
- **Modular design**: 1 file per item, clear separation of concerns
- **Declarative registration**: users declare items, framework wires them up
d. Key technologies
- Vanilla JS (ES6 modules), no runtime dependencies except Lodash

##### Final advice
- How the **reactive loop** works: model change → triggers → model change → …

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public API Layer
    subgraph "Public API Layer"
        PublicAPI["Public API\nwu.create(), wu.start(),\nwu.getter(), wu.setter(),\nwu.model.*"]:::public
    end

    %% Definition & Bootstrapping
    subgraph "Definition & Bootstrapping"
        Definition["definition.js\n(register items)"]:::core
    end

    %% Core Reactive Data Model
    subgraph "Core Reactive Data Model"
        Model[(Reactive Data Store\nmodel.js)]:::core
    end

    %% Item Handlers
    subgraph "Item Handlers"
        Ensurer["Ensurer\nensurer.js"]:::handler
        Watcher["Watcher\nwatcher.js"]:::handler
        Getter["Getter\ngetter.js"]:::handler
        Setter["Setter\nsetter.js"]:::handler
        Router["Router\nrouter.js"]:::handler
        subgraph "API Module"
            APICore["API Core\napi.js"]:::handler
            APICache["API Cache\napi-cache.js"]:::handler
            APIQueue["API Queue\napi-queue.js"]:::handler
            APIFlags["API Flags\napi-flags.js"]:::handler
            APIOnline["API Online\napi-online.js"]:::handler
            APIHandlers["API Handlers\napi-handlers.js"]:::handler
        end
    end

    %% Utilities
    subgraph "Utilities"
        Common["common.js"]:::util
        Lodash["lodash.js"]:::util
    end

    %% External Environment
    subgraph "External Environment"
        Browser["Browser/Node Runtime"]:::external
        HTTP["HTTP Endpoints"]:::external
        ReactExt["Third-party Libs\n(e.g. React)"]:::external
    end

    %% Connections
    PublicAPI -->|"calls wu.create()"| Definition
    Definition -->|"initializes"| Model

    Model -->|"onChange event"| Ensurer
    Model -->|"onChange event"| Watcher
    Model -->|"onChange event"| Getter
    Model -->|"onChange event"| Setter
    Model -->|"onChange event"| Router
    Model -->|"onChange event"| APICore

    Ensurer -->|"model.set()"| Model
    Setter -->|"model.set()"| Model
    Router -->|"model.set()"| Model

    Watcher -->|"run side-effect"| ReactExt

    APICore -->|"pipeline start"| APIHandlers
    APIHandlers -->|"enqueue"| APIQueue
    APIQueue -->|"cache/store flags"| APICache
    APIQueue -->|"check online"| APIFlags
    APIFlags -->|"go online"| APIOnline
    APIOnline -->|"HTTP request"| HTTP
    HTTP -->|"response"| APICore
    APICore -->|"model.set()"| Model

    Browser -->|"URL change"| Router

    %% Utility usage
    Definition --> Common
    Model --> Common
    Ensurer --> Common
    Watcher --> Common
    Getter --> Common
    Setter --> Common
    Router --> Common
    APICore --> Common

    Definition --> Lodash
    Model --> Lodash
    Ensurer --> Lodash
    Watcher --> Lodash
    Getter --> Lodash
    Setter --> Lodash
    Router --> Lodash
    APICore --> Lodash

    %% Click Events
    click PublicAPI "https://github.com/migueldelmazo/wu/blob/master/src/index.js"
    click Definition "https://github.com/migueldelmazo/wu/blob/master/src/definition.js"
    click Model "https://github.com/migueldelmazo/wu/blob/master/src/model.js"
    click Ensurer "https://github.com/migueldelmazo/wu/blob/master/src/ensurer.js"
    click Watcher "https://github.com/migueldelmazo/wu/blob/master/src/watcher.js"
    click Getter "https://github.com/migueldelmazo/wu/blob/master/src/getter.js"
    click Setter "https://github.com/migueldelmazo/wu/blob/master/src/setter.js"
    click Router "https://github.com/migueldelmazo/wu/blob/master/src/router.js"
    click APICore "https://github.com/migueldelmazo/wu/blob/master/src/api.js"
    click APICache "https://github.com/migueldelmazo/wu/blob/master/src/api-cache.js"
    click APIQueue "https://github.com/migueldelmazo/wu/blob/master/src/api-queue.js"
    click APIFlags "https://github.com/migueldelmazo/wu/blob/master/src/api-flags.js"
    click APIOnline "https://github.com/migueldelmazo/wu/blob/master/src/api-online.js"
    click APIHandlers "https://github.com/migueldelmazo/wu/blob/master/src/api-handlers.js"
    click Common "https://github.com/migueldelmazo/wu/blob/master/src/common.js"
    click Lodash "https://github.com/migueldelmazo/wu/blob/master/src/lodash.js"

    %% Styles
    classDef public fill:#FFA500,stroke:#333,stroke-width:2px
    classDef core fill:#1E90FF,stroke:#333,stroke-width:2px
    classDef handler fill:#32CD32,stroke:#333,stroke-width:2px
    classDef util fill:#A9A9A9,stroke:#333,stroke-width:2px
    classDef external fill:#9370DB,stroke:#333,stroke-width:2px
```
