# optimajet/formengine architecture

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

- Interactive diagram: https://gitdiagram.com/optimajet/formengine
- Repository: https://github.com/optimajet/formengine

## Overview

1. This repository is a monorepo for FormEngine, split into a free/community codebase and a premium/examples codebase. The architectural center is a JSON-driven form runtime: form structure is described in JSON or generated from code, then rendered through a viewer/runtime plus a UI theme package.

2. The `community/src/packages/core` package is the main engine. It contains the form viewer runtime, form JSON builder, validation, localization, event handling, modal/repeater/template support, and the internal state/store layer. If you are diagramming the system, this is the hub that coordinates data, UI metadata, validation rules, and emitted actions.

3. The core runtime is intentionally UI-agnostic. It exposes abstract component definitions and a viewer API, but delegates actual controls to theme/view packages. The main data flow is: form definition in JSON or builder output -> core store/model -> viewer render tree -> component-specific props/events/validation -> user interaction back into store/actions.

4. The `community/src/packages/views/*` packages are the concrete UI adapters. There are separate packages for Mantine, Material UI, RSuite, and Uploader, each implementing component definitions, wrappers, localized descriptions, and theme-specific behaviors. These packages map core abstractions like buttons, inputs, dialogs, and containers onto each design system.

5. The view packages also define the “catalog” of supported components for each theme. That means the architecture has a clear boundary between engine and presentation: core owns semantics and runtime behavior, while views own component bindings, styling, and theme-specific props.

6. JSON schema generation is a separate subsystem. Packages like `json-schema-generator` and the per-theme `public/schemas/*.json` assets produce schema files for forms and component definitions. These are used by tooling, validation, and example apps to load or author forms consistently without coupling to runtime internals.

7. Localization is built into both core and view packages. Core ships language resources and a Fluent-based localization engine, while each theme package supplies its own UI text and component descriptions. In the runtime, localization is part of the rendering layer rather than an external concern.

8. Validation is another first-class pipeline. The core validation subsystem supports schema-driven validation rules, Zod integration, custom rules, and error rendering. Validation results flow back into the viewer/store so components can display field-level errors and control submission or custom actions.

9. The repository also contains example applications that demonstrate end-to-end consumption paths. Community examples include `example-viewer`, `formdata`, `bundle-size`, and a small file-upload server; these show how the core/view packages are embedded in real apps, how form JSON is loaded, and how file upload or bundle analysis is handled around the engine.

10. The `community/examples/bundle-size` area is a benchmarking harness, not a product feature. It compares different stacks and themes through separate mini-apps, plus build/report scripts that measure JS/CSS output and generate console/CSV/HTML/MDX/JSON reports. This subsystem is useful for architecture because it shows the library’s modular packaging and build boundaries.

11. The `premium/examples` tree demonstrates the commercial designer workflow and framework integrations. It includes separate example apps for React/Formik, Angular forms, Next.js, and Remix, all reusing shared JSON form definitions and validators. This shows the same core form model being adapted into different host frameworks and rendering environments.

12. Build and packaging are organized per package with Vite/TypeScript configs and package-local publish settings. The repo is structured as independently buildable packages rather than one monolith, which matters for architecture diagrams: each package has its own entrypoints, public assets, and schema artifacts, while the shared runtime contracts come from core.

Main entry points: [`community/src/packages/core`](https://github.com/optimajet/formengine/tree/master/community/src/packages/core) (Core), [`community/src/packages/core/src/features/form-viewer`](https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/form-viewer) (Viewer), [`community/src/packages/apps/common`](https://github.com/optimajet/formengine/tree/master/community/src/packages/apps/common) (Common app), [`community/src/packages/views/mantine`](https://github.com/optimajet/formengine/tree/master/community/src/packages/views/mantine) (Mantine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_community["Community"]
end

subgraph group_premium["Premium"]
  node_premium_examples_formengine["Premium demo<br/>designer demo"]
  node_premium_examples_with_angular_forms["Angular forms<br/>integration demos"]
  node_premium_examples_with_formik["Formik<br/>integration demo"]
  node_premium_examples_with_nextjs["Next.js<br/>integration demo"]
  node_premium_examples_with_remix["Remix<br/>integration demo"]
end

subgraph group_examples["Examples"]
  node_community_src_packages_apps_common["Common app<br/>shared app shell"]
  node_community_src_packages_apps_example_viewer["Example viewer<br/>demo app"]
  node_community_examples_formdata["Formdata<br/>demo app"]
  node_community_examples_bundle_size["Bundle size<br/>benchmark harness"]
  node_community_examples_file_upload_server["Upload server<br/>backend demo"]
end

subgraph group_runtime["Runtime"]
  node_community_src_packages_core["Core<br/>form runtime"]
  node_community_core_store[("Store<br/>state layer")]
  node_community_core_viewer["Viewer<br/>render runtime"]
  node_community_core_validation["Validation"]
  node_community_core_localization["Localization<br/>i18n engine"]
  node_community_core_events["Events<br/>action system"]
  node_community_core_builder["Form builder<br/>json builder"]
end

subgraph group_views["Views"]
  node_community_src_packages_views_mantine["Mantine<br/>theme adapter"]
  node_community_src_packages_views_material_ui["Material UI<br/>theme adapter"]
  node_community_src_packages_views_rsuite["RSuite<br/>theme adapter"]
  node_community_src_packages_views_uploader["Uploader<br/>theme adapter"]
end

subgraph group_tools["Tools"]
  node_community_src_packages_json_schema_generator["Schema gen<br/>schema tool"]
  node_community_src_packages_viewer_bundle["Viewer bundle<br/>bundle entry"]
end

node_community_core_builder -->|"builds form JSON"| node_community_src_packages_core
node_community_src_packages_core -->|"owns state"| node_community_core_store
node_community_src_packages_core -->|"drives render"| node_community_core_viewer
node_community_src_packages_core -->|"validates"| node_community_core_validation
node_community_src_packages_core -->|"localizes"| node_community_core_localization
node_community_src_packages_core -->|"emits actions"| node_community_core_events
node_community_core_viewer -->|"adapts to theme"| node_community_src_packages_views_mantine
node_community_core_viewer -->|"adapts to theme"| node_community_src_packages_views_material_ui
node_community_core_viewer -->|"adapts to theme"| node_community_src_packages_views_rsuite
node_community_core_viewer -->|"adapts to theme"| node_community_src_packages_views_uploader
node_community_src_packages_views_mantine -->|"supplies text"| node_community_core_localization
node_community_src_packages_views_material_ui -->|"supplies text"| node_community_core_localization
node_community_src_packages_views_rsuite -->|"supplies text"| node_community_core_localization
node_community_src_packages_views_uploader -->|"supplies text"| node_community_core_localization
node_community_src_packages_json_schema_generator -->|"generates schema"| node_community_src_packages_views_material_ui
node_community_src_packages_json_schema_generator -->|"generates schema"| node_community_src_packages_views_rsuite
node_community_src_packages_json_schema_generator -->|"generates schema"| node_community_src_packages_views_uploader
node_community_src_packages_apps_common -->|"uses core"| node_community_src_packages_core
node_community_src_packages_apps_common -->|"uses theme"| node_community_src_packages_views_mantine
node_community_src_packages_apps_common -->|"uses theme"| node_community_src_packages_views_material_ui
node_community_src_packages_apps_common -->|"uses theme"| node_community_src_packages_views_rsuite
node_community_src_packages_apps_example_viewer -->|"reuses shell"| node_community_src_packages_apps_common
node_community_examples_formdata -->|"embeds viewer"| node_community_src_packages_core
node_community_examples_bundle_size -->|"benchmarks"| node_community_src_packages_core
node_community_examples_bundle_size -->|"benchmarks"| node_community_src_packages_views_mantine
node_community_examples_bundle_size -->|"benchmarks"| node_community_src_packages_views_material_ui
node_community_examples_file_upload_server -->|"supports uploads"| node_community_src_packages_views_uploader
node_premium_examples_formengine -->|"uses core"| node_community_src_packages_core
node_premium_examples_formengine -->|"uses theme"| node_community_src_packages_views_mantine
node_premium_examples_with_angular_forms -->|"integrates runtime"| node_community_src_packages_core
node_premium_examples_with_formik -->|"integrates runtime"| node_community_src_packages_core
node_premium_examples_with_nextjs -->|"integrates runtime"| node_community_src_packages_core
node_premium_examples_with_remix -->|"integrates runtime"| node_community_src_packages_core

click node_community_src_packages_core "https://github.com/optimajet/formengine/tree/master/community/src/packages/core"
click node_community_src_packages_json_schema_generator "https://github.com/optimajet/formengine/tree/master/community/src/packages/json-schema-generator"
click node_community_src_packages_viewer_bundle "https://github.com/optimajet/formengine/tree/master/community/src/packages/viewer-bundle"
click node_community_src_packages_views_mantine "https://github.com/optimajet/formengine/tree/master/community/src/packages/views/mantine"
click node_community_src_packages_views_material_ui "https://github.com/optimajet/formengine/tree/master/community/src/packages/views/material-ui"
click node_community_src_packages_views_rsuite "https://github.com/optimajet/formengine/tree/master/community/src/packages/views/rsuite"
click node_community_src_packages_views_uploader "https://github.com/optimajet/formengine/tree/master/community/src/packages/views/uploader"
click node_community_src_packages_apps_common "https://github.com/optimajet/formengine/tree/master/community/src/packages/apps/common"
click node_community_src_packages_apps_example_viewer "https://github.com/optimajet/formengine/tree/master/community/src/packages/apps/example-viewer"
click node_community_examples_formdata "https://github.com/optimajet/formengine/tree/master/community/examples/formdata"
click node_community_examples_bundle_size "https://github.com/optimajet/formengine/tree/master/community/examples/bundle-size"
click node_community_examples_file_upload_server "https://github.com/optimajet/formengine/tree/master/community/examples/file-upload-server"
click node_premium_examples_formengine "https://github.com/optimajet/formengine/tree/master/premium/examples/formengine"
click node_premium_examples_with_angular_forms "https://github.com/optimajet/formengine/tree/master/premium/examples/with-angular-forms"
click node_premium_examples_with_formik "https://github.com/optimajet/formengine/tree/master/premium/examples/with-formik"
click node_premium_examples_with_nextjs "https://github.com/optimajet/formengine/tree/master/premium/examples/with-nextjs"
click node_premium_examples_with_remix "https://github.com/optimajet/formengine/tree/master/premium/examples/with-remix"
click node_community_core_store "https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/stores"
click node_community_core_viewer "https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/form-viewer"
click node_community_core_validation "https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/validation"
click node_community_core_localization "https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/localization"
click node_community_core_events "https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/event"
click node_community_core_builder "https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/form-json-builder"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_premium_examples_formengine,node_premium_examples_with_angular_forms,node_premium_examples_with_formik,node_premium_examples_with_nextjs,node_premium_examples_with_remix toneAmber
class node_community_src_packages_apps_common,node_community_src_packages_apps_example_viewer,node_community_examples_formdata,node_community_examples_bundle_size,node_community_examples_file_upload_server toneMint
class node_community_src_packages_core,node_community_core_store,node_community_core_viewer,node_community_core_validation,node_community_core_localization,node_community_core_events,node_community_core_builder toneRose
class node_community_src_packages_views_mantine,node_community_src_packages_views_material_ui,node_community_src_packages_views_rsuite,node_community_src_packages_views_uploader toneIndigo
class node_community_src_packages_json_schema_generator,node_community_src_packages_viewer_bundle toneTeal
```

## Components

### Premium

Commercial examples and framework integrations.

- [Premium demo](https://github.com/optimajet/formengine/tree/master/premium/examples/formengine): designer demo · Premium React example showing form builder and viewer consumption paths. · `premium/examples/formengine`
- [Angular forms](https://github.com/optimajet/formengine/tree/master/premium/examples/with-angular-forms): integration demos · Stepwise Angular examples that move from native forms to FormEngine and designer integration. · `premium/examples/with-angular-forms`
- [Formik](https://github.com/optimajet/formengine/tree/master/premium/examples/with-formik): integration demo · React/Formik example embedding shared JSON form definitions and validators. · `premium/examples/with-formik`
- [Next.js](https://github.com/optimajet/formengine/tree/master/premium/examples/with-nextjs): integration demo · Next.js example with shared form model, builder, viewer, and actions. · `premium/examples/with-nextjs`
- [Remix](https://github.com/optimajet/formengine/tree/master/premium/examples/with-remix): integration demo · Remix example with client/server viewer and builder entrypoints around shared form JSON. · `premium/examples/with-remix`

### Examples

Standalone demo and benchmarking applications.

- [Common app](https://github.com/optimajet/formengine/tree/master/community/src/packages/apps/common): shared app shell · Shared example-app shell for theme picking, persistent state, and loading forms from JSON. · `community/src/packages/apps/common`
- [Example viewer](https://github.com/optimajet/formengine/tree/master/community/src/packages/apps/example-viewer): demo app · End-to-end viewer app that switches between themes and renders sample forms. · `community/src/packages/apps/example-viewer`
- [Formdata](https://github.com/optimajet/formengine/tree/master/community/examples/formdata): demo app · Vite example that loads sample form JSON and embeds the viewer runtime. · `community/examples/formdata`
- [Bundle size](https://github.com/optimajet/formengine/tree/master/community/examples/bundle-size): benchmark harness · Multi-stack performance and bundle-size comparison suite with reporting scripts. · `community/examples/bundle-size`
- [Upload server](https://github.com/optimajet/formengine/tree/master/community/examples/file-upload-server): backend demo · Small file-upload server used by uploader-oriented examples. · `community/examples/file-upload-server`

### Runtime

Core form engine and its main supporting subsystems.

- [Core](https://github.com/optimajet/formengine/tree/master/community/src/packages/core): form runtime · JSON-driven form engine with viewer, builder, validation, localization, events, modal/repeater/template support, and store/state management. · `community/src/packages/core`
- [Store](https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/stores): state layer · Central form state, component state, persisted form, and localization stores. · `community/src/packages/core/src/stores`
- [Viewer](https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/form-viewer): render runtime · FormViewer, viewer wrapper, component tree rendering, and viewer store/provider plumbing. · `community/src/packages/core/src/features/form-viewer`
- [Validation](https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/validation): validation pipeline · Schema-driven validation, Zod rules, custom rules, and error rendering. · `community/src/packages/core/src/features/validation`
- [Localization](https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/localization): i18n engine · Fluent-based localization engine, language resources, and viewer localization provider. · `community/src/packages/core/src/features/localization`
- [Events](https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/event): action system · Action definitions, event handlers, and event-to-store coordination for user interactions. · `community/src/packages/core/src/features/event`
- [Form builder](https://github.com/optimajet/formengine/tree/master/community/src/packages/core/src/features/form-json-builder): json builder · Builder for generating form JSON and metadata from code. · `community/src/packages/core/src/features/form-json-builder`

### Views

Theme-specific UI adapters and component catalogs.

- [Mantine](https://github.com/optimajet/formengine/tree/master/community/src/packages/views/mantine): theme adapter · Mantine component bindings, viewer wrappers, localized descriptions, and theme-specific behaviors. · `community/src/packages/views/mantine`
- [Material UI](https://github.com/optimajet/formengine/tree/master/community/src/packages/views/material-ui): theme adapter · Material UI component bindings, wrappers, and catalog definitions for the form runtime. · `community/src/packages/views/material-ui`
- [RSuite](https://github.com/optimajet/formengine/tree/master/community/src/packages/views/rsuite): theme adapter · RSuite component bindings, wrappers, localization, and CSS assets for the runtime. · `community/src/packages/views/rsuite`
- [Uploader](https://github.com/optimajet/formengine/tree/master/community/src/packages/views/uploader): theme adapter · Uploader-focused component package and schema catalog. · `community/src/packages/views/uploader`

### Tools

Schema generation and packaging utilities.

- [Schema gen](https://github.com/optimajet/formengine/tree/master/community/src/packages/json-schema-generator): schema tool · Generates JSON schemas from core types and form metadata. · `community/src/packages/json-schema-generator`
- [Viewer bundle](https://github.com/optimajet/formengine/tree/master/community/src/packages/viewer-bundle): bundle entry · Package entry for bundling the viewer runtime for consumers. · `community/src/packages/viewer-bundle`

## Connections

- Form builder → Core: builds form JSON · Produces runtime form definitions consumed by the core viewer and store.
- Core → Store: owns state · Core coordinates store/state, persisted form data, and component model updates.
- Core → Viewer: drives render · Core exposes the viewer API and render tree used by apps and theme packages.
- Core → Validation: validates · Validation results flow back into the viewer/store for field errors and submission control.
- Core → Localization: localizes · Localization is part of the rendering/runtime layer.
- Core → Events: emits actions · User interaction is converted into named actions and event handlers.
- Viewer → Mantine: adapts to theme · Viewer uses theme-specific component bindings and wrappers.
- Viewer → Material UI: adapts to theme · Viewer uses theme-specific component bindings and wrappers.
- Viewer → RSuite: adapts to theme · Viewer uses theme-specific component bindings and wrappers.
- Viewer → Uploader: adapts to theme · Viewer uses uploader-specific component bindings and wrappers.
- Mantine → Localization: supplies text · Theme package contributes localized descriptions and UI strings.
- Material UI → Localization: supplies text · Theme package contributes localized descriptions and UI strings.
- RSuite → Localization: supplies text · Theme package contributes localized descriptions and UI strings.
- Uploader → Localization: supplies text · Theme package contributes localized descriptions and UI strings.
- Schema gen → Material UI: generates schema · Produces theme component schema assets for tooling and authoring.
- Schema gen → RSuite: generates schema · Produces theme component schema assets for tooling and authoring.
- Schema gen → Uploader: generates schema · Produces theme component schema assets for tooling and authoring.
- Common app → Core: uses core · Shared app shell loads forms and renders via the runtime.
- Common app → Mantine: uses theme · Theme picker and form rendering use Mantine bindings.
- Common app → Material UI: uses theme · Theme picker and form rendering use Material UI bindings.
- Common app → RSuite: uses theme · Theme picker and form rendering use RSuite bindings.
- Example viewer → Common app: reuses shell · Example viewer is built on shared app utilities and form loading helpers.
- Formdata → Core: embeds viewer · Loads sample JSON and renders through the core form viewer.
- Bundle size → Core: benchmarks · Compares stack and theme packaging costs against the core runtime.
- Bundle size → Mantine: benchmarks · Measures bundle size impact for theme bindings.
- Bundle size → Material UI: benchmarks · Measures bundle size impact for theme bindings.
- Upload server → Uploader: supports uploads · Provides backend counterpart for uploader-themed flows.
- Premium demo → Core: uses core · Premium demo consumes the shared runtime and JSON model.
- Premium demo → Mantine: uses theme · Premium demo renders through a concrete UI adapter.
- Angular forms → Core: integrates runtime · Angular steps reuse the shared form model and validation layer.
- Formik → Core: integrates runtime · Formik example binds the shared form JSON and validation into React forms.
- Next.js → Core: integrates runtime · Next.js example wires shared JSON definitions into app routes and actions.
- Remix → Core: integrates runtime · Remix example wires shared JSON definitions into client/server routes.