Article Type: Concept
Audience: Solution Architects, Solution Engineers, Project Managers, System Administrators
Module: Platform Architecture / Development Best Practices
Applies to Versions: All Versions
SOLID is an acronym for five foundational software design principles — Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion — originally formulated for object-oriented programming. When applied to the Fuuz Industrial Operations Platform, these principles translate directly into architectural guidance for how to design data models, build data flows, compose screens, and package applications. Following SOLID practices in Fuuz results in applications that are easier to maintain, safer to extend, and more resilient to changing business requirements.
Fuuz applications are composed of three primary layers — Data Models, Data Flows, and Screens — all organized within Modules and ModuleGroups and distributed as .fuuz packages. Each of these layers presents opportunities to either violate or enforce SOLID principles. A flow that does too many things at once, a data model that conflates unrelated concerns, or a screen that mixes roles are all common patterns that SOLID helps to prevent. This article walks through each principle with concrete Fuuz examples and anti-patterns to avoid.
This article is intended for Solution Architects designing application structure, Solution Engineers implementing flows and screens, and Project Managers evaluating code quality and maintainability standards. It assumes familiarity with core Fuuz concepts including Modules, Flows, Screens, GraphQL queries, Connectors, and Sequences.
setContext replaces the context object; mergeContext adds to it. Used to externalize configuration from core logic.Each SOLID principle maps primarily to one or more Fuuz layers:
| Principle | Primary Fuuz Layer | Key Mechanism |
|---|---|---|
| Single Responsibility | Flows, Models, Screens | Flow decomposition, model domain separation |
| Open/Closed | Packages, Flows, Screens | Module extension, setContext, $appConfig |
| Liskov Substitution | Models, Sub-flows | Consistent base fields, uniform sub-flow contracts |
| Interface Segregation | GraphQL Queries, Flows, Screens | Lean queries, minimal payload contracts, role screens |
| Dependency Inversion | Connectors, Sequences, Saved Queries | Named abstractions, no hardcoded credentials or endpoints |
OEE Calculation Flow Decomposition (SRP): A manufacturing application needs to calculate OEE, send downtime alerts, and update work order status. Instead of building one large flow, the team creates three separate flows: calculateOeeHourly, notifyDowntimeAlert, and updateWorkOrderStatus. Each flow has a single reason to change — if the OEE formula changes, only calculateOeeHourly is touched.
Extending an Application Without Modifying the Base (OCP): A base Quality module handles inspection records. A new compliance requirement demands digital signature tracking. Rather than modifying the base Quality module, a new Compliance Signatures module is added to the ModuleGroup, extending the application without touching proven, deployed code.
Multi-Plant Deployment with Configurable Thresholds (OCP): An OEE alert flow reads its downtime threshold and notification group directly from $appConfig wherever needed. No flow modification or cloning is required when a second plant has different thresholds — only the app configuration changes.
Runtime Context Consolidation (OCP): A production event flow needs the current timestamp, the workcenter type, and a derived night shift flag across multiple downstream nodes. A setContext node at the top computes all three once from the incoming payload. When the night shift boundary rule changes, only the setContext node is updated — every downstream node referencing $state.context.isNightShift automatically reflects the new logic without modification.
Uniform Workcenter Type Handling (LSP): A dashboard displays current status for all workcenters, regardless of type (Machine, Assembly Line, Clean Room). Because all workcenter type variants share the same base fields (name, status, currentShift, oeeTarget), the dashboard query and screen work uniformly across all types without special-casing.
Interchangeable Notification Sub-flows (LSP): A parent flow routes alerts to different channels depending on severity — email for warnings, SMS for critical. Both sendEmailNotification and sendSmsNotification sub-flows accept the same context shape (message, severity, recipientGroupId) and return the same output structure. The parent flow is agnostic to which handler it calls.
Lean GraphQL Queries on a Production Screen (ISP): A production entry screen only needs id, workOrderNumber, and targetQuantity from the WorkOrder model. Instead of fetching all 25 fields on the model, the screen query requests only those three. This reduces payload size, speeds up rendering, and decouples the screen from unrelated model changes.
Role-Specific Screen Design (ISP): Operators need a simple production entry screen with 5 fields. Supervisors need a review screen with production history, defect analysis, and approval workflows. Rather than building one screen with 30 fields and hiding half by role, two distinct screens are built — each focused on its user's task.
ERP Integration via Named Connector (DIP): A flow syncs work orders from Plex. The flow references the Connector named PlexProduction — not a hardcoded URL or credentials. When the Plex environment changes from sandbox to production, only the Connector configuration is updated. No flow logic changes.
Document Numbering via Sequence (DIP): Work order numbers are generated using a platform Sequence named WorkOrderNumber. The flow calls the Sequence by name and receives the next value. If the numbering format or starting point changes, the Sequence configuration is updated — the flow is untouched.
Centralized Data Access via Saved Queries (DIP): Three different flows need to look up active work orders by workcenter. Instead of embedding the same GraphQL query in all three flows, a Saved Query named ActiveWorkOrdersByWorkcenter is created. All three flows reference it by name. When the WorkOrder model adds a new filter field, only the Saved Query is updated.
Screen Configuration via $appConfig (OCP + DIP): A dashboard displays status colors based on OEE thresholds. Colors and thresholds are stored in $appConfig rather than hardcoded in screen bindings. When the customer changes their KPI targets, only the app configuration is updated — the screen logic is unchanged and no redeployment is required.
SOLID principles influence screen design at multiple levels: how screens are scoped, how they consume data, how they handle configuration, and how they serve different user roles. The following guidance applies to the Fuuz Screen Designer.
Each screen should serve one user task. Common violations include combining list and entry functionality, mixing operator and supervisor workflows, and embedding configuration management in operational screens.
| Violation Pattern | SOLID Correction |
|---|---|
| Work Order List + Production Entry on same screen | Separate into Work Order List screen and Production Entry screen |
| Operator and Supervisor views combined with role-based visibility hiding | Build dedicated screens per role |
| Dashboard that also includes a data entry form | Separate dashboard and form into distinct screens |
Screens should be configurable without being rewritten. Use $appConfig for thresholds, labels, colors, and display options. Use $state for runtime context. Avoid hardcoded values in component properties or JSONata bindings.
/* Open/Closed: Read OEE color threshold from $appConfig */
$state.payload.oeeValue > $appConfig.oeeGoodThreshold ? "green" : "red"
/* Violation: Hardcoded threshold */
$state.payload.oeeValue > 85 ? "green" : "red"Table and form screens should query only the fields they need. Use the Screen Designer's GraphQL builder to select specific fields rather than accepting default full-record queries. This reduces payload size and decouples screens from model changes.
| Screen Type | Fields to Query | Fields to Avoid Querying |
|---|---|---|
| Work Order List | id, workOrderNumber, status, dueDate, assignedWorkcenter | All detail fields, BOM lines, history records |
| Production Entry Form | id, workOrderNumber, targetQuantity, product.name | Supplier info, financial fields, audit timestamps |
| OEE Dashboard | workcenter.name, oeeValue, availabilityRate, performanceRate, qualityRate | Raw event logs, individual cycle records |
A well-structured Fuuz flow should perform one logical operation. The recommended decomposition pattern for complex operations is a master flow that orchestrates focused child flows:
Master Flow: processProductionEvent
└── Child Flow: validateProductionRecord
└── Child Flow: calculateOeeContribution
└── Child Flow: updateWorkOrderProgress
└── Child Flow: notifyIfThresholdBreachedEach child flow has a single entry context and a single output. When the OEE formula changes, only calculateOeeContribution is modified. All other child flows and the master flow remain untouched.
Use a setContext node at the top of the flow to derive and consolidate runtime values — such as computed fields, payload-driven lookups, or current timestamps — into a single named context. This keeps all downstream logic nodes closed to change: if the derivation logic evolves, only the setContext node is updated.
/* setContext node — top of flow: derive runtime values once, reuse everywhere */
{
"eventTimestamp": $now(),
"shiftId": $state.payload.shiftId,
"workcenterType": $state.payload.workcenter.type,
"isNightShift": $state.payload.shiftStart > $appConfig.nightShiftStartTime or $state.payload.shiftStart < $appConfig.nightShiftEndTime
}
/* Violation: same derivation repeated inline across multiple downstream nodes */
/* Node A */ $now() & " — " & $state.payload.workcenter.type
/* Node B */ $state.payload.shiftStart > "20:00" or $state.payload.shiftStart < "06:00"
/* Node C */ $state.payload.shiftId & "-" & $state.payload.workcenter.typeDownstream nodes reference $state.context.isNightShift, $state.context.workcenterType, and so on — never re-deriving values inline. When the shift classification logic changes (e.g. night shift boundary moves to 21:00), only the setContext node is updated. All downstream nodes remain untouched.
When designing models with type variants, define a base field set that all variants must carry. Document this contract explicitly in the model's description field:
| Base Field | Type | Required on All Variants |
|---|---|---|
| name | String | Yes |
| status | Enum (WorkcenterStatus) | Yes |
| currentShift | Relation → Shift | Yes |
| oeeTarget | Float | Yes |
Variant-specific fields (e.g., cleanRoomClassification for Clean Room type) are additive. Any flow or screen that operates on workcenters in general uses only the base contract fields and remains agnostic to type.
When designing sub-flow inputs, define the minimum payload needed for that flow's task. Do not pass the entire upstream context. Use JSONata transforms to extract and shape the input:
/* Transform before calling notifyDowntimeAlert sub-flow */
/* Only pass what the notification flow needs */
{
"message": "Downtime threshold exceeded on " & $state.payload.workcenter.name,
"severity": "critical",
"recipientGroupId": $state.context.notificationGroupId
}The notification sub-flow does not receive — and therefore does not depend on — production quantities, OEE values, shift records, or any other upstream data it doesn't need.
All external integrations must use named Connectors. Never embed URLs, tokens, or credentials in flow logic:
/* Correct: Reference connector by name in HTTP Request node */
{
"connector": "PlexProduction",
"endpoint": "/api/v1/workorders",
"method": "GET"
}
/* Violation: Hardcoded URL and token */
{
"url": "https://mycompany.plex.com/api/v1/workorders",
"headers": { "Authorization": "Bearer abc123token" }
}Similarly, all human-readable ID generation must use Sequences:
/* Correct: Use platform Sequence node */
Sequence Node → name: "WorkOrderNumber" → result: "WO-000123"
/* Violation: Generate number in JSONata */
"WO-" & $string($count($state.payload.existingOrders) + 1)| Anti-Pattern | Violated Principle | Correction |
|---|---|---|
| One flow handles OEE calc + notification + WO update | SRP | Split into three focused flows |
| Hardcoded threshold values inside flow logic nodes | OCP | Move all configurable values to setContext |
| Workcenter type variants with inconsistent base fields | LSP | Define and enforce a base field contract for all variants |
| Querying full records when only 3 fields are needed | ISP | Write targeted queries with only required fields |
| Hardcoded ERP URL and token in HTTP Request node | DIP | Configure a named Connector and reference it in the node |
| Operator and supervisor tasks on the same screen | SRP + ISP | Build separate role-specific screens |
| Modifying base module to add new feature | OCP | Add a new module to the ModuleGroup instead |
| ID generation via JSONata counter logic | DIP | Use a platform Sequence node |
| Issue | Cause | Resolution |
|---|---|---|
| A change to the OEE formula breaks the notification logic in the same flow | SRP violation — multiple responsibilities in one flow | Decompose the flow into separate child flows per responsibility. Use a master orchestrator flow to call them in sequence. |
| Deploying to a second plant requires editing core flow logic | OCP violation — configurable values are hardcoded in logic nodes | Move all plant-specific values (thresholds, IDs, targets) into a setContext node at the top of the flow. Reference via $state.context. |
| Dashboard screen breaks when a new workcenter type is added | LSP violation — dashboard query depends on type-specific fields | Update the screen query to use only base contract fields. Add type-specific fields only in type-specific views. |
| Sub-flow breaks when upstream flow adds new fields to its payload | ISP violation — sub-flow receives the full upstream payload | Add a JSONata transform node before calling the sub-flow to extract and shape only the required fields into the sub-flow's input. |
| Integration flow fails after ERP environment change | DIP violation — URL or credentials hardcoded in the HTTP Request node | Replace hardcoded connection details with a named Connector. Update the Connector configuration to point to the new environment without touching the flow. |
| Work order numbers become duplicated under concurrent load | DIP violation — ID generation logic implemented in JSONata instead of using a Sequence | Replace the JSONata counter with a platform Sequence node. Sequences are atomic and concurrency-safe by design. |
| Screen performance is slow on low-bandwidth plant floor tablets | ISP violation — screen queries are returning full records with many unused fields | Audit the screen's GraphQL query and remove all fields not rendered in the UI. Use the Screen Designer's field selector to build lean queries. |
| Adding a new feature requires modifying a module shared across multiple deployments | OCP violation — functionality is being added to a shared base module instead of extended | Create a new module within the ModuleGroup for the new feature. The base module remains stable; the new module extends the application. |
| Operator screen is confusing because it shows too many fields irrelevant to their task | SRP + ISP violation — single screen trying to serve multiple roles | Split into role-specific screens. Operator screen shows only production-critical fields. Supervisor screen provides review and approval workflow. |
| A notification flow behaves differently depending on which parent flow calls it | LSP violation — the notification sub-flow has inconsistent input expectations | Define a strict input contract for the sub-flow (message, severity, recipientGroupId). All calling flows must shape their payload to match this contract before invoking it. |
| Color thresholds on a dashboard are wrong after a KPI target change | OCP violation — threshold values are hardcoded in screen bindings | Move threshold values to $appConfig. Update $appConfig to change behavior without modifying the screen. |
| Three different flows embed the same GraphQL query for active work orders | DIP violation — data access logic is duplicated across flows | Create a Saved Query for active work orders. All three flows reference it by name. When the query needs to change, update it in one place. |
calculateOeeHourly, closeWorkOrder, notifyDowntimeAlert. A well-named flow communicates its single responsibility immediately.| Version | Date | Editor | Description |
|---|---|---|---|
| 1.0 | 2026-03-06 | Fuuz Documentation Team | Initial Release |
Fuuz Industrial Operations Platform — Knowledge Base