# procodersptyltd/blazorforms architecture

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

- Interactive diagram: https://gitdiagram.com/procodersptyltd/blazorforms
- Repository: https://github.com/procodersptyltd/blazorforms

## Overview

##### Project type and purpose
- This is an open-source .NET low-code framework (“BlazorForms”) for defining and running flows, forms and business rules.
- It ships as a collection of NuGet-style class-library projects under src/, plus host apps under demo/ and seed/, and end-to-end integration tests under tests/.

##### High-level file-structure & architectural insights
- Top-level folders:
- demo/ – sample Blazor Server and WASM apps using the framework
- seed/ – minimal “sandpit” apps
- src/ – framework code, organized into feature-area subfolders (admin, dynamic-code, expressions, flows, forms, platform, proxy, rendering, rules, shared, store, wasm)
- tests/ – integration and unit tests organized by subsystem
- Each src/<area> folder is one or more .csproj libraries targeting a well-defined slice of functionality.
- Demo and seed apps reference platform + rendering + flows + forms + rules packages via DI.

##### Core architectural layers
a. Definitions layer (src/flows/BlazorForms.Flows.Definitions, src/forms/BlazorForms.Forms.Definitions, src/rules/BlazorForms.FlowRules.Definition)
– Contains abstractions, interfaces and JSON/schema models for flows, forms and rules.
b. Engine layer (src/flows/BlazorForms.Flows.Engine, src/dynamic-code/BlazorForms.DynamicCode, src/expressions/BlazorForms.Expressions, src/rules/BlazorForms.FlowRules)
– Implements parsing, execution, validation, dynamic compilation, expression evaluation and rule engines.
c. Platform layer (src/platform/BlazorForms.Platform.*)
– Plug-in points for storage (Cosmos, PostgreSQL, in-memory, item-store), hosting (ASP.NET Core controllers, WebAssembly support), background tasks, feature toggles and code generation.
d. Rendering layer (src/rendering/BlazorForms.Rendering.*)
e. Auxiliary libraries
– src/proxy/BlazorForms.Proxyma (model-proxying), src/shared/BlazorForms.Shared (common data structures, extensions), src/store/BlazorForms.ItemStore & BlazorForms.Storage (store abstractions).
f. Host apps
– demo/BlazorFormsDemo* and seed/BlazorForms* – sample Blazor Server, Blazor WASM and admin apps that consume platform + rendering + engine + definitions.

##### Key interactions and dependencies
- Flow or form definition → parsed by engine → produces a FlowContext or FormModel
- Engine invokes expression and rule libraries to evaluate conditions, business rules, field triggers
- Persistence: engine calls IFlowRepository → injected implementation (Cosmos, PostgreSQL, InMemory)
- UI: Blazor host app calls Platform’s Web API controllers to fetch FlowModel → rendering layer’s components render forms/flows in browser
- DynamicCodeEngine enables runtime‐compiled flows (SqlDynamicFlowRepository) and validation rules
- Proxyma library can wrap model objects for change-tracking scenarios

##### Architectural patterns & design principles
- Layered modular design with clear separation of concerns (definitions → engine → platform → rendering)
- Dependency Injection and IServiceCollection extension methods as plug-in model
- Onion/hexagonal architecture around core definitions and engine
- Plugin extensibility via IServiceCollection: add support for new storage, rendering, UI toolkits, code‐gen

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Definitions Layer
    subgraph "Definitions Layer"
        FlowsDef["Flows Definitions"]:::core
        FormsDef["Forms Definitions"]:::core
        RulesDef["Rules Definitions"]:::core
    end

    %% Engine Layer
    subgraph "Engine Layer"
        FlowEngine["FlowRunEngine"]:::core
        DynamicCodeEngine["DynamicCodeEngine"]:::core
        ExpressionEngine["ExpressionEngine"]:::core
        RuleEngine["RuleEngine"]:::core
    end

    %% Platform Layer
    subgraph "Platform & Infrastructure"
        APIControllers["API Controllers"]:::infra
        BackgroundService["Background Tasks"]:::infra
        ConfigFeature["Config & Feature Toggles"]:::infra
        CosmosAdapter["Cosmos DB Adapter"]:::infra
        PostgresAdapter["PostgreSQL Adapter"]:::infra
        WASMSupport["WebAssembly Support"]:::infra
        DefinitionsShared["Definitions & Shared Infra"]:::infra
        CodeGen["Code Generation"]:::infra
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        CoreRendering["Core Rendering Abstractions"]:::ui
        FlowDiagram["Flow Diagram Renderer"]:::ui
        MaterialUI["MaterialBlazor Toolkit"]:::ui
        MudUI["MudBlazor Toolkit"]:::ui
        RadzenUI["Radzen Toolkit"]:::ui
        StandardUI["Standard UI Toolkit"]:::ui
    end

    %% Auxiliary Libraries
    subgraph "Auxiliary Libraries"
        Proxyma["Proxy Generation (Proxyma)"]:::core
        SharedUtils["Shared Utilities & Extensions"]:::core
        ItemStore["ItemStore Abstractions"]:::core
        GenericStorage["In-Memory & Generic Storage"]:::core
    end

    %% Host Applications
    subgraph "Host Applications"
        AdminUI["Admin UI (flow management)"]:::host
        DemoApps["Demo Blazor Apps"]:::host
        SeedApps["Seed Sandpit Apps"]:::host
    end

    %% External Entities
    CosmosDB[(Cosmos DB)]:::external
    PostgreSQL[(PostgreSQL)]:::external
    Browser((User Browser)):::external

    %% Relationships
    FlowsDef -->|defines| FlowEngine
    FormsDef -->|defines| FlowEngine
    RulesDef -->|defines| RuleEngine

    FlowEngine -->|uses| ExpressionEngine
    FlowEngine -->|uses| RuleEngine
    FlowEngine -->|invokes| DynamicCodeEngine

    FlowEngine -->|calls| CosmosAdapter
    FlowEngine -->|calls| PostgresAdapter

    APIControllers -->|routes to| FlowEngine
    AdminUI -->|calls API| APIControllers
    DemoApps -->|calls API| APIControllers
    SeedApps -->|calls API| APIControllers

    DemoApps -->|renders| CoreRendering
    AdminUI -->|renders| CoreRendering
    DemoApps -->|renders| MaterialUI
    DemoApps -->|renders| MudUI
    DemoApps -->|renders| RadzenUI
    DemoApps -->|renders| StandardUI
    AdminUI -->|renders| FlowDiagram
    DemoApps -->|renders| FlowDiagram

    CoreRendering -->|extends via DI| MaterialUI
    CoreRendering -->|extends via DI| MudUI
    CoreRendering -->|extends via DI| RadzenUI
    CoreRendering -->|extends via DI| StandardUI

    BackgroundService -->|hosts| DynamicCodeEngine
    WASMSupport -->|supports| DemoApps
    WASMSupport -->|supports| SeedApps

    Proxyma -->|wraps| FlowEngine
    SharedUtils -->|used by| all
    ItemStore -->|implements| CosmosAdapter
    ItemStore -->|implements| PostgresAdapter
    GenericStorage -->|implements| CosmosAdapter
    GenericStorage -->|implements| PostgresAdapter

    CosmosAdapter -->|connects to| CosmosDB
    PostgresAdapter -->|connects to| PostgreSQL

    DemoApps -->|shown in| Browser
    AdminUI -->|shown in| Browser
    SeedApps -->|shown in| Browser

    %% Click Events
    click FlowsDef "https://github.com/procodersptyltd/blazorforms/blob/main/src/flows/BlazorForms.Flows.Definitions"
    click FormsDef "https://github.com/procodersptyltd/blazorforms/blob/main/src/forms/BlazorForms.Forms.Definitions"
    click RulesDef "https://github.com/procodersptyltd/blazorforms/blob/main/src/rules/BlazorForms.FlowRules.Definition"
    click FlowEngine "https://github.com/procodersptyltd/blazorforms/blob/main/src/flows/BlazorForms.Flows.Engine"
    click DynamicCodeEngine "https://github.com/procodersptyltd/blazorforms/blob/main/src/dynamic-code/BlazorForms.DynamicCode"
    click ExpressionEngine "https://github.com/procodersptyltd/blazorforms/blob/main/src/expressions/BlazorForms.Expressions"
    click RuleEngine "https://github.com/procodersptyltd/blazorforms/blob/main/src/rules/BlazorForms.FlowRules"
    click APIControllers "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform/Api.Controllers"
    click BackgroundService "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform.BackgroundService"
    click ConfigFeature "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform.Config"
    click CosmosAdapter "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform.Cosmos"
    click PostgresAdapter "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform.PostgreSql"
    click WASMSupport "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform.WebAssembly"
    click DefinitionsShared "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform.Definitions"
    click DefinitionsShared "https://github.com/procodersptyltd/blazorforms/blob/main/src/platform/BlazorForms.Platform.Shared"
    click CodeGen "https://github.com/procodersptyltd/blazorforms/tree/main/src/platform/BlazorForms.Platform/CodeGeneration"
    click FlowDiagram "https://github.com/procodersptyltd/blazorforms/blob/main/src/rendering/BlazorForms.Rendering.Flows"
    click CoreRendering "https://github.com/procodersptyltd/blazorforms/blob/main/src/rendering/BlazorForms.Rendering"
    click MaterialUI "https://github.com/procodersptyltd/blazorforms/blob/main/src/rendering/BlazorForms.Rendering.MaterialBlazor"
    click MudUI "https://github.com/procodersptyltd/blazorforms/blob/main/src/rendering/BlazorForms.Rendering.MudBlazorUI"
    click RadzenUI "https://github.com/procodersptyltd/blazorforms/blob/main/src/rendering/BlazorForms.Rendering.RadzenBlazor"
    click StandardUI "https://github.com/procodersptyltd/blazorforms/blob/main/src/rendering/BlazorForms.Rendering.Standard"
    click Proxyma "https://github.com/procodersptyltd/blazorforms/blob/main/src/proxy/BlazorForms.Proxyma"
    click SharedUtils "https://github.com/procodersptyltd/blazorforms/blob/main/src/shared/BlazorForms.Shared"
    click ItemStore "https://github.com/procodersptyltd/blazorforms/blob/main/src/store/BlazorForms.ItemStore"
    click GenericStorage "https://github.com/procodersptyltd/blazorforms/blob/main/src/store/BlazorForms.Storage"
    click AdminUI "https://github.com/procodersptyltd/blazorforms/blob/main/src/admin/BlazorForms.Admin.App"
    click DemoApps "https://github.com/procodersptyltd/blazorforms/tree/main/demo/"
    click SeedApps "https://github.com/procodersptyltd/blazorforms/tree/main/seed/BlazorFormsSandpit"
    %% Styles
    classDef core fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef infra fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef ui fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef host fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef external fill:#f5f5f5,stroke:#333,stroke-width:1px
```
