# workiva/over_react architecture

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

- Interactive diagram: https://gitdiagram.com/workiva/over_react
- Repository: https://github.com/workiva/over_react

## Overview

##### Project Type & Purpose
- OverReact is an open-source Dart library/framework for authoring statically-typed React UI components.
- It comprises:
- A core runtime library (over_react) exposing UiFactory/UiProps/UiComponent2 abstractions
- An OverReact Redux extension for state management
- A build_runner “builder” plugin that parses Dart code and generates `.g.dart` artifacts
- An analyzer_plugin providing IDE linting & assists
- Extensive documentation, examples, and a test harness

##### Directory Structure & Architectural Layers
- Top-level modules:
- `lib/` – Core library code, split into subpackages:
– `builder/` (codegen entrypoints + AST parsing + generator)
– `component/` (runtime component classes, mixins)
– `component_declaration/` (UiFactory / builder DSL annotations)
– `over_react_redux/` (Redux connectors, hooks, devtools middleware)
– `util/` (DOM interop, CSS utils, promise interop, debug tools)
- `tools/analyzer_plugin/` – Dart analysis server plugin for OverReact-specific diagnostics
- `app/over_react_redux/todo_client/` – sample Todo app demonstrating usage
- `example/`, `web/` – multiple demonstration apps (builder, hooks, suspense, component demos)
- `test/` + `test_fixtures/` – unit/integration tests for library & plugins
- `doc/` + `CHANGELOG.md` + `CONTRIBUTING.md` – documentation & contributor guides

##### Core Components & Interactions
- Developer Code (e.g., `app/...`, `example/...`, user’s own app)
→ imports `package:over_react/over_react.dart` & optionally `over_react_redux.dart`
→ annotates components with mixins and `UiFactory` definitions
- Build System (`build_runner`)
→ invokes OverReact “builder” (configured via `build.yaml`)
→ Builder parses developer Dart AST (via `lib/src/builder/parsing`)
→ Generates `.over_react.g.dart` files (`lib/src/builder/codegen` modules)
- Analyzer Plugin (IDE)
→ Reads code + generated parts to provide lints, code fixes, assists
→ Lives under `tools/analyzer_plugin` and plugs into the Dart Analysis Server
- Runtime
→ Dart2JS/Dart VM executes compiled code
→ OverReact runtime classes (UiComponent2, Dom builders, Redux connectors)
→ Interops with React.JS and ReactDOM (via `react.dart` and JS interop)
- OverReact Redux
→ Provides `Provider` components, hooks (`useSelector`, `useDispatch`), middleware
→ Integrates with external Redux store implementations

##### Architectural Patterns & Design Principles
- Layered Architecture:
1. DSL Layer – UiFactory/UiProps/UiState mixin declarations
2. Codegen Layer – AST parsing + code generation
3. Runtime Layer – component base classes + utilities + interop
4. External Facades – react-dart, React.JS, Redux libraries
- Plugin Pattern: builder and analyzer are pluggable into the standard Dart toolchain
- Fluent Interface & Builder Pattern: component instantiation via cascading setters
- Separation of Concerns: parsing, codegen, runtime, tooling (IDE plugin) are distinct

##### Elements
- Developer Application (e.g., Todo Client or any user app)
- OverReact Core Library (split into Runtime, DSL, Util)
- OverReact Redux Extension
- Build Runner & OverReact Builder
- Analyzer Plugin (IDE)
- External Dependencies: react-dart, React.JS, Redux, Dart2JS/Dart VM
- Developer Code → imports → OverReact DSL/Runtimes
- build_runner → invokes → Builder → generates → `.g.dart` files
- IDE (Analysis Server) → loads → Analyzer Plugin → provides → lints/assists
- Compilation → Dart2JS → JavaScript → ReactJS runtime → browser DOM
- OverReact Redux connects Developer Code to external Redux Stores
- Visual Aids:
– Tooling (builder/analyzer) in one hue
– Runtime libraries in another
– External dependencies in a third
– Rectangles for code modules
– Clouds for external libraries/services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Application
    subgraph "Developer Application" 
        DevApp["Sample Todo Client App"]:::frontend
    end
    click DevApp "https://github.com/workiva/over_react/blob/master/app/over_react_redux/todo_client/lib/todo_client.dart"

    %% OverReact Core Library
    subgraph "OverReact Core Library"
        OREntry["Entry Points\nover_react.dart\ncomponent_base.dart\ncomponents.dart"]:::runtime
        DSL["DSL Layer\n(UiFactory/Props)"]:::dsl
        RuntimeLayer["Runtime Layer\n(UiComponent2, Components)"]:::runtime
        Util["Util Layer\n(dom_util, js_component, css utils)"]:::util
    end
    click OREntry "https://github.com/workiva/over_react/blob/master/lib/over_react.dart"
    click DSL "https://github.com/workiva/over_react/blob/master/lib/src/component_declaration/annotations.dart"
    click RuntimeLayer "https://github.com/workiva/over_react/tree/master/lib/src/component/"
    click Util "https://github.com/workiva/over_react/blob/master/lib/src/util/dom_util.dart"

    %% OverReact Redux Extension
    subgraph "OverReact Redux Extension"
        ReduxAPI["Public API"]:::runtime
        Connectors["Connector & Middleware"]:::runtime
        Hooks["Hooks"]:::runtime
    end
    click ReduxAPI "https://github.com/workiva/over_react/blob/master/lib/over_react_redux.dart"
    click Connectors "https://github.com/workiva/over_react/blob/master/lib/src/over_react_redux/redux_multi_provider.dart"
    click Hooks "https://github.com/workiva/over_react/blob/master/lib/src/over_react_redux/hooks/use_selector.dart"

    %% Build Pipeline
    subgraph "Build Pipeline"
        BuildRunner["build_runner"]:::tooling
        Builder["OverReact Builder"]:::tooling
        Parsing["AST Parsing"]:::tooling
        CodeGen["Code Generation"]:::tooling
        Generated[".over_react.g.dart Artifacts"]:::code
    end
    click Builder "https://github.com/workiva/over_react/blob/master/lib/src/builder/builder.dart"
    click Parsing "https://github.com/workiva/over_react/tree/master/lib/src/builder/parsing/"
    click CodeGen "https://github.com/workiva/over_react/tree/master/lib/src/builder/codegen/"

    %% Analyzer Plugin
    subgraph "Analyzer Plugin"
        PluginBootstrap["Plugin Bootstrap"]:::tooling
        Assist["Assist Providers"]:::tooling
        Diagnostics["Diagnostics Contributors"]:::tooling
    end
    click PluginBootstrap "https://github.com/workiva/over_react/blob/master/tools/analyzer_plugin/bin/plugin.dart"
    click Assist "https://github.com/workiva/over_react/tree/master/tools/analyzer_plugin/lib/src/assist/"
    click Diagnostics "https://github.com/workiva/over_react/tree/master/tools/analyzer_plugin/lib/src/diagnostic/"

    %% Support Resources
    subgraph "Support Resources"
        Examples["Examples & Demos"]:::example
        Docs["Documentation & Guides"]:::example
        Tests["Test Suite"]:::example
    end
    click Examples "https://github.com/workiva/over_react/tree/master/example/"
    click Docs "https://github.com/workiva/over_react/tree/master/doc/"
    click Tests "https://github.com/workiva/over_react/tree/master/test/"

    %% External Dependencies & Compile
    ReactDart["react-dart"]:::external
    Compile["Compile (Dart2JS / VM)"]:::external
    ReactJS["React.JS"]:::external
    ReduxLib["Redux Library"]:::external
    Browser["Browser DOM"]:::external
    DevIDE["IDE (Analysis Server)"]:::external

    %% Relationships
    DevApp -->|"imports"| OREntry
    DevApp -->|"imports"| DSL
    DevApp -->|"imports"| RuntimeLayer
    DevApp -->|"uses"| Hooks
    DevApp -->|"uses"| ReduxAPI
    DevApp -->|"source to build_runner"| BuildRunner

    BuildRunner -->|"invokes"| Builder
    Builder -->|"parses AST"| Parsing
    Parsing -->|"feeds"| CodeGen
    CodeGen -->|"generates"| Generated
    Generated -->|"used by compile"| Compile

    Compile -->|"interops"| ReactDart
    ReactDart -->|"calls"| ReactJS
    ReactJS -->|"renders"| Browser

    RuntimeLayer --> ReactDart
    ReduxAPI --> ReduxLib
    Hooks --> ReduxLib
    Connectors --> ReduxLib
    DevApp -->|"connects via"| Connectors

    DevIDE -->|"loads plugin"| PluginBootstrap
    PluginBootstrap -->|"provides"| Assist
    PluginBootstrap -->|"provides"| Diagnostics
    Assist -->|"reports to"| DevIDE
    Diagnostics -->|"reports to"| DevIDE

    %% Styles
    classDef frontend fill:#E8F1FF,stroke:#333,stroke-width:1px
    classDef dsl fill:#FFF5E1,stroke:#333,stroke-width:1px
    classDef runtime fill:#E2F7E1,stroke:#333,stroke-width:1px
    classDef util fill:#E1F0F7,stroke:#333,stroke-width:1px
    classDef tooling fill:#FDDDE6,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef code fill:#FFEFD5,stroke:#333,stroke-width:1px
    classDef example fill:#FFF0E1,stroke:#333,stroke-width:1px
```
