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.

Term	Description
JSON	JSON stands for JavaScript Object Notation. It is a simple text file that stores information in an organised, structured way so that both people and computers can read it.
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.
Data Connection	A link between your interface and a data source (like a database). It defines what data to fetch and when to fetch it, so components can display live information.
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.
Component Bindings	The collection of all connections between a component and its data sources or values. Think of it as the instruction sheet that tells each part of a component where to get its information from — whether from a query, user input, or fixed values.
Static Value	A fixed value that doesn't change, as opposed to data that comes from a query or user interaction. For example, setting a chart title to "Sales Dashboard" is a static value — it stays the same every time, unlike data that updates.
Context Provider	A container that holds shared information (state) that multiple parts of your application can access. For example, a "user context" might store the current user's name and settings, making it available throughout the app.
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.
Component Registry	A catalog of available components that can be used in panels. Think of it like a menu of building blocks — charts, tables, maps, buttons — that users can choose from when building interfaces.
Schema	A definition that describes the structure of data or configuration. It specifies what fields exist, what types they are (text, number, etc.), and which ones are required. Schemas ensure data follows the correct format.
API	Application Programming Interface — a way for different software systems to communicate. In OR, the FDK uses APIs to request data from backend services and display it in the interface.
Endpoint	A specific address in an API where you can request or send data. For example, a /users endpoint might return a list of users, while a /save endpoint might save changes.
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.
or.config.json	The configuration file that defines an FDK application. It contains all the information about panels, components, data connections, and layout — everything the FDK needs to generate a working application.
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.
Payload	The actual data being sent or received. For example, when submitting a form, the payload would be the information entered into the form fields. When receiving query results, the payload is the data returned by the server.
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.
CTA	Call To Action — a button or element that prompts users to take a specific action. For example, "Get Started," "Sign Up," or "Learn More" buttons are CTAs. In FDK, "leftCta" or "rightCta" refers to action buttons positioned on the left or right side of a panel header.
className	A property used to apply custom styling to a component. It specifies CSS (styling) classes that control the component's appearance — colors, spacing, fonts, etc.
Template	A pre-designed starting point or pattern that can be reused. Templates provide a basic structure that you can customize for your specific needs, saving time by not starting from scratch.
deck.gl	A library for creating high-performance, interactive map visualizations. In the FDK, deck.gl powers map layers that can display thousands of data points, routes, and geographic information smoothly.
Layer	In map visualizations, a layer is a separate visual element overlaid on the map. For example, one layer might show roads, another might show data points, and another might show boundaries. Layers can be turned on/off and styled independently.
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.
Route/Routing	The system that determines which page or panel to show based on the URL. For example, /dashboard might show the dashboard page, while /settings shows the settings page. Routing makes navigation between different parts of the application work.
Variable	A named container that holds a value that can change. For example, a "userName" variable might store different names for different users. Variables let you reference and reuse values throughout your configuration.
Field	A single piece of data within a larger structure. For example, a user object might have fields like "name," "email," and "age." Each field holds a specific piece of information.
Path	A string that describes how to navigate through nested data to reach a specific field. For example, "user.profile.name" is a path that means: go to user, then to profile inside user, then to name inside profile.
Array	A list or collection of items stored in order. For example, an array of users [user1, user2, user3] or an array of numbers [10, 20, 30]. Arrays let you work with multiple items of the same type.
Object	A collection of related fields grouped together. For example, a user object might contain { name: "John", age: 30, email: "john@example.com" }. Objects organize related information into a single unit.
String	A data type representing text — any sequence of characters. For example, "Hello World", "user@email.com", or "12345" (as text, not a number). Strings are always enclosed in quotes in configuration.
Number	A data type representing numeric values — integers or decimals. For example, 42, 3.14, or -100. Numbers don't need quotes and can be used in mathematical operations.
Boolean/Bool	A data type with only two possible values: true or false. Booleans are used for yes/no decisions, like "is the user logged in?" or "should this panel be visible?"
Union	When a field can accept multiple types of values. Like a form field that could accept either text or a number — you could enter "Name" or 123, and both would be valid. It's like saying "this can be A or B or C."
ID	Short for "identifier" — a unique value that distinguishes one item from another. For example, each panel has a unique ID so the system can reference it specifically. IDs ensure no confusion when working with multiple similar items.
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.
Null/Undefined	Special values representing "no value" or "missing data." Null explicitly means "intentionally empty," while undefined means "this hasn't been set yet." Both indicate the absence of a real value.
Nested	When something is placed inside something else, creating layers. For example, nested components means components inside other components, or nested data means objects inside objects.
Key-Value Pair	A fundamental data structure where a key (name) is associated with a value. For example, in { "age": 30 }, "age" is the key and 30 is the value. Objects are collections of key-value pairs.
Dependency	When one piece of code relies on another piece to work correctly. For example, a panel might depend on a data connection — it can't display data without it. Dependencies determine what order things must be loaded or configured.
Validation	The process of checking whether data meets certain rules or requirements. For example, validating that an email field actually contains a valid email address, or that a required field isn't empty.