chore: add custom apps guide

docs/platform/3.core/7.apps.md

@@ -4,7 +4,8 @@
 
 DIAL-native applications adhere to the [unified protocol](/docs/platform/3.core/0.about-core.md#unified-api) of DIAL, a single protocol for all applications and models deployed in a specific DIAL instance. DIAL-native apps can be enabled in DIAL and used directly (via API or UI) or as building blocks in other apps.
 
-> Refer to [Agentic Platform](/docs/platform/0.architecture-and-concepts/4.agentic-platform.md) to learn more about agents in DIAL.
+> * Refer to [Agentic Platform](/docs/platform/0.architecture-and-concepts/4.agentic-platform.md) to learn more about agents in DIAL.
+> * Refer to [Custom Apps](/docs/tutorials/1.developers/4.apps-development/6.develop-custom-apps-overview.md) to learn about custom applications in DIAL.
 
 ## Schema-rich Applications
 
@@ -14,21 +15,24 @@ Schema-rich applications are defined by a JSON schema that conforms to the main
 
 Users can create instances of schema-rich applications with different properties via [DIAL Core API](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomApplication). There is a method in [DIAL SDK](https://github.com/epam/ai-dial-sdk) (`application_properties = await request.request_dial_application_properties()`) that returns application properties with a configuration request to DIAL Core.
 
-Unlike [apps without schemas](#applications-without-schemas), where business logic properties are embedded in the application code or container environment and are difficult to change, schema-rich applications provide greater flexibility.
+**Application Runners** are used to run schema-rich applications. An application runner can be seen as an application factory that allows end-users create individual logical instances each with its own configuration. An application runner definition includes a configuration schema that enforces data structure persisted for each instance. It is worth noting that Quick Apps, Code Apps and Mind Maps are application runners available in DIAL platform out of the box. DIAL admins can add and manage runners in the [DIAL Admin application](/docs/tutorials/3.admin/builders-application-runners.md).
+
+Unlike [apps without schemas](#standalone-applications), where business logic properties are embedded in the application code or container environment and are difficult to change, schema-rich applications provide greater flexibility.
 
 ### Application Types
 
 Schema-rich applications are usually associated with a specific **Application Type** - as schema-rich template for creating custom implementations of specific application types.
 
-The [meta schema](https://github.com/epam/ai-dial-core/blob/development/config/src/main/resources/custom-application-schemas/schema) determines a possible structure of an application type schema, which is used to determine properties structure of specific applications of this type:
+The [meta schema](https://github.com/epam/ai-dial-core/blob/development/config/src/main/resources/custom-application-schemas/schema.json) determines a possible structure of an application type schema, which is used to determine properties structure of specific applications of this type:
 
 ![](./img/schema-rich-apps.svg)
 
-One of the main advantages of application types, is that they allow adding [application wizards](/docs/tutorials/0.user-guide.md#application-builder) on UI for end-users to create/edit apps in a low and no-code manner.
+One of the main advantages of application types, is that they allow adding [application wizards](/docs/tutorials/0.user-guide.md#application-builder) on UI for end-users to create/edit apps in a low and no-code manner via a UI editor.
+
+Out of the box, DIAL includes application types such as Quick app, Code app and Mind Map. Users of DIAL Chat can use UI wizards to create custom instances of these application types.
 
-:cloud: DIAL SaaS edition includes application types such as Quick app, Code app and Mind Map. Users of DIAL Chat can use UI wizards to create apps of these types.
+:floppy_disk: In self-hosted deployments of DIAL, you can add new application types, featuring custom application UI (`applicationTypeViewerUrl`) and wizards (`applicationTypeEditorUrl`) and enabling end-users to create applications of that type. Refer to [Custom Apps](/docs/tutorials/1.developers/4.apps-development/6.develop-custom-apps-overview.md) to learn about custom applications in DIAL.
 
-:floppy_disk: In self-hosted deployments of DIAL, you can add new application types, featuring custom application UI (`applicationTypeViewerUrl`) and wizards (`applicationTypeEditorUrl`) and enabling end-users to create applications of that type.
 
 #### Quick Apps
 
@@ -78,9 +82,9 @@ Mind Map enables users to explore information through an interactive knowledge g
 > - Watch [Demo Video](/docs/video%20demos/2.Applications/mindmap-studio.md) to see [DIAL Mind Map Studio](/docs/tutorials/4.mind-map.md) in action.
 > - Refer to solutions to see implementations in specific industries: [Caspase-2 Article Visualization](https://dialx.ai/solutions/scientific-literature-knowledge-graph), [OMICS AI Assistant](https://dialx.ai/solutions/omics-data-assistant), [Visualization of Cinematic Universe](https://dialx.ai/solutions/lotr-universe-case)
 
-## Applications without Schemas
+## Standalone Applications
 
-Applications without schemas are not tied to any specific application type. When enabling such an app, you must explicitly specify (in the [API PUT request](/docs/tutorials/1.developers/4.apps-development/3.enable-app.md#using-api-1) standard parameters of the application and available endpoints the application offers. Properties that define the logic and behavior of the application are part of the application code and the container it runs in, meaning they cannot be modified through the DIAL Core API, contrary to [schema-rich applications](#schema-rich-applications). For example, to enable two apps without schemas, you may need to launch two containers, whereas for schema-rich apps, you can make just two API calls.
+Standalone applications are not tied to any specific application type nor their structure is defined by a JSON schema. When enabling such an app, you must explicitly specify (in the [API PUT request](/docs/tutorials/1.developers/4.apps-development/3.enable-app.md#using-api-1)) standard parameters of the application and available endpoints the application offers. Properties that define the logic and behavior of the application are part of the application code and the container it runs in, meaning they cannot be modified through the DIAL Core API, contrary to [schema-rich applications](#schema-rich-applications). For example, to enable two apps without schemas, you may need to launch two containers, whereas for schema-rich apps, you can make just two API calls.
 
 ## Create Applications
 
@@ -111,7 +115,7 @@ Ready and deployed applications must be enabled to use them in DIAL.
 **Prerequisites for enablement of schema-rich applications:**
 
 - A schema of the application type must be included in the DIAL Core configuration.
-- Having a running container for each application type.
+- An application runner container must be running for each application type.
 - These containers must be accessible via the endpoints specified in the JSON schema for their respective application types.
 
 **Prerequisites for enablement of for applications without schemas:**

docs/tutorials/1.developers/4.apps-development/6.develop-custom-apps-overview.md

@@ -0,0 +1,80 @@
+# Developing Custom DIAL Applications
+
+## Introduction
+
+Whenever the no-code and low-code DIAL extensibility features such as [Quick Apps](/docs/platform/3.core/7.apps.md#quick-apps), [Code Apps](/docs/platform/3.core/7.apps.md#code-apps) or [Mind Maps](/docs/platform/3.core/7.apps.md#mind-maps) are not sufficient to satisfy the needs of a particular use case, a custom application can be developed in any technology stack and exposed through the DIAL platform. From an end-user perspective, such applications will be accessible through the [DIAL Marketplace](/docs/platform/4.chat/1.marketplace.md) similarly to models and standard platform applications.
+
+There are two forms of custom applications in DIAL:
+
+- [Custom Standalone Application](/docs/tutorials/1.developers/4.apps-development/7.develop-single-app.md) – exists as a single logical instance in the platform. Settings and access permissions are managed centrally by an administrator. For example, it can be a standalone document summarization tool, where a platform administrator defines summarization options and quotas.
+- [Custom Application Runner](/docs/tutorials/1.developers/4.apps-development/8.develop-app-runner.md) – an application factory that allows end-users create individual logical instances each with its own configuration. For example, a custom RAG application runner may allow an end user to configure a personalized RAG agent by connecting it to chosen data sources, such as internal knowledge bases, document repositories, or external APIs, and then share it with other users and groups. An application runner definition includes a configuration schema that enforces data structure persisted for each instance. It is worth noting that Quick Apps, Code Apps and Mind Maps are application runners available in DIAL platform out of the box. 
+
+Regardless of the form, a custom DIAL application may consist of three separate components – Backend, Viewer UI and Editor UI. The purpose and necessity of each one is indicated in the table below.
+
+|Component|Custom Standalone Application|Custom Application Runner|
+|---------|-----------------------------|-------------------------|
+|Backend|Implements the business logic.<br />**Required**|Implements the business logic.<br />**Required**|
+|Viewer UI|An alternative end-user UI (is needed when the default chat interface is not sufficient).<br />**Optional**|An alternative end-user UI (is needed when the default chat interface is not sufficient).<br />**Optional**|
+|Editor UI|A UI screen for managing application settings from the [DIAL Admin](/docs/tutorials/3.admin/home.md) application.<br />**Optional**|A UI screen for configuring application settings when creating or updating a logical application instance.<br />**Required**|
+
+There are a few typical sets of components to be developed for a custom DIAL application depending on the use case:
+
+- Backend only – when end-users of a Custom Application are supposed to interact with the application through the default chat interface and there are no application settings to be managed by the DIAL administrator.
+- Backend and Admin UI – when a Custom Application has some settings to be managed by the DIAL administrator or you are building a Custom Application Runner, while there is no need to have a custom end-user UI.
+- Backend, Admin UI, and End-user UI – when a non-standard end-user UI is needed, and the Custom Application has some settings to be managed by the DIAL administrator, or you are building a Custom Application Runner.
+
+Here is an example of a custom Editor UI accessible through the DIAL Admin for a standalone application:
+
+![](../img/overview1.png)
+
+The screenshots below illustrate a typical user flow for an Application Runner, using Mind Maps as an example where both the Viewer and Editor UIs are customized:
+
+1.	All Application Runners that the current user has access to, are available in the “Add App” dropdown in the [user’s Workspace](/docs/tutorials/0.user-guide.md#my-workspace).
+
+    ![](../img/overview2.png)
+
+2.	After populating the General Info tab and proceeding to the App Settings, a custom Editor UI will appear.
+
+    ![](../img/overview3.png)
+
+    ![](../img/overview4.png)
+
+3.	A custom Viewer UI can be seen when a user opens a logical application instance created this way from his DIAL Workspace or Marketplace.
+
+    ![](../img/overview5.png)
+
+The diagram below shows the most complete logical structure of a Custom Standalone Application:
+
+![](../img/overview6.png)
+
+And the following diagram – the most complete structure of a Custom Application Runner:
+
+![](../img/overview7.png)
+
+## Backend
+
+A backend service that implements the necessary business logic and exposes either a standard Open AI chat completion endpoint, or a set of custom API endpoints, or both. Can be implemented using any technology stack, but for simple cases, when only a chat completion endpoint needs to be exposed, it is recommended to use [DIAL SDK for Python](https://github.com/epam/ai-dial-sdk).
+
+For Application Runners, this SDK provides an easy way of getting configuration details about the calling instance (see `request_dial_application_properties` method). These properties are usually managed via a custom Editor UI and are validated by DIAL Core against the configuration schema provided for the application runner. 
+
+The service doesn’t have to validate tokens, since authorization is handled by DIAL Core, which serves as an API gateway in this scenario. When forwarding a call to a backend endpoint, DIAL Core passes a [per-request key](/docs/platform/3.core/3.per-request-keys.md) in the `“api-key”` header instead of the original authorization header, which can later be used by the backend logic to call DIAL Core back for accessing models or other applications.
+
+## UI
+
+Both UI pieces are developed and hosted as standalone applications, but when registered in the platform, they get embedded as IFRAME into respective DIAL UI applications, providing integrated experience.
+
+There are no limitations on the technology stack, but it is recommended to use the [Next.js solution template](https://github.com/epam/ai-dial/tree/main/dial-samples/common-ui-app), since it already has all necessary boilerplate code including the authentication mechanism.
+
+As shown on the diagram above, each of the custom UI applications is supposed to be hosted on a separate subdomain. In order to issue a JWT token for accessing endpoints exposed by DIAL Core, each custom UI application must have its own client registration with the Identity Provider. Separate client registrations allow for more granular control over permissions and scopes, enabling each application to request only the access it requires, which aligns with the principle of least privilege. This separation also simplifies auditing and monitoring, as it becomes easier to trace and identify which application is responsible for specific API calls or security events.
+
+Communication with the corresponding backend service is always made through DIAL Core. When the backend exposes custom API endpoints, the corresponding [routes](https://github.com/epam/ai-dial-core/blob/development/docs/dynamic-settings/routes.md) must be configured in the DIAL Core configuration to make them reachable for the UI application.
+
+For Editor UI of an Application Runner it is recommended to save instance configuration in the application object – data stored in `application_properties` attribute of an application instance is validated against the schema provided for the corresponding Application Runner, persisted, and then can be read by the backend depending on the calling instance. 
+
+## Deployment
+
+There are no limitations of how and where the custom components are deployed, the only requirement is that there must be network connectivity between DIAL Core and the backend service, as well as between UI applications and DIAL Core. Any communication between components is made only through API.
+Here are the links to sample configuration guides for different types of applications:
+
+- [Standalone application](/docs/tutorials/1.developers/4.apps-development/7.develop-single-app.md)
+- [Application runner](/docs/tutorials/1.developers/4.apps-development/8.develop-app-runner.md)