Technical Guide: Build on Fuuz Like You Built It

Overview

Every screen, data flow, integration and data model you create in Fuuz runs on the same stack: MongoDB, GraphQL APIs, the Data Flow Engine, Fuuz JSONata bindings and a deploy-anywhere infrastructure, with real-time updates over WebSockets. Knowing how each layer works, and how the layers talk to each other, is how you write better screens, faster flows and cleaner integrations, and how you find problems in minutes instead of hours.

This guide is written for engineers coming from SQL-backed, relational or legacy ERP and MES environments.

The stack

How the layers talk to each other: MongoDB reads and writes BSON documents; GraphQL serves typed queries, mutations and predicates; flows and screens reshape results with JSONata or JavaScript; and real-time events arrive over WebSockets.

• MongoDB is your data layer. Documents, not rows. The schema lives in the Fuuz data model designer, and the shape of your documents decides how simple or complex your queries, flows and bindings will be.
• GraphQL APIs are your data contract. Filtering and aggregation happen here, with predicates and _aggregate queries, not in JSONata transforms.
• The Data Flow Engine is your workflow layer. It orchestrates logic, API calls, transforms, conditions, error handling and integrations, and sits above GraphQL in the stack.
• Fuuz JSONata is your expression language. Fuuz extends standard JSONata with platform bindings such as $components, $metadata, $state and join functions.

Tip: The stack gives you a clear way to isolate problems. Data wrong? Check the document shape with a GraphQL query. Query returning unexpected results? Check the predicates and filters. Transform producing bad output? Check the JSONata or JavaScript expression in the transform console. Screen not rendering? Inspect the element binding.

Real time: WebSockets, not GraphQL subscriptions

Live screen refresh, push events and shop-floor alerts are delivered by a dedicated WebSocket subscription service, separate from the GraphQL APIs. The result is the same, live data without polling, but it is a distinct service, not a GraphQL subscription.

MongoDB: think in documents, not tables

This is the biggest shift for engineers from SQL-backed environments. MongoDB stores JSON documents, not rows, and how you design documents affects query performance, screen bindings and flow logic.

In a relational MES or ERP, reconstructing one work order can take four tables and three joins, and adding a field means ALTER TABLE, a migration and a deployment window:

SELECT wo.id, wo.number, wo.status, p.name, p.revision, op.seq, op.description
FROM work_orders wo
JOIN parts p ON p.id = wo.part_id
JOIN wo_operations op ON op.wo_id = wo.id
WHERE wo.id = 'WO-1042';

In Fuuz, the whole object comes back in one read, and a new field such as customer_po is added in the schema designer:

{
  "id": "WO-1042",
  "number": "WO-1042",
  "status": "In Progress",
  "part": { "id": "part-ref-id", "name": "Bracket Assy", "revision": "C" },
  "operations": [],
  "customer_po": "PO-8812"
}

Because adding a field takes near-zero downtime, you can extend your applications without losing valuable production time.

Embedding: the right mental model, arriving in early 2027

The embed-versus-reference pattern is the right way to think about a document database. Today, Fuuz supports JSON schema and JSON objects within data models, and enumerations are handled by joining models, which keeps them clean and queryable. Full embedded document support is on the roadmap for early 2027. Apply the principles in your data models now, and they will be well placed as that support arrives.

Important: The most common mistake from SQL backgrounds is over-normalizing: creating a separate model for every sub-entity. Before you split, ask whether the data will ever be queried on its own, or whether it always travels with its parent. Fewer models often mean simpler queries, cleaner flows and easier screen bindings.

GraphQL APIs: where filtering and fetching live

Fuuz exposes multiple GraphQL APIs. This is where you declare the data you want, apply filters and predicates, and run aggregations. When you create or extend a data model, its GraphQL API is generated and updated automatically.

Conventions to know before you build

• Connection pattern: results are wrapped in edges { node { ... } }. Your data lives on node.
• Sorting: use orderBy: [{ field: "fieldName", direction: "asc" }], not sort.
• Aggregation: put the group field and _aggregate { id { count } } together inside edges.node. There is no separate groupBy argument.
• Record ID: always id, never _id.
• Filtering: use where variables. Never fetch everything and filter in JSONata.

Good habits:

• Declare exactly what you need. A table row that shows three fields should request three fields.
• Filter with predicates. Predicates are your WHERE clause: field values, date ranges and relationships, applied before data reaches the screen or flow.
• Traverse relationships in one call. Walk from work center to work orders to operations in a single query.
• Aggregate at the query layer. _aggregate runs on the server, which is far more efficient than counting in JSONata.
• Always return id from mutations. It confirms the write and gives you the ID for chained operations.

The GraphQL editor autocompletes and validates against the schema as you type, so field-name errors and type mismatches are caught before runtime.

Query with predicates

query GetOpenWOs($where: WorkOrderWhereInput, $orderBy: [WorkOrderOrderByInput!], $first: Int, $after: String) {
  workOrder(where: $where, orderBy: $orderBy, first: $first, after: $after) {
    pageInfo { startCursor endCursor hasNextPage hasPreviousPage }
    total
    edges {
      node {
        id
        number
        status
        scheduledStart
        part { name revision }
      }
    }
  }
}

{
  "where": { "workCenterId": { "_eq": "wc-123" }, "status": { "_eq": "Open" } },
  "orderBy": [{ "field": "scheduledStart", "direction": "asc" }]
}

Mutation

mutation UpdateWOStatus($id: ID!, $status: String!, $completedAt: DateTime) {
  updateWorkOrder(id: $id, data: { status: $status, completedAt: $completedAt }) {
    id
    status
    completedAt
  }
}

Aggregate query

The group field goes on the node, with _aggregate beside it. Each edge.node in the result contains the group field and its count.

query WOStatusCounts($where: WorkOrderWhereInput, $orderBy: [WorkOrderOrderByInput!]) {
  workOrder(where: $where, orderBy: $orderBy) {
    total
    edges {
      node {
        workOrderStatusId
        _aggregate { id { count } }
      }
    }
  }
}

See also Aggregate Query API.

Anti-pattern: filtering in the wrong layer

Do not fetch every record and filter in a JSONata transform such as $[status = "Open"]. Filter in the query instead:

query {
  workOrders(where: { status: { _eq: "Open" } }) {
    id
    status
    number
  }
}

API Explorer and Query Builder

The fastest way to learn Fuuz GraphQL is to let the built-in tools write it for you. Go to System > Business Intelligence > API Explorer in any tenant. The Query Builder is under Tools at the top of the editor, and everything runs against your tenant's schema in real time.

• Visual query building. Pick the model, check the fields you want, and the Query Builder writes the GraphQL.
• Relationships one click away. Related models appear as expandable nodes. Click one to include its fields, with no join syntax.
• Field descriptions. Click the pencil icon next to a field to see its description, data type and arguments.
• Live code view. Click ** GraphQL Code** to see the query as you build it, then copy it into a screen binding or flow node.
• Variable explorer. Click $ to see the available variables, such as $where, $orderBy, $first and $after, with their exact types.
• Field arguments reduce scripting. Duration fields can return ISO 8601 text or milliseconds, and float fields can round up, to nearest or down. Check for an argument before writing a transform to format a value.
• Saved queries become APIs. Save a query or mutation from the Explorer and it appears in your external API list, with no server code to write.

A learning path

1. Open API Explorer > Tools > Query Builder.
2. Select your model and check the fields you need.
3. Click the pencil on a field to read its description and arguments.
4. Click $ to see the variables and their types.
5. Click ** GraphQL Code** to view the generated query.
6. Copy the query into your screen binding or flow node, and test it in the Explorer first.

Do this a dozen times across different models and Fuuz GraphQL will feel natural.

Data Flow Engine

The Data Flow Engine sits above the GraphQL layer. It is your application's business logic layer: built visually, with the option to drop into JavaScript for complex operations. Flows call GraphQL APIs to read and write data, then use the transformation layer to process the results. Keep that order in mind when you trace what triggered what.

• Integrate without rip and replace. Connect external systems and work with their data where it lives, orchestrated through Fuuz flows, GraphQL queries and MCP tools.
• Flows are MCP tools. Every data flow is also a Model Context Protocol tool, so AI agents can orchestrate flows, and integration nodes can build deterministic agentic workflows.
• Pub/sub, topics and webhooks. Create your own topics and webhooks for real-time, event-driven integrations without polling.
• Debug with the console and logs. Every transform node shows its input and output in the Flow Console, so you can inspect the data at each step without adding debug nodes. Check the console of the relevant transform before assuming the problem is upstream.

Fuuz JSONata bindings

Standard JSONata is the foundation; Fuuz extends it with more than 200 platform bindings for screen state, user identity, flow context, joins and more. For the standard language, see the JSONata tutorial and the custom Fuuz-only JSONata library.

Two execution contexts

• Screen expressions run in the browser. You can use $components, $metadata, $card, data and $$.
• Data flow expressions run on the server. You can use $state, $state.context and $state.claims. Web flows that run with screen context can also use $components and related screen bindings.

$components: work with screen elements

$metadata: URL, user and tenant

$state: data flow context

data, $card and $$: element-level bindings

Join functions and utility bindings

/* $innerJoin: match records from both sides */
$innerJoin(workOrders, parts, "partId", "id")

/* $leftOuterJoin: keep every left record, match the right */
$leftOuterJoin(workOrders, scheduledShifts, "shiftId", "id")

/* $query: run a GraphQL query inline */
$query({ "api": "system", "statement": "query { ... }", "variables": { "id": "123" } })

/* $numeral: number formatting */
$numeral(12345).format("0,0")        /* "12,345" */
$numeral(0.75).format("0%")          /* "75%" */
$numeral(1234.5).format("$0,0.00")   /* "$1,234.50" */

$now               /* ISO 8601 timestamp */
$appConfig.someKey /* tenant app configuration */

Syntax gotchas

Coming from SQL? Reframe these habits

These are the closest useful parallels, not a one-to-one mapping.

Application Graph

The Application Designer includes the Application Graph: a live, visual knowledge graph of your application that shows every relationship between data models, screens and data flows in one interactive view. It reflects your actual application, not a static diagram.

• Data models as nodes. Relationships between models are edges, the same relationships the Query Builder and GraphQL schema expose.
• Screens and flows connected. See which screens and flows use each model, so you know the impact of a schema change before you make it.
• Your starting point. Open it at the start of every new engagement, troubleshooting session or impact analysis. Combined with the Query Builder, it takes you from no context to correct GraphQL in minutes.

Build patterns

1. Design the query before the model. Start with what the screen needs to show, and shape the document to make that query simple.
2. Filter in GraphQL, reshape in JSONata. Filter with where, count and sum with _aggregate, sort with orderBy, and use JSONata only to reshape the filtered response.
3. Always return id in mutations. It confirms the write and feeds chained operations.
4. Check the console before assuming the problem is upstream. Every transform shows its input and output.
5. Request only what the screen uses. Over-fetching adds payload and makes bindings harder to read.
6. Know your JSONata context. Screens use $components, $metadata, data and $card; flows use $state. Mixing them up fails silently.
7. Map ERP writes to mutations early. When you scope an ERP integration, such as NetSuite, Plex or Business Central, identify the target mutations before writing flow logic.
8. Treat field additions as low-risk. Adding a field is fast and has near-zero downtime. The real effort is in flow logic, behavior changes and performance tuning on large collections.

The build loop: confirm the document shape in the schema designer, write the GraphQL query with predicates, reshape the result with JSONata, bind it to the screen element or flow output, then inspect each layer in the console and logs before calling it done.

Troubleshooting: debug by layer

Start at the data layer and work up, every time.

The debug order:

1. Does the data exist? Run a GraphQL query to confirm.
2. Does the query return it correctly? Run the exact binding query, with its predicates, on its own.
3. Does the JSONata transform it correctly? Inspect the input and output in the transform console.
4. Does the screen element bind correctly? Check the element's property mapping.

Skipping steps leads to false diagnoses.

What managed infrastructure means for your scope

When Fuuz hosts your environment, it changes what belongs in your delivery scope.

• Schema changes are near-instant. Add fields with near-zero downtime and iterate on the data model across sprints, without upgrade events or deployment windows.
• Security is inherited. Encryption at rest and in transit, identity and access management and audit logging are part of the platform. Do not scope custom security plumbing.
• Infrastructure is not in your scope. In Fuuz-hosted environments there are no servers, database setup, backups or failover planning for you to run. In customer-hosted environments, the customer is responsible for applying updates.
• Know the release cadence. Fuuz-hosted production environments are updated monthly, and the latest changes reach build environments first. Confirm feature availability for your release when you scope.
• Platform scale is not app performance. The platform scales, but how your application handles large datasets is a design concern you own. Complex flow logic, unindexed queries on large collections and overly dynamic bindings all affect performance. Load test with realistic data before go-live.
• Multi-site is configuration. Adding a plant or region to an existing deployment is a configuration task, not new infrastructure.

At a glance: adding a field to a model takes near-zero downtime, and one GraphQL call returns a fully hydrated object graph.

Related articles

• Aggregate Query API
• JSONata tutorial
• Custom Fuuz-only JSONata library
• Script editor
• Build on Fuuz
• Developer Bootcamp 201