OVERVIEW
With this documentation, we try to understand, how a detailed flow including various system components will work. The document outlines end-to-end flow consisting of interaction among various system components, which is driven by the user personas or the stakeholder group (or roles).
Definitions of Roles and Responsibilities within the Platform
The platform supports following roles, which could be residing at various stakeholder groups:
Stakeholder Groups
- Platform Providers: These are providers of the frontend platform, who deliver the tools, frameworks and systems in order to develop applications based on the platform. Platform providers are contracted by the Platform Owner to support the application vendors.
- Application Vendors: These are application developers for the specific application types of iOS, Android or a Web Application. Application vendors are contracted by the client to develop applications for the products based on the platform.
- Platform Owner/Organisation: This is the stakeholder group, who has a contract to own the instance of the platform from the platform providers, who are also contracting application vendors to develop applications for their products based on the platform.
Main Roles
- Platform Developers: The platform developers develop the tools, frameworks and systems in order to deliver the platform and support application vendors.
- Application Developers: These are application specific developers, who develop either an iOS, Android or a Web Application. Application Developers can belong to one or more application vendors, contracted by the Platform Owner.
- Product Owners: Users with this role are responsible to conceptualise and deliver the product based on the platform. Product owners can belong to the stakeholder group of client or they could belong to the application vendors.
Platform Operations
The platform consists of different building blocks:
- Administrative UI: This is a configuration portal, where the organisation has product(s), which supports various tenants of the organisation. The product could be configured with two types of plugins: Dev Plugin, Workflow Plugin, which are part of the plugin catalogue.
- Frontend SDK Mobile: This is a SDK, which provides standard protocols, configurations and configurable design system to develop mobile applications consisting of various plugins for a given product.
- Frontend SDK Web: This is a SDK, which provides standard protocols, configurations and configurable design system to develop web applications consisting of various plugins for a given product.
- Backend SDK: The backend SDK provides fundamental tools to develop the backend services that support the frontend and provides framework to implement the services based on Backend-For-Frontend Framework.
The Applications are configured and developed in the development area (Dev) and deployed for execution on Execution Area (Runtime). Configurations cannot be altered in the execution area.
Application Initialization
Product development on the platform is initiated by the application vendor. The application vendor through the application developers, creates the git repositories for the intended applications for the product. Application developers should pull the Frontend SDK from JFrog Artifactory through their dependency management tool and subsequently include it in git as a dependency to manage the specific version.
Once the SDK has been pulled, application developers must implement the application and register it in the coreSDK. Application developers should set up the coreSDK with the application and optional overrides. The overrides could be for the logging module, error handling, and other related protocols. If desired, application developers could potentially use the general implementation provided by the coreSDK. Ensure to check the coreSDK documentation to confirm that the overrides work across different application types, such as mobile and web. Following is an example of existing interfaces inside coreSDK, which could be overriden.
// Define platform-agnostic interfaces
interface LoggingModule {
log(message: string): void;
}
interface ErrorHandler {
handleError(error: Error): void;
}
// Default implementations
class DefaultLoggingModule implements LoggingModule {
log(message: string): void {
console.log(message);
}
}
class DefaultErrorHandler implements ErrorHandler {
handleError(error: Error): void {
console.error(error);
}
}
// CoreSDK class with dependency injection
class CoreSDK {
private loggingModule: LoggingModule;
private errorHandler: ErrorHandler;
constructor(loggingModule?: LoggingModule, errorHandler?: ErrorHandler) {
this.loggingModule = loggingModule || new DefaultLoggingModule();
this.errorHandler = errorHandler || new DefaultErrorHandler();
}
setLoggingModule(loggingModule: LoggingModule): void {
this.loggingModule = loggingModule;
}
setErrorHandler(errorHandler: ErrorHandler): void {
this.errorHandler = errorHandler;
}
// Other coreSDK methods...
}
// Example usage
const customLoggingModule: LoggingModule = {
log(message: string): void {
// Custom logging implementation
}
};
const customErrorHandler: ErrorHandler = {
handleError(error: Error): void {
// Custom error handling implementation
}
};
const coreSDK = new CoreSDK(customLoggingModule, customErrorHandler);
Once the application setup is complete with the coreSDK including the possible overrides, the start screen needs to be implemented, which should be overriden via application. (Add details on the start screen code)
Once the application initialization is done, the product registration process should begin in the Administration UI.
Product Registration
Once the application developer has completed the application initialization, the product owner should register the product on the administrative UI (AdminUI). The product configuration contains further details regarding Generic application information, Tenant specific information, plugins that are part of the product and overrides for tenants. A tenant is a sub-entity within an organisation, that wishes to drive value with the product through their applications. With the override configurations, tenants can define tenant-specific configurations, that are only relevant for the specific tenant.
A Product configuration for AOK Test Product could look like following:
{
"product": {
"name": "AOK Test Product",
"appId": "AOK TP_app",
"description": "health navigator app.",
"version": "1.0.0",
"logo": "url_to_logo_image",
"platformsEnabled": [
"iOS",
"Android",
"Web"
],
"overrideConfigurations": {
"aokplus": [{
"menusPlacement": [
{
"id": "menu1",
"label": "Document Upload",
"link": "url",
"placementid": "bottom_1",
"parent": "",
"type": "static"
},
{
"id": "menu2",
"label": "Doctor Search",
"link": "url",
"placementid": "bottom_2",
"parent": "menu1",
"type": "static"
},
]
}],
"aokbw": [{
"menusPlacement": [
{
"id": "menu1",
"label": "Document Upload",
"link": "url",
"placementid": "bottom_1",
"parent": "",
"type": "static"
},
{
"id": "menu2",
"label": "Doctor Search",
"link": "url",
"placementid": "bottom_2",
"parent": "menu1",
"type": "static"
},
]
}],
"aoknw": [{
"menusPlacement": [
{
"id": "menu1",
"label": "Document Upload",
"link": "url",
"placementid": "bottom_1",
"parent": "menu1",
"type": "static"
},
{
"id": "menu2",
"label": "Doctor Search",
"link": "url",
"placementid": "bottom_2",
"parent": "menu1",
"type": "static"
},
]
}]
},
}
}
Upon creation of the product configuration, the configuration is saved through the BE-AdminUI-API in the separate git repository. Every created product is contained in a specific folder structure for the given organisation. The product structure includes the github configurations, then per versions, product configuration, localisation and the list of configured plugins.
This is an old structure. Refer to the API section to see the valid JSON Format.
-- AOK
-- AOK Test Product
-- github-config.json
-- v1.0.0
-- Product-config.json
-- localisation.json
-- configured_plugin.json
-- v1.0.1
-- Product-config.json
-- localisation.json
-- configured_plugin.json
-- AOK TP 2
-- github-config.json
-- v1.0.0
-- Product-config.json
-- localisation.json
-- configured_plugin.json
-- v2.0.0
-- Product-config.json
-- localisation.json
-- configured_plugin.json
Build history needs to be maintained somewhere. Once there is an update for the product_config, localisation, or configured plugins, the commit should be of a specific format: that is:
dev/aoktp2/v1.0.0/update --
This is an old structure. Refer to the API section to see the valid JSON Format.
-- AOK
-- products
-- versions.json
-- v1.0.0_github_config.json
-- v1.0.0_aoktp_config.json
-- v1.1.1_aoktp_config.json
-- plugins
-- versions.json
-- v1.0.0_aoktp_configured_plugin.json
-- v1.0.1_aoktp_configured_plugin.json
-- v1.1.1_aoktp_configured_plugin.json
-- localisations
-- versions.json
-- v1.0.0_aoktp_localisation.json
-- v1.1.1_aoktp_localisation.json
-- v1.0.2_NAVIDA_localisation.json
While creating the product configuration, github configuration has to be added for the given product with related application details. The details should support the activated application types (or enabled platforms) with the relevant git information, such as the repository URL. The Github configurations should also include information regarding the git locations of the repositories of the plugins.
Refer to the API section to see the valid JSON Format.
Product configuration for the given product needs to be extended with the required plugins from the plugin-catalogue. When a specific plugin is required in the product, product owner can select the given plugin and move it to the available plugins for the given product configuration. When the given plugin is moved to the product configuration, all the related plugin configurations are copied over in the product config. As an override configurations, plugins can be customised for the given tenants in the product configurations. The tenants configurations are part of the product configuration. If a specific plugin is not part of the available plugins, then it should be created in the plugin catalogue.
Refer to the API section to see the valid JSON Format.
Plugin Catalogue and Instanciation for a given product
Application vendors can create two types of plugins for the application. Every Plugin should be maintained in the plugin catalogue and should have a separate plugin repository.
- Developed Plugin (Feature Plugin): A Plugin, which delivers a custom, non-workflow-based functionality. For example, a "Doctor Search" plugin could allow users to search for doctors based on location, specialty, or availability. This plugin might include a native implementation for mobile platforms or a webview for web applications, providing a seamless user experience without relying on a predefined business process.
- Workflow Plugin: A Workflow-Plugin delivers step-driven, workflow-based functionalities. For instance, a "Document Upload" plugin could guide users through a multi-step process to upload and verify documents. This workflow could be designed using a BPMN Editor in the AdminUI, allowing for customization of steps such as selecting a file, validating its format, and confirming the upload.
The plugin-catalogue for every Plugin should contain details on the name, type, catalogueId, which is a unique identifier for the plugin in the plugin catalogue along with the plugin version. It should also contain plugin specific configurations. If the type of the plugin is a workflow plugin, then If it is a workflow plugin, the workflow xml should be part of the plugin repository.
Refer to the API section to see the valid JSON Format.
Building the Versions for the product
A Product Owner (or an equivalent role for releases) can trigger the Versions for the applications associated with the product. The Trigger to build the application can be instantiated through AdminUI for the given frontends, AdminUI sends the trigger details via the BE-AdminUI-API, where the trigger includes tag for the DevOps Pipelines. The Tag follows a specific format, which explains, which environment, version and the appname needs to be deployed.
Pipeline will send back the status of the build creation to BE-AdminUI-API and FE should showcase it.
Giving the first endpoint to FE Team.
{
Tag Format: <env>/<organisation>/<appid>/<config-version>
Example : dev/aok/aoktp2/1.0.0
Configuration Update: dev/aok/aoktp2/1.0.0/update
}
Based on the tag, BE-AdminUI-API automatically directs the related artifacts to the appropriate branch, either "main" or "master," for the specific product. If both branches exist, the system prioritizes the "main" branch by default unless explicitly configured otherwise. The DevOps Pipeline picks up the artifacts from the product repository to initiate the build pipeline. These artifacts include the git configuration of the application, which contains the git-link to the application repository and the details of the configured plugins.
Runtime (Execution Phase)
Parallely, the DevOps pipeline initiates the transfer of the git content for the product including product configuration, plugin configuration and the localisation to the volume storage in the execution phase.
In the event of update of a specific configuration, be it product, configured plugins, or localisation, if the timestamp for given version gets updated, then it needs to be pushed to volume storage, provided the build for the version is triggered in the runtime and is successful. A tag with update will be sent by the BE-AdminUI-API to trigger the pipeline in above format.
The deployed versions in the Runtime access the product configuration through the FE Common API in the execution phase (runtime).