Digia Architecture & Runtime

This guide details how Digia transforms a visual definition into a native mobile experience at runtime.

Core Philosophy: Just as a Web Browser reads HTML to render a webpage, the Digia SDK reads a JSON configuration to render Native Widgets. The Server sends the blueprint; the Device builds the house.

1. High-Level Architecture

Digia operates on a decoupled architecture where the UI definition is separated from the rendering logic.

• Digia Studio (The IDE): A specialized environment for building server-driven apps. It handles static analysis, data binding, visual layout, and state management to produce a robust UI definition.

• Digia Cloud (The CDN): Hosts the compiled JSON configuration, ensuring global low-latency availability.

• Digia SDK (The Runtime): A lightweight engine inside your app that fetches the configuration and renders native components.

2. The Protocol (JSON Schema)

The core communication language between Digia Cloud and your app is the SDUI JSON Protocol.

Unlike traditional APIs that just fetch data (e.g., a list of users), the Digia configuration contains everything needed to run the module:

• Pages & Navigation: The structure of every screen.

• Components & Styling: Layouts, colors, fonts, and themes.

• Logic & Actions: What happens when a user taps a button or submits a form.

• API Calls: Definitions of network requests to your own backend.

{
  "appSettings": {
    "initialRoute": "home"
  },
  "pages": {
    "home": {
      "layout": {
        "root": {
          "type": "scaffold",
          "props": { "backgroundColor": "#FFFFFF" },
          "children": {
            "body": [
              {
                "type": "text",
                "props": {
                  "text": "Hello, Server-Driven World!",
                  "style": { "fontSize": 24, "color": "#000000" }
                }
              },
              {
                "type": "button",
                "props": { "label": "Click Me" },
                "actions": { "onTap": "navigateToSettings" }
              }
            ]
          }
        }
      }
    }
  }
}

3. The Runtime (Digia UI SDK)

The Digia SDK (available for Flutter, React Native, iOS, Android) is the engine that interprets the protocol. It is not just a UI mapper; it is a full-fledged runtime environment composed of some key layers:

3.1 Core Engine (Recursive Renderer)

At its core, the SDK is a Recursive Renderer. It loops through the JSON tree and instantiates the native widgets.

• Direct Mapping: Each JSON node translates directly to a native widget. There is no "Virtual DOM" layer.

• Reactive Updates: When state changes, the SDK simply rebuilds the affected part of the tree. It relies on the native platform (Flutter, SwiftUI, Compose) to render the changes efficiently.

Performance: Since the SDK maps JSON directly to Native Widgets (e.g., UIButton, RecyclerView), you get 60fps scrolling and native gesture handling. There are no WebViews involved.

3.2 State Management System

Digia manages data at multiple levels, ensuring that complex apps can be built without fighting the framework:

1. Global Store: App-wide data (e.g., User Profile, Auth Token) accessible from any page.

2. Page State: Data scoped to a single screen (e.g., Form data).

3. Local State: Ephemeral state for individual components (e.g., Is this dropdown open?).

3.3 Logic & Interactivity

The SDK handles dynamic behavior without needing a server round-trip for every action:

• Expression Library: Supports dynamic bindings like ${user.name} or conditional visibility ${gt(cart.total, 0)}.

• Actions Manager: Orchestrates events such as navigation, API calls, or state updates (e.g., onTap: navigateToPage).

3.4 Config Manager (Network & Caching)

This layer handles the synchronization of your UI definition. It is responsible for fetching, caching, and validating the JSON/Protobuf payload.

You can configure the update strategy based on your app's needs:

1. Sync Fetch (Instant Updates):

   • On startup, the SDK checks for a new version.

   • If available, it downloads and applies it immediately for the current session.

   • Best for: Critical fixes or apps that must always show the latest content.

2. Async Fetch (Background Updates):

   • On startup, the SDK immediately requires the cached config (zero latency).

   • It checks for updates in the background. If a new version is found, it is downloaded silently and saved.

   • The next app session will use the new configuration.

   • Best for: Optimizing startup time and non-critical updates.

Resilience & Offline Mode: Our global CDN is backed by industry-standard cloud infrastructure, ensuring 99.99% uptime. However, in the unlikely event of a service disruption or network failure, the app remains fully functional by seamlessly falling back to its local cache.

4. Adoption Strategy: Start Small

You do not need to rebuild your entire app to use Digia. The architecture supports Incremental Adoption.

• Spot Integration: Use Digia for a single dynamic section, like a "Holiday Sale" banner or a "Feedback Form".

• Hybrid Page: Embed a Digia view inside an existing native screen.

• Full Screen: Build an entire "Explore" tab or "Onboarding" flow in Digia while keeping the rest of the app as-is.

5. Extending the Runtime

Sometimes you need a specialized UI element that isn't in the standard library (e.g., a 3D Model Viewer or a specialized Camera view).

Custom Widgets allow you to register your own native components with the SDK. Once registered, you can drop them into the Digia Studio visual builder just like any other component. For implementation details, see Building Custom Widgets.

void registerCustomButton() {
  DUIFactory().registerWidget<CustomButtonProps>(
    'custom/button-v1', // Unique ID used in Digia Studio
    CustomButtonProps.fromJson,
    (props, childGroups) => CustomButton(
      props: props,
      commonProps: null,
      parent: null,
      refName: 'custom_button',
    ),
  );
}