Page History

Comprehensive product knowledge, for AI integration builders and advanced users.

Platform | Installation | Solution | Modules | Controls | Code | Troubleshooting

...

This page provides a comprehensive view of the FrameworX platform architecture, covering every module, data model, syntax rule, and integration pattern. It is designed for AI assistants working with FrameworX MCP services, system integrators building complex solutions, and advanced users who want a single-page understanding of how all platform components connect.

For getting started, see [Quick Start Guide]. For module-specific tutorials, see [BUILD section]. This page is the architectural map — not a tutorial.

This page provides a comprehensive view of the FrameworX platform architecture, covering every module, data model, syntax rule, and integration pattern. It is designed for AI assistants working with FrameworX MCP services, system integrators building complex solutions, and advanced users who want a single-page understanding of how all platform components connect.

For getting started, see [Quick Start Guide]. For module-specific tutorials, see [BUILD section]. This page is the architectural map — not a tutorial.

...

The Solution Designer is the Windows-based configuration environment where solutions are built and tested. The Runtime Engine (TServer.exe) executes solutions on any supported platform. Operator interfaces run as Rich Clients (WPF desktop), Web Clients (WebAssembly via Blazor), or Mobile Clients. The Solution Manager SolutionCenter provides a visual launcher for selecting and starting solutions.

...

Everything in FrameworX is an object in a unified namespace. Configuration, runtime, and navigation are three views of the same data:

When you create a row in a configuration table, it immediately becomes a runtime object accessible via its namespace path. There is no separate deployment or compilation step — the runtime reads directly from the solution database.

...

ObjectName is used by ScriptsExpressions. It binds a calculation to a namespace object. Format: full namespace path like Tag.Machine1/Level — requires the namespace prefix, no @, no .Value.

Singleton tables (SolutionSettings, AlarmsGlobalSettings, RuntimeStartup) have no key column — they contain a single configuration row.

Module Architecture

Tags — The Data Foundation

The Tags module provides the Unified Namespace (UNS) — the central real-time data repository that all other modules connect to.

UnsTags contains process data points organized in a hierarchical folder structure using / separators. The Name column holds the full path: Area1/Line1/Tank1/Level. Supported data types include Digital (Boolean), Integer, Double, String, DateTime, TimeSpan, and JSON.

Tags have a Domain property: Server domain (default) synchronizes values across all connected clients, while Client domain keeps values local to each client instance. Built-in client tags like @Client.UserName and @Client.Session.ComputerNameprovide session context.

UnsUserTypes defines custom tag templates (UDTs). When a UserType is defined with members such as Setpoint, ProcessValue, and AlarmLimit, creating a tag of that type automatically creates all member tags. Modifying the UserType definition auto-updates every tag instance — members are added, removed, or changed across the entire solution automatically. Members are accessed via dot notation: Tag.Loop1.Setpoint.

UnsTagProviders connects external data sources that dynamically populate the UNS with tags. When a TagProvider connects to an MQTT broker or OPC UA server, it discovers and creates tags automatically.

UnsEnumerations maps between numeric values and human-readable text labels.

Devices — Field Equipment Communication

The Devices module connects FrameworX to PLCs, sensors, controllers, and other field equipment through a three-layer architecture:

DevicesChannels configures the communication protocol. FrameworX includes 70+ native drivers: OPC UA, OPC DA, Modbus TCP/RTU, Siemens S7, Allen-Bradley EtherNet/IP, MQTT, MQTT Sparkplug B, BACnet, DNP3, IEC 61850, and many more.

DevicesNodes defines individual device addresses within a channel. Each node belongs to exactly one channel.

DevicesPoints maps tags to device addresses. Each point references an existing tag (via TagName) and specifies the device register or address to read/write. Points belong to nodes.

Six columns in Nodes and Points are protocol-dependent: ProtocolOptions, Interface, PrimaryStation, BackupStation, Address, and DataType. Their valid values change based on the protocol selected in the parent Channel. When configuring devices programmatically, always query the protocol schema to determine valid field values and formats.

Alarms — Event Detection and Notification

AlarmsGroups defines behavior rules including notification methods, escalation procedures, and acknowledgment requirements. Three groups are predefined: Critical (highest severity), Warning (operational attention), and AuditTrail (logging without operator notification).

AlarmsItems creates individual alarm triggers bound to tags. Each item references a tag via the TagName column and belongs to a group. Items define the alarm condition (high limit, low limit, rate of change, digital state change, etc.).

AlarmsAreas provides optional organizational hierarchy for grouping alarms by plant area, equipment type, or other criteria. Areas are not required for basic alarm configuration.

AlarmsGlobalSettings is a singleton table containing alarm module defaults such as acknowledgment requirements and notification options.

Historian — Time-Series Data Storage

HistorianStorageLocations defines where historical data is stored. The predefined TagHistorian location uses SQLite by default and can be changed to SQL Server, PostgreSQL, or other supported databases.

HistorianHistorianTables coordinates storage behavior — how frequently data is sampled, how long it is retained, and what compression is applied. The predefined Table1 provides default settings connected to the TagHistorian storage location.

HistorianHistorianTags specifies which tags are logged to which historian table, referenced via the TagName column.

Datasets — Database Connectivity

The Datasets module provides bidirectional database access for SQL integration, reporting data sources, and external system connectivity.

DatasetsDBs stores database connection strings. Four databases are predefined and serve platform functions: TagHistorian (historian storage, default SQLite), AlarmHistorian (alarm event logging), Retentive (tag value persistence across restarts), and RuntimeUsers (runtime user management extending the Security module). These predefined databases can be reconfigured (for example, switching from SQLite to SQL Server) but cannot be deleted.

DatasetsQueries contains SQL query definitions for reading and writing data. These are document objects — when updated, the entire query definition is replaced rather than merged.

DatasetsTables provides direct binding to database tables without writing SQL.

DatasetsFiles handles file-based data operations independent of database connections.

Scripts — Automation Logic

The Scripts module supports three languages: C#, VB.NET, and Python. Cross-language interoperability is fully supported — a C# task can call a Python class and vice-versa.

ScriptsTasks are event-triggered code blocks that run when activated by server events, tag value changes, or timer intervals. Task code is written as a method body — the platform provides the execution wrapper including exception handling and thread management. Tasks execute independently and cannot be instantiated or called from other code. Predefined tasks ServerStartup and ServerShutdown run automatically at runtime start and stop.

ScriptsClasses are reusable code libraries defined as full class definitions. Classes can be instantiated, have methods with parameters and return values, and be called from tasks, other classes, display CodeBehind, and even from external systems via the MCP for Runtime service. At runtime, class methods are accessible as Script.Class.ClassName.MethodName().

ScriptsExpressions bind one-line calculations to namespace objects. The ObjectName column uses the full namespace format (Tag.Machine1/Level) — this is the only context where the Tag. prefix is required in a key column.

ScriptsReferences registers external .NET DLL libraries for use in scripts — an advanced feature for integrating custom compiled code.

Displays — Operator Interface

The Displays module provides the visualization layer with two distinct display paradigms:

Canvas displays use absolute pixel positioning, giving full control over element placement. This is the traditional approach for HMI/SCADA screens with specific layout requirements.

Dashboard displays use a grid-based responsive layout that adapts to different screen sizes. This approach suits data-centric monitoring screens where precise positioning is less important than information density.

Displays can be classified as Pages (navigable screens loaded into layout regions) or Dialogs and Popups (modal or floating windows for focused interaction).

Every display has two editing surfaces. The Draw tab contains graphical elements — shapes, controls, gauges, charts, and symbols arranged visually. The CodeBehind tab contains C# or VB.NET code for event handling and custom actions such as DisplayOpening events, button click handlers, and custom logic. CodeBehind code lives inside the display object, separate from the Scripts module.

Key Columns: When using write_objects, tables with a Name field require only the name. Tables using TagName or ObjectName require both key columns to uniquely identify an object:

Singleton tables (SolutionSettings, AlarmsGlobalSettings, RuntimeStartup, DisplaysClientSettings) have no key column — they contain a single configuration row. RuntimeExecutionProfiles for AI will show only the differences between Development and Production profiles, directly on the Designer UI it has more options. 

...

Module Architecture

Tags — The Data Foundation

The Tags module provides the Unified Namespace (UNS) — the central real-time data repository that all other modules connect to.

UnsTags contains process data points organized in a hierarchical folder structure using / separators. The Name column holds the full path: Area1/Line1/Tank1/Level. Supported data types include Digital (Boolean), Integer, Double, String, DateTime, TimeSpan, and JSON.

Tags have a Domain property: Server domain (default) synchronizes values across all connected clients, while Client domain keeps values local to each client instance. Built-in client tags like @Client.UserName and @Client.Session.ComputerNameprovide session context.

UnsUserTypes defines custom tag templates (UDTs). When a UserType is defined with members such as Setpoint, ProcessValue, and AlarmLimit, creating a tag of that type automatically creates all member tags. Modifying the UserType definition auto-updates every tag instance — members are added, removed, or changed across the entire solution automatically. Members are accessed via dot notation: Tag.Loop1.Setpoint.

UnsTagProviders connects external data sources that dynamically populate the UNS with tags. When a TagProvider connects to an MQTT broker or OPC UA server, it discovers and creates tags automatically.

UnsEnumerations maps between numeric values and human-readable text labels.

Devices — Field Equipment Communication

The Devices module connects FrameworX to PLCs, sensors, controllers, and other field equipment through a three-layer architecture:

DevicesChannels configures the communication protocol. FrameworX includes 70+ native drivers: OPC UA, OPC DA, Modbus TCP/RTU, Siemens S7, Allen-Bradley EtherNet/IP, MQTT, MQTT Sparkplug B, BACnet, DNP3, IEC 61850, and many more.

DevicesNodes defines individual device addresses within a channel. Each node belongs to exactly one channel.

DevicesPoints maps tags to device addresses. Each point references an existing tag (via TagName) and specifies the device register or address to read/write. Points belong to nodes.

Six columns in Nodes and Points are protocol-dependent: ProtocolOptions, Interface, PrimaryStation, BackupStation, Address, and DataType. Their valid values change based on the protocol selected in the parent Channel. When configuring devices programmatically, always query the protocol schema to determine valid field values and formats.

Alarms — Event Detection and Notification

AlarmsGroups defines behavior rules including notification methods, escalation procedures, and acknowledgment requirements. Three groups are predefined: Critical (highest severity), Warning (operational attention), and AuditTrail (logging without operator notification).

AlarmsItems creates individual alarm triggers bound to tags. Each item references a tag via the TagName column and belongs to a group. Items define the alarm condition (high limit, low limit, rate of change, digital state change, etc.).

AlarmsAreas provides optional organizational hierarchy for grouping alarms by plant area, equipment type, or other criteria. Areas are not required for basic alarm configuration.

AlarmsGlobalSettings is a singleton table containing alarm module defaults such as acknowledgment requirements and notification options.

Historian — Time-Series Data Storage

HistorianStorageLocations defines where historical data is stored. The predefined TagHistorian location uses SQLite by default and can be changed to SQL Server, PostgreSQL, or other supported databases.

HistorianHistorianTables coordinates storage behavior — how frequently data is sampled, how long it is retained, and what compression is applied. The predefined Table1 provides default settings connected to the TagHistorian storage location.

HistorianHistorianTags specifies which tags are logged to which historian table, referenced via the TagName column.

Datasets — Database Connectivity

The Datasets module provides bidirectional database access for SQL integration, reporting data sources, and external system connectivity.

DatasetsDBs stores database connection strings. Four databases are predefined and serve platform functions: TagHistorian (historian storage, default SQLite), AlarmHistorian (alarm event logging), Retentive (tag value persistence across restarts), and RuntimeUsers (runtime user management extending the Security module). These predefined databases can be reconfigured (for example, switching from SQLite to SQL Server) but cannot be deleted.

DatasetsQueries contains SQL query definitions for reading and writing data. These are document objects — when updated, the entire query definition is replaced rather than merged.

DatasetsTables provides direct binding to database tables without writing SQL.

DatasetsFiles handles file-based data operations independent of database connections.

Scripts — Automation Logic

The Scripts module supports three languages: C#, VB.NET, and Python. Cross-language interoperability is fully supported — a C# task can call a Python class and vice-versa.

ScriptsTasks are event-triggered code blocks that run when activated by server events, tag value changes, or timer intervals. Task code is written as a method body — the platform provides the execution wrapper including exception handling and thread management. Tasks execute independently and cannot be instantiated or called from other code. Predefined tasks ServerStartup and ServerShutdown run automatically at runtime start and stop.

ScriptsClasses are reusable code libraries defined as full class definitions. Classes can be instantiated, have methods with parameters and return values, and be called from tasks, other classes, display CodeBehind, and even from external systems via the MCP for Runtime service. At runtime, class methods are accessible as Script.Class.ClassName.MethodName().

ScriptsExpressions bind one-line calculations to namespace objects. The ObjectName column uses the full namespace format (Tag.Machine1/Level) — this is the only context where the Tag. prefix is required in a key column.

ScriptsReferences registers external .NET DLL libraries for use in scripts — an advanced feature for integrating custom compiled code.

Displays — Operator Interface

The Displays module provides the visualization layer with two distinct display paradigms:

Canvas displays use absolute pixel positioning, giving full control over element placement. This is the traditional approach for HMI/SCADA screens with specific layout requirements.

Dashboard displays use a grid-based responsive layout that adapts to different screen sizes. This approach suits data-centric monitoring screens where precise positioning is less important than information density.

Displays can be classified as Pages (navigable screens loaded into layout regions) or Dialogs and Popups (modal or floating windows for focused interaction).

Every display has two editing surfaces. The Draw tab contains graphical elements — shapes, controls, gauges, charts, and symbols arranged visually. The CodeBehind tab contains C# or VB.NET code for event handling and custom actions such as DisplayOpening events, button click handlers, and custom logic. CodeBehind code lives inside the display object, separate from the Scripts module.

Display elements fall into several categories. Shapes (Rectangle, Ellipse, Polygon, Polyline, Path, Line) are basic drawing primitives. Controls (TextBlock, TextBox, Button, ComboBox, DataGrid, AlarmViewer, TrendChart, and approximately 50 others) are platform-provided Display elements fall into several categories. Shapes (Rectangle, Ellipse, Polygon, Polyline, Path, Line) are basic drawing primitives. Controls (TextBlock, TextBox, Button, ComboBox, DataGrid, AlarmViewer, TrendChart, and approximately 50 others) are platform-provided components with configurable properties and fixed internal behavior. Gauges (CircularGauge, LinearGauge, DigitalGauge) visualize numeric data. Symbols are user-authored reusable graphic components that can be designed from scratch with any combination of shapes, controls, and dynamic behaviors.

...

MainPage plays a dual role. It is the default display loaded into the Content region at startup, and it also serves as the solution preview image — the Solution Manager SolutionCenter shows whatever is rendered on MainPage as the solution thumbnail when selecting solutions to open.

...

SecuritySecrets stores credentials for external system authentication. Secret values are write-only and cannot be read back through any API.

Settings

Solution and Runtime Configuration

SolutionCategories defines labels applied to any object in the solution. The predefined MCP category marks AI-created objects — AI can only modify objects that have this label. That label is added automatically when document was created by AI. User can apply or remove it manually in any object.

Four Three singleton configuration tables control global solution behaviorcontain global settings with a single configuration row each:

SolutionSettings contains global solution parameters. AlarmsGlobalSettings provides alarm module defaults. RuntimeStartup controls startup behavior , execution profile selection, and runtime options.

Runtime Architecture

Startup Sequence

The FrameworX runtime follows a seven-step startup sequence:

and runtime options. RuntimeExecutionProfiles defines connection replacements between Development and Production profiles — for example, different server addresses per execution profile.

...

Runtime Architecture

Startup Sequence

The FrameworX runtime follows a seven-step startup sequence:

1. TStartup.exe launches — loads the solution file, reads configuration, parses command line arguments, and activates the runtime engine
2. TServer.exe starts — loads all objects, tags, templates, and assets into the real-time in-memory database and establishes the communication service
3. Modules initialize — Historian, Alarms, Devices, Scripts, Datasets, and Reports start their services and connect to the main runtime process
4. Execution profiles applied — modules configure themselves according to the selected profile (Development provides full access for testing; Production restricts modifications for operational safety)
5. Designer auto-connects — if the Solution Designer is open, it connects to the running solution for live monitoring and diagnostics
6. Client displays open — operator interfaces (WebAssembly or WPF) can be launched from any networked computer
7. Online changes applied — configuration changes made during runtime are applied without disrupting the running solution. If the online configuration is enabled, the modifications are pushed right away. If the configuration online is disabled, or the modifications requires restart of modules, like changing UTDs, tag types, or other modifications there requires validation of scripts, or may have global impact, those require the command hot_rreload. That command is on Designer, Runtime Diagnostics pages, or by the AI MCP for Designer tools.
8. TStartup.exe launches — loads the solution file, reads configuration, parses command line arguments, and activates the runtime engine
9. TServer.exe starts — loads all objects, tags, templates, and assets into the real-time in-memory database and establishes the communication service
10. Modules initialize — Historian, Alarms, Devices, Scripts, Datasets, and Reports start their services and connect to the main runtime process
11. Execution profiles applied — modules configure themselves according to the selected profile (Development provides full access for testing; Production restricts modifications for operational safety)
12. Designer auto-connects — if the Solution Designer is open, it connects to the running solution for live monitoring and diagnostics
13. Client displays open — operator interfaces (WebAssembly or WPF) can be launched from any networked computer
14. Online changes applied — configuration changes made during runtime are applied through hot reload without disrupting the running solution

Execution Profiles

Development profile provides unrestricted access for configuration, testing, and debugging. Production profile enforces operational restrictions appropriate for live industrial environments. The MCP for Designer service operates under the Development profile.

...

FrameworX uses a category label system to control which objects AI can modify through the MCP for Designer service. Objects created through MCP tools are automatically labeled for AI access. In , with the label MCP added to the Category of object.  In new solutions created from templates, all predefined objects (MainPage, default alarm groups, predefined databases) are also labeled, giving AI full creative control from the start.

...

Terminology Quick Reference

...

Related Documentation

Getting Started: [Quick Start Guide] — Build your first solution in 30 minutes

...