# cvdlab/react-planner architecture

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

- Interactive diagram: https://gitdiagram.com/cvdlab/react-planner
- Repository: https://github.com/cvdlab/react-planner

## Overview

This project is a React‐based building model planner called “react-planner.” Its goal is to let users drag & drop building elements from a catalog, creating 2D wireframes that can be transformed into 3D models. The source code, organized in multiple layers (src, es, and lib), follows a flux/redux architecture designed around React components, actions, reducers, and a plugin mechanism.

##### Main system components
- User Interface Layer: At the core is the ReactPlanner component. This composite component consists of various child UI elements such as the 2D and 3D viewers, sidebars, toolbars, and configurators.
- State Management: The project uses Redux (or a similar flux pattern) to maintain application state. This includes actions (in actions directories), reducers (in reducers directories), and the overall store that holds the “react-planner” state.
- Catalog System: A catalog of objects (found in the demo and catalog directories) serves as a repository of customizable building elements. Factories and properties modules in catalog directories indicate how these objects are constructed and configured.
- Rendering Engines: There are both Viewer2D and Viewer3D components that handle the graphical rendering; the 3D components even load external assets (e.g., OBJ/MTL files) and utilize libraries like Three.js (notable from files such as pointer-lock-controls.js and orbit-controls.js).
- Plugin System: The project supports plugins (Keyboard, Autosave, ConsoleDebugger, etc.), which extend the core functionality. These plugins are passed as an array to the ReactPlanner component and provide flexible enhancements to the UI and state changes.

##### Relationships and interactions
- The UI (React components) is rendered based on the state stored in Redux. Components dispatch actions (located in the “actions” directories) that are then processed by reducers to update the store.
- The Catalog interacts with the UI by providing new building elements. Factories in the catalog modules create instances of areas, holes, items, and lines.
- Plugins hook into the event system, reacting to key events and state changes to provide extra functionality (autosave, debugging, etc.).
- The Viewer2D and Viewer3D components show the plan and model, respectively. They interact with the domain model classes (area.js, group.js, etc.) and use utility functions (in utils) for geometric calculations and rendering details.

##### Architectural patterns and design principles
- Modular design: The project separates concerns by organizing actions, reducers, components, and catalog-specific modules into distinct directories.
- Flux/Redux pattern: Unidirectional data flow is enforced with actions updating the state that then triggers UI re-renders.
- Plugin extensibility: The design facilitates adding new behavior with plugins, making the system flexible.
- Component-based UI: The use of React ensures that the UI is made of small, re-usable components (sidebar, toolbar, viewer, etc.), facilitating scalability.

##### Following
– Toolbar
– Sidebar & Panel Editors (for element attributes)
– Content area (which holds the Viewer2D and Viewer3D components)
– Configurator
- A separate section for State Management / Redux showing:
– “Actions” modules dispatching events
– “Reducers” processing state changes
– The centralized “Store” (holding a “react-planner” key)
- The Catalog component, interacting with the UI, contains:
– Catalog Factories (for creating areas, holes, items, lines)
– Catalog Properties (customizable object properties)
- The Plugin System, depicted as a plug-in module connected to the ReactPlanner and to the state management, to show how external functionalities (like keyboard shortcuts, autosave, debugging) hook into core events.
- Renderers: Two distinct renderers (for 2D and 3D views). For the 3D viewer, indicate integration with 3D rendering libraries and file loaders (OBJ/MTL assets).
- Utility Libraries & Domain Classes: A layer illustrating common functionalities (geometry operations, ID generation, etc.) that support both UI rendering and the catalog object creation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["ReactPlanner Main Component"]:::ui
        UI2["Toolbar"]:::ui
        UI3["Sidebar & Panel Editors"]:::ui
        UI4["Content Area"]:::ui
        UI5["Configurator"]:::ui
        UI4A["Viewer2D"]:::ui
        UI4B["Viewer3D"]:::ui
    end

    %% State Management / Redux
    subgraph "State Management / Redux"
        STM1["Actions"]:::state
        STM2["Reducers"]:::state
        STM3["Store (react-planner)"]:::state
    end

    %% Catalog System
    subgraph "Catalog System"
        CAT1["Catalog Modules & Factories"]:::catalog
        CAT2["Catalog Properties"]:::catalog
    end

    %% Plugin System
    subgraph "Plugin System"
        PLG1["Plugins (Autosave, Debugger, Keyboard)"]:::plugin
    end

    %% Utility & Domain
    subgraph "Utility & Domain"
        UTIL1["Utilities & Domain Classes"]:::util
    end

    %% Relationships and Data Flow
    UI1 -->|"dispatch"| STM1
    STM1 -->|"process"| STM2
    STM2 -->|"update"| STM3
    STM3 -->|"stateUpdate"| UI1

    CAT1 -->|"providesElements"| UI1
    CAT2 -->|"customizesUI"| UI1

    PLG1 -->|"extendUI"| UI1
    PLG1 -->|"hookStore"| STM3

    UTIL1 -->|"supportRendering"| UI4A
    UTIL1 -->|"supportRendering"| UI4B

    UI1 -->|"contains"| UI2
    UI1 -->|"contains"| UI3
    UI1 -->|"contains"| UI4
    UI1 -->|"contains"| UI5
    UI4 -->|"comprises"| UI4A
    UI4 -->|"comprises"| UI4B

    %% Click Events
    click UI1 "https://github.com/cvdlab/react-planner/blob/master/src/react-planner.jsx"
    click UI2 "https://github.com/cvdlab/react-planner/blob/master/src/components/toolbar/toolbar.jsx"
    click UI3 "https://github.com/cvdlab/react-planner/blob/master/src/components/sidebar/sidebar.jsx"
    click UI4A "https://github.com/cvdlab/react-planner/blob/master/src/components/viewer2d/viewer2d.jsx"
    click UI4B "https://github.com/cvdlab/react-planner/blob/master/src/components/viewer3d/viewer3d.js"
    click STM1 "https://github.com/cvdlab/react-planner/tree/master/src/actions/"
    click STM2 "https://github.com/cvdlab/react-planner/tree/master/src/reducers/"
    click CAT1 "https://github.com/cvdlab/react-planner/blob/master/src/catalog/catalog.js"
    click CAT1 "https://github.com/cvdlab/react-planner/tree/master/src/catalog/factories/"
    click CAT2 "https://github.com/cvdlab/react-planner/tree/master/src/catalog/properties/"
    click PLG1 "https://github.com/cvdlab/react-planner/tree/master/src/plugins/"
    click UTIL1 "https://github.com/cvdlab/react-planner/tree/master/src/utils/"
    click UTIL1 "https://github.com/cvdlab/react-planner/tree/master/src/class/"

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:2px;
    classDef state fill:#cfc,stroke:#333,stroke-width:2px;
    classDef catalog fill:#ccf,stroke:#333,stroke-width:2px;
    classDef plugin fill:#fcf,stroke:#333,stroke-width:2px;
    classDef util fill:#cff,stroke:#333,stroke-width:2px;
```
