Glossary

GraphQL

GraphQL is a query language and runtime for APIs that provides a flexible and efficient alternative to traditional REST APIs. Unlike REST, where fixed endpoints return predefined data, GraphQL allows clients to request only the data they need, reducing unnecessary data transfers (over-fetching and under-fetching).

With GraphQL, clients can retrieve, modify, and subscribe to real-time updates from a single endpoint. Its strongly-typed schema defines the structure of data and the available operations, enabling multiple queries in a single request.

In Optimal Reality (OR), GraphQL acts as the link between back-end microservices, the database, and the front-end. It enables applications to efficiently query, update, and stream data without relying on multiple API endpoints.

Before setting up a GraphQL data service, it’s essential to understand its key components and how they interact within OR.

Term	Description
Schema	A GraphQL schema defines the structure of data and the operations that can be performed on it. It acts as a contract between the client and server, outlining available data types, their relationships, and the actions that can be executed.
Types	GraphQL types define the shape of data that can be queried or modified.
Scalar Types	Basic data types such as Int, Float, String, Boolean, and ID.
Object Types	More complex structures that contain multiple fields (e.g., a User type with name, email, and age).
Enum Types	A special type that restricts values to a predefined set (e.g., Status with values ACTIVE, INACTIVE).
Input Types	Used for sending structured data as input for mutations.
Queries	A query is a request for data from the server. Clients specify the fields they need, and the server returns only the requested data. Queries are similar to GET requests in REST APIs.
Mutations	A mutation is an operation that modifies data on the server. It allows clients to create, update, or delete records while ensuring data consistency. Mutations are similar to POST, PUT, or DELETE requests in REST APIs.
Subscriptions	A subscription enables real-time updates by notifying clients when specific events occur on the server. This allows applications to receive live updates instead of manually polling for changes.
Resolvers	A resolver is a function that retrieves data for a specific field in the schema. It defines how the server responds to queries, mutations, and subscriptions, ensuring that the correct data is fetched and returned.
Directives	A directive modifies the behavior of queries or mutations. It can be used to conditionally include or exclude fields, apply transformations, or execute custom logic.
Operations	Operations refer to queries, mutations, and subscriptions that clients execute against the API. These actions define how data is retrieved or modified within the system.
Introspection	Introspection allows clients to query details about the schema itself. This helps GraphQL IDEs and documentation tools explore available types, fields, and operations dynamically.

FDK

FDK (Frontend Development Kit) is a tool that lets you build dashboards and applications without writing code. You describe what you want your application to look like and what information it should display, and the FDK automatically creates it for you.

The FDK includes a Panel Builder, a drag-and-drop tool that allows you to visually design your screens by adding elements like charts, tables, and buttons. This makes it possible for anyone to create applications, even if they've never programmed before.

Restaurant Analogy

Think of the FDK as the menu and dining area of a restaurant. Just as a menu presents available dishes to customers in an attractive, easy-to-understand format, the FDK creates the user interface that presents data and functionality to your application users. The Panel Builder is like arranging tables and designing the dining experience — you're creating the environment where users interact with your application.

Term	Description
Configuration	A JSON file (or.config.json) that describes your entire application structure. This includes what panels to show, which components to use, and how data flows through the interface. The FDK reads this file and generates working code automatically.
Panel	A section or page in your application interface. Think of it like a tab or screen that displays information. For example, a "Dashboard" panel might show charts and metrics, while a "Map" panel shows geographic data.
Component	An individual building block of the interface — like a chart, table, button, or form field. Components are the visual elements users interact with.
Panel Builder	A drag-and-drop visual tool for composing user interfaces. Users place components onto a canvas, connect them to data, and configure their appearance — all without writing code.
DynamicPanel	A flexible screen that can change what it displays based on settings you provide. Instead of being fixed, it reads instructions from a configuration file to decide which elements to show and where to put them. This means you can completely redesign the screen just by editing the settings file, without needing a programmer.
DynamicForm	A special component that creates forms based on configuration. It automatically generates input fields, validation rules, and submission logic from a configuration file, so forms can be modified without writing code.
Props	Short for "properties" — the settings or inputs passed to a component. For example, a chart component might have props for the chart title, colors to use, and which data to display.
Binding	Connecting a component's property to a data source. For example, binding a table's "data" prop to a query result means the table automatically shows whatever data the query returns.
State	The current values and settings in your application. For example, "is the sidebar open?" or "what item did the user select?". State changes when users interact with the interface, and components update to reflect those changes.
Micro-frontend	An independent mini-application that can be loaded and displayed as part of a larger application. In OR, each team can build their own micro-frontend with its own features and release it independently of other teams' work.
Scaffold/Scaffolding	Automatically setting up the foundation and starting files for a new application. Like how a building scaffold provides the framework for construction, the FDK creates the basic folder structure and essential files you need to get started, saving you from having to set everything up manually.
Repeater	A special component that displays a list of items by repeating the same layout for each item. For example, a repeater showing a list of users would display the same card design for each user, automatically populated with their specific information.
Action	Something that happens in response to user interaction or an event. For example, clicking a button might trigger a "save" action that stores data, or a "delete" action that removes an item.
Transform	A pre-defined operation that modifies data or state in a common way. For example, "push" adds an item to a list, "toggle" switches a value between true and false, "increment" increases a number by one.
Query	A request to fetch (retrieve) data from a server or database. For example, a query might ask "get me the list of all users" or "show me today's sales data." Queries only read data, they don't change it.
LazyQuery	A query that waits for you to trigger it instead of running automatically. Like a "search" button — the data doesn't load until you click it. This is useful when you only need certain information in specific situations, not every time the page loads.
Mutation	A request to change data on the server — creating, updating, or deleting records. For example, "save this form" or "delete this item" would be mutations. The name comes from "mutating" (changing) the data.
Subscription	A long-running connection that automatically sends updates when data changes on the server. For example, a subscription might notify your interface whenever a new message arrives, so it can update in real-time without you having to refresh the page.
Variant	A style variation or different version of a component. For example, a button might have variants like "primary" (bold and prominent), "secondary" (subtle), or "destructive" (red, for dangerous actions like delete). Variants control how something looks or behaves.
H3 Hexagon	A geographic coordinate system that divides the world into hexagonal cells. Instead of using latitude/longitude points, H3 groups nearby data into hexagons, making it easier to visualize density and patterns across geographic areas.
Conditional	A component or logic that shows different content based on whether a condition is true or false. For example, show a "Welcome back!" message if the user is logged in, otherwise show a "Please sign in" message.

DDK

DDK (Data Development Kit) is a schema-driven tool for building GraphQL servers that manage your application's data layer. You define your data model — the objects, fields, and relationships you need — and the DDK automatically generates a production-ready server with a PostgreSQL database, Redis caching, and full create/read/update/delete (CRUD) operations.

The DDK uses a visual interface where you can drag and drop objects and fields to design your database schema, or you can write GraphQL schema code directly. Once defined, the DDK builds all the APIs and database structures your application needs.

Restaurant Analogy

Think of the DDK as the pantry and kitchen storage of a restaurant. Just as a well-organized pantry keeps all ingredients labeled, shelved, and ready to retrieve, the DDK organizes all your data in a structured, accessible way. When the chef (MDK) needs ingredients to cook a dish, they know exactly where to find them. The DDK ensures your data is stored properly, easy to access, and ready to use.

Term	Description
Server	A DDK server is your data schema service. It acts as the API layer that manages all database operations for your data objects. One project can have multiple DDK servers to organize different data domains.
Object	A definition of a data record type in your system, equivalent to a table in a database. For example, a User object defines the structure of user records. If you'd put it in a separate spreadsheet tab, it should be a separate object.
Primary Key	A unique identifier for each record in an object/table. By convention, this is usually an id field. Every database-backed object must have a primary key.
Foreign Key	A field that links one object to another by referencing the primary key of the related object. Foreign keys create relationships between different data objects.
Migration	A database migration applies your schema changes to the actual database, creating or modifying tables to match your defined structure. Migrations ensure your database stays in sync with your schema definition.
Trigger	A trigger links your DDK to the MDK, allowing data operations to automatically kick off workflows. When enabled on an object, creating or updating a record can trigger a simulation or AI model to run.
Regenerate	The process of validating your schema structure and generating the necessary code. You must regenerate successfully before building or deploying changes.

MDK

MDK (Modelling Development Kit) is an orchestration tool for building AI/ML workflows and simulations. You chain together AI models, data transformers, and external data connections into repeatable, auditable pipelines that process your data and generate insights.

The MDK allows you to visually design workflows that take inputs (from your DDK), run them through various processing steps (like machine learning models or simulations), and produce outputs (stored back in your DDK).

Restaurant Analogy

Think of the MDK as the chef and the cooking process in a restaurant. Just as a chef takes ingredients from the pantry (DDK) and transforms them into finished dishes through cooking techniques, the MDK takes your data and processes it through AI models and workflows to create valuable insights. The MDK is where the transformation happens — where raw data becomes actionable intelligence.

Term	Description
Workflow	A sequence of connected steps that process data. Each workflow takes inputs, runs them through various operations (like AI models or data transformers), and produces outputs. Workflows are repeatable and can be triggered automatically.
Model	An AI or machine learning model that processes data. Models can be pre-built (from OR's template library), brought from external sources, or custom-trained for your specific use case.
Template	A pre-built workflow pattern or model that you can use as a starting point. OR provides templates for common operations like traffic simulations, route optimization, and forecasting.
Trigger	A mechanism that starts a workflow. Triggers can be manual (user clicks a button), automatic (when data is created/updated in the DDK), or scheduled (run at specific times).
Input/Output	Inputs are the data and parameters a workflow needs to run. Outputs are the results the workflow produces. Inputs typically come from DDK objects, and outputs are typically saved back to DDK objects.
Step/Node	An individual operation within a workflow. Steps can include data transformations, model executions, API calls, or conditional logic. Steps are connected in sequence to form the complete workflow.
Deployment	Making a workflow available to run in your environment. Deployed workflows can be triggered by applications or data operations.