# yaser2us/dynamo architecture

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

- Interactive diagram: https://gitdiagram.com/yaser2us/dynamo
- Repository: https://github.com/yaser2us/dynamo

## Overview

##### Project type and purpose
- **Type**: This is a frontend‐focused UI library/engine for dynamic form/page generation, published as an NPM package (“dynamo”) and demonstrated via two sample clients (a React web app under `example/` and a React Native mobile app under `exampleRN/`).
- **Purpose**: Provide a low-code, data-driven rendering engine that takes a JSON “items” array plus a components‐dictionary/renderer and produces dynamic, validated UI on web or mobile.

##### File structure
- **Top-level modules**:
- `src/` – core engine source
– `builder/` – FormBuilder versions (V1..V5), entry in `index.js`
– `controller.js` – orchestration of form state, refs, callbacks
– `logic/` – pure functions: validation, value getters/setters, rendering decisions
– `middleware/` – data/schema transformers & proxy setup
– `tools/` – hooks (`useHistory`, transformer), utilities for runtime
– root hooks: `useForm`, `useFormContext`, `useController`, `useFieldArray`, etc.
– `utils/` – generic helpers (deepMerge, debounce, jsonata integration, subjects/observables).
- `dist/` – compiled outputs (`index.js`, `index.modern.js` + maps + CSS) consumed by clients
- **Examples**:
- `example/` – React web demo (App.js + Components folder)
- `exampleRN/` – React Native demo with full Android/iOS configs
- **Configs**: `.gitignore`, `package.json`, `README.md`, LICENSE.

##### README for architectural insights
- Data-driven model: JSON array → engine
- Component dictionary → rendering
- Rendering callback → optional container injection
- Managed callbacks → form-level actions (submit, getValues)
- Custom onChange override, runtime prop injection (`field`, `item`, `error`).

##### Main components & interactions (
a. **Clients**:
- React Web App (`example/`)
- React Native App (`exampleRN/`)
b. **Dynamo Engine (npm package)**:
1. **API Layer** (`DynoBuilder` entrypoint)
- Accepts props: `items` (JSON schema), `components` (render fn), `managedCallback`
2. **Builder Module** (`src/builder`)
- Transforms JSON schema into form control definitions
3. **Controller** (`src/controller.js`)
- Manages form state, refs, effects, exposes `getValues()`, `reset()`, etc.
4. **Logic Layer** (`src/logic`)
- Validation routines, value extraction, visibility logic, preconditions
5. **Middleware** (`src/middleware`)
- Schema/data transformers, proxies for runtime enhancements
6. **Render Pipeline**
- For each element: apply middleware → builder output → lookup in `componentsDictionary` → wrap with container (optional) → render React element
7. **Hooks & Tools** (`src/tools`, root hooks)
- Provide React hooks (`useForm`, `useWatch`, etc.) for fine-grained state access
8. **Utilities** (`src/utils`)
- Shared helper functions (e.g., `deepMerge`, `debounce`, `Subject` for event pub/sub)
c. **External Dependencies**:
- React / React Native
- Third-party UI components (Button, Checkbox, Select, etc.)
- JSONATA (optional custom validation/resolvers)
d. **Build & Distribution**:
- Rollup/Babel build produces `dist/` bundles
- CSS shipped as `dist/index.css`

##### Architectural patterns/design principles
- **Inversion of Control**: client supplies `components` / render callback
- **Data-driven UI**: JSON schema dictates structure
- **Middleware Pipeline**: transformations & proxies before rendering
- **Separation of Concerns**:
- Builder transforms schema → definitions
- Controller handles state & APIs
- Logic layer pure functions
- Render layer deals only with React elements
- **Extensibility**: multiple FormBuilder versions, inject custom middleware/hooks

##### Detailed capture of essential elements
- JSON “items” schema entering the pipeline, and form values exiting via `getValues()`

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        Web["React Web Client"]:::client
        Mobile["React Native Client"]:::client
    end

    subgraph "Dynamo Engine (npm package)"
        API["DynoBuilder API Layer"]:::core

        subgraph "Core Pipeline"
            Builder["Builder Module"]:::core
            Controller["Controller Module"]:::core
            Logic["Logic Layer"]:::core
            Middleware["Middleware Layer"]:::middleware
            Render["Render Pipeline"]:::core
        end

        subgraph "Support Modules"
            Hooks["Hooks & Tools"]:::util
            Utils["Utilities"]:::util
        end
    end

    subgraph "UI Targets"
        WebUI["React DOM"]:::external
        MobileUI["Native UI"]:::external
    end

    External["External Dependencies"]:::external
    Dist["Distribution Bundle"]:::dist

    Web -->|calls| API
    Mobile -->|calls| API
    Dist -->|provides bundle| Web
    Dist -->|provides bundle| Mobile
    API -->|transforms schema| Builder
    Builder -->|defines controls| Controller
    Controller -->|manages state| Logic
    Logic -->|applies validation| Middleware
    Middleware -->|enhances data| Render
    Render -->|renders elements| WebUI
    Render -->|renders elements| MobileUI

    Hooks -->|provides hooks| Controller
    Hooks -->|provides hooks| Render
    Utils -->|shared helpers| Builder
    Utils -->|shared helpers| Logic
    Utils -->|shared helpers| Middleware

    External -->|used by| Logic
    External -->|used by| Render

    click Web "https://github.com/yaser2us/dynamo/blob/main/example/src/App.js"
    click Mobile "https://github.com/yaser2us/dynamo/blob/main/exampleRN/App.js"
    click API "https://github.com/yaser2us/dynamo/blob/main/src/index.js"
    click Builder "https://github.com/yaser2us/dynamo/blob/main/src/builder/index.js"
    click Controller "https://github.com/yaser2us/dynamo/blob/main/src/controller.js"
    click Logic "https://github.com/yaser2us/dynamo/blob/main/src/logic/index.js"
    click Middleware "https://github.com/yaser2us/dynamo/blob/main/src/middleware/index.js"
    click Hooks "https://github.com/yaser2us/dynamo/blob/main/src/tools/index.js"
    click Utils "https://github.com/yaser2us/dynamo/blob/main/src/utils/index.js"
    click Dist "https://github.com/yaser2us/dynamo/blob/main/dist/index.js"

    classDef core fill:#bbdefb,stroke:#0d47a1
    classDef client fill:#c8e6c9,stroke:#2e7d32
    classDef middleware fill:#ffe0b2,stroke:#e65100
    classDef util fill:#d7ccc8,stroke:#4e342e
    classDef external fill:#eeeeee,stroke:#757575
    classDef dist fill:#f3e5f5,stroke:#6a1b9a
```
