Flow Engine Architecture

How flow-engine-lib connects to UniverseDataController, execution model, and entity definition flow

Flow Engine Architecture

Overview

The Flow Engine (formerly singularity-lib) is a visual flow builder that lets users define data operations and logic without code. It connects to the backend's UniverseDataController for real CRUD operations against MongoDB.

Architecture

┌─────────────────────────────────────────────────────┐
│                  Flow Engine (Frontend)               │
│                                                       │
│  ┌──────────────┐  ┌───────────────┐  ┌───────────┐ │
│  │ Entity Def   │→ │ CRUD Template │→ │ Flow      │ │
│  │ Component    │  │ Generator     │  │ Canvas    │ │
│  └──────────────┘  └───────────────┘  └─────┬─────┘ │
│                                             │       │
│  ┌──────────────┐  ┌───────────────┐  ┌─────▼─────┐ │
│  │ Block        │  │ Variable      │  │ Execution │ │
│  │ Library (97) │  │ Resolver      │  │ Engine    │ │
│  └──────────────┘  └───────────────┘  └─────┬─────┘ │
└─────────────────────────────────────────────┼───────┘
                                              │
                    HTTP / REST API            │
                                              ▼
┌─────────────────────────────────────────────────────┐
│              backend-api (port 3000)                  │
│                                                       │
│  ┌──────────────────────────────────────────────────┐│
│  │           UniverseDataController                  ││
│  │                                                    ││
│  │  POST /data/:collection/query    → Query records  ││
│  │  POST /data/:collection/insert   → Insert record  ││
│  │  PUT  /data/:collection/:id      → Update record  ││
│  │  DELETE /data/:collection/:id    → Delete record  ││
│  │  POST /data/:collection/aggregate→ Aggregate      ││
│  │  POST /data/schemas              → Upsert schema  ││
│  │  GET  /data/schemas              → List schemas   ││
│  │  GET  /data/schemas/:collection  → Get schema     ││
│  └──────────────────────────────────────────────────┘│
│                         │                             │
│                         ▼                             │
│  ┌──────────────────────────────────────────────────┐│
│  │              MongoDB                              ││
│  │  space_{spaceId} database                         ││
│  │    universe_{universeId}_schemas   (schema defs)  ││
│  │    universe_{universeId}_products  (user data)    ││
│  │    universe_{universeId}_orders    (user data)    ││
│  │    universe_{universeId}_flows     (flow defs)    ││
│  └──────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘

Execution Model

Client-Side Execution (Preview/Testing)

LogicExecutionEngineService runs flows block-by-block in the browser
Used for: testing flows, previewing behavior, development
Data source: GgStorage (local IndexedDB) or mock data

Server-Side Execution (Production)

FlowBackendExecutionService (to be created) maps block operations to HTTP calls
Each storage block maps to a specific UniverseDataController endpoint
Used for: production CRUD, deployed applications

Block-to-Endpoint Mapping

Block Type	Block Operation	Backend Endpoint
`action` + `storage`	`query`	`POST /data/:collection/query`
`action` + `storage`	`save` / `insert`	`POST /data/:collection/insert`
`action` + `storage`	`update`	`PUT /data/:collection/:recordId`
`action` + `storage`	`delete`	`DELETE /data/:collection/:recordId`
`action` + `storage`	`get`	`POST /data/:collection/query` (with `_id` filter)
`action` + `storage`	`aggregate`	`POST /data/:collection/aggregate`

Entity Definition Flow

User opens Flow Builder
User clicks "New Entity" -> EntityDefinitionComponent opens
User defines fields (name, type, required, validation)
Frontend calls POST /data/schemas with the schema
Backend stores schema in universe_{id}_schemas
Frontend calls instantiateCrudFlow() from crud-flow-templates.ts
Five CRUD flows are auto-generated with the entity's collection and display name
Flows appear on the canvas ready for customization
User can modify flows, add blocks, change connections
Flows are persisted to backend via BackendFlowClientService

Integration Points

Standalone Route

/space/:spaceSlug/flow-engine/* (space-level)
Full-page Flow Builder with dashboard, canvas, and block library

Unified Builder Panel

Loaded as a tab in /space/:slug/universe/:id/builder
Uses SingularityEmbeddableComponent (name kept for backward compat)
Tab label: "Flows", icon: fa-diagram-project

Widget Integration

WidgetFlowExecutorService connects widgets to flows
FlowAttachmentService attaches flows to pages
Widgets can trigger flow execution and receive results

Block Categories (97+ blocks)

Category	Count	Examples
Triggers	~10	button-click, form-submit, page-load
API	~5	HTTP GET, POST, PUT, DELETE
UI Control	~8	show/hide, update widget, toast, modal
Navigation	~3	route navigation
Auth	~3	authentication operations
Communication	~3	email, notifications
Payment	~3	payment processing
Files	~3	file upload/download
Control	~5	if/else, loops, branches
Storage	~6	GgStorage CRUD
Database	~6	MongoDB operations
AI	~5	text gen, image gen, chat
Math	~10	add, subtract, multiply, divide
String	~10	concat, split, replace
Theme	~3	theme operations
Widgets	~3	widget generation
Modules	~3	module loading