# Guidelines for App Development Utilizing the insureMO Platform

## Purpose of the Guidelines

These guidelines serve to establish best practices for developing applications on our PaaS platform. They aim to streamline the development process, ensure compliance with platform standards, and promote effective integration and maintenance practices, ultimately enhancing the user experience and application performance.

## insureMO App Overview

### What is insureMO App?

insureMO App refers to any application that uses insureMO APIs, utilities, data or other services. The table below shows 3 major types.

| Type | Tech stack | Deployment | Major difference | Example |
| ---      |  ------  |---------|---------|---------|
| 1   | Client's or Vendor's choice  | Client's or Vendor's choice  | developed using any technology, no insureMO hosting and development support  | native mobile app, sales portal, vendor app that integrates with insureMO's API  |
| 2   | insureMO API Services  | k8s on insureMO public cloud or client's private cloud | use insureMO API services to build APIs, start with an existing reference sample or from scratch | iComposer, iHub|
| 3   | insureMO App Framework  | k8s on insureMO public cloud or client's private cloud | use insureMO tech stack and hosting service, start with an existing app template | Easy Apps, Gemini Apps|

### insureMO App Artifacts

An insureMO App may have the following artifacts.

![artifacts](./image/app_dev_overview/app_artifacts.png)

These artifacts can be divided into two types:

| Type | Features | Examples |
| --------- | --------- | --------- |
| Physical Artifacts  | packaged into a container image and deployed to hosting environment  | code, product config data, DB script |
| Standalone Artifacts | used by the application  | middleware, APIs |

### Relation Between App and insureMO Platform

**insureMO View**

![insuremo_overview](./image/app_dev_overview/insuremo_overview.png)

**Component View**

![component](./image/app_dev_overview/component.png)

* An insureMO client tenant may have multiple Apps.
* Each App contains 1 or more service projects (also known as BFF).
* Each App may have 1 or more UI projects. Some Apps don't have UI projects, for example, channel integration Apps which only provide customized APIs.
* Apps call insureMO platform APIs to use the business and technical services provided by the platform, such as calculating premiums or sending SMS.

### insureMO Configurations and its Relation with App

insureMO **configurations** are meta data used to describe insurance products and implement insurance apps. Configurations can be classified into the following 2 types:

* **Product Configuration**
  * Describe product structure (also known as policy model): data dictionary, data tables, code tables, rules, rating, etc.
  * [Example for General Insurance Travel Scenario](https://docs.insuremo.com/common/doc_00000426#1-product-structure-configuration)
* **System Configuration**
  * Describe configuration groups: I18n text, URP (User, Role, Permission), menu, data tables, and code tables.
  * [Example for Travel Scenario](https://docs.insuremo.com/common/doc_00000427#1-configuration-group-configuration1)

Configurations should be defined in the **MC** (Master Configuration) environment, and then be exported and deployed to the insureMO runtime environment by using CICD tools. The exported data is referred to as **Bizdata**.

* MC environment URL: `<https://tenantcode***.insuremo.com/>`
* Example: MC for insureMO GI tenant: `<https://tenantcode***.insuremo.com/>`

insureMO apps use insureMO configurations in many cases, such as:

* **product structure:** describe multi-layer insurance products
* **code table:** render fields of drop-down lists
* **I18n:** render different language texts
* **URP:** display different menus for different user roles

### Tools for App Development

The following tools are used in App development.

* **Console** is the entry point to view products, Apps, dev environments, and to link to other tools.
* **DevOps** builds and deploys applications and manages k8s pods.
* **Monitoring** searches logs and views API trace information.
* **Config Center** views and edits application configurations.
* **API Management** registers, views and tests APIs, generates access tokens to call APIs.

## Application Development Models

This section outlines the various development models available for building applications on our PaaS platform. It includes three primary approaches:

* **Pure API Consumption**, which allows for complete flexibility in technology choices.
* **Using the Platform's JAVA SDK**, which simplifies integration with platform services.
* **Using the Platform's App Framework**, which provides structured tools for front-end and back-end development.

Each model caters to different development needs and preferences, ensuring that developers can choose the most suitable approach for their projects.

![Models](./image/app_dev_overview/app_dev_models.png)

### Pure API Consumption (Recommended)

Developers have the freedom to select their technology stack while solely consuming the platform’s APIs. This model emphasizes flexibility, allowing for customized application development, deployment, and maintenance. Developers are encouraged to document their API interactions and manage their own infrastructure.

#### Consuming Atomic APIs

Developers can create applications that solely consume the platform’s atomic APIs, maintaining their own infrastructure while ensuring effective management of transaction behaviors.

Developers should consider the configuration and behavior of atomic APIs, including product configurations, rule settings, rate tables and etc. Global transaction management is crucial when interacting with multiple atomic APIs to ensure data consistency.

[Atomic API References](https://docs.insuremo.com/tech/pro/sdk/api)

#### Building business APIs in iComposer

Utilize the orchestration service - **iComposer** to arrange and call multiple atomic APIs based on specific business requirements. This enables the creation of business-oriented, granular APIs that enhance operational efficiency. Reference materials are available to guide SDK support and orchestration usage.

[iComposer Details](https://docs.insuremo.com/common/doc_00000009)


#### API Integration in iHub

Developers can leverage the platform's API integration services - **iHub**, which simplify the process of connecting disparate systems and services. Detailed reference materials are provided for effective integration.

[iHub Details](https://docs.insuremo.com/common/doc_00000376)

#### Generic Guidelines for Calling APIs

There are some generic guidelines for you when calling insureMO APIs.

![generic_norms_calling_api](./image/app_dev_overview/generic_norms_calling_api.png)

* All calls must go through the API gateway.
  * With the exception: services may call service in the same namespace through k8s naming.
* The API gateway by default does authentication to make sure a valid token is in place.
  * A short period token will be received when the user login to the app.
  * A long period token can be created in the API management tool using a functional ID, and is used only for service-to-service integration.
* The API gateway is integrated with Business URP OOTB.

### Using the Platform's JAVA SDK

The platform provides a JAVA SDK to facilitate easier integration with the APIs. This SDK is designed to minimize potential conflicts with existing technology foundations, offering streamlined access to core functionalities. Developers can leverage the SDK to reduce boilerplate code and enhance productivity.

[Welcome to insureMO SDK for Java](https://docs.insuremo.com/common/doc_00000089)

#### Maven Repository Access

The SDK can be pulled from a public Maven repository, ensuring easy access to necessary dependencies.

* Public maven repositories settings

    ```
    <repositories>
            <repository>
                <releases>
                    <enabled>true</enabled>
                </releases>
                <snapshots>
                    <enabled>false</enabled>
                </snapshots>
                <id>insuremo</id>
                <name>insureMO Maven Repository</name>
                <url>https://public.insuremo.com/artifactory/maven/</url>
            </repository>
        </repositories>

        <pluginRepositories>
            <pluginRepository>
                <releases>
                    <enabled>true</enabled>
                </releases>
                <snapshots>
                    <enabled>false</enabled>
                </snapshots>
                <id>insuremo</id>
                <name>insureMO Maven Repository</name>
                <url>https://public.insuremo.com/artifactory/maven/</url>
            </pluginRepository>
        </pluginRepositories>
    ```

#### Minimizes Dependencies

* The design minimizes dependencies to avoid conflicts with existing foundations.
* For developers using the Spring Boot framework (both v2 and v3 supported), the SDK includes a spring autoconfiguration artifact to streamline initialization, enhancing developer productivity.

### Framework-Based Development

#### Frontend Development with RainbowUI

* **Technology Stack:** The front-end applications should be developed using ReactJS and HTML5 (H5).
* **Support:** While primarily designed for PC access, limited support for mobile interfaces is available. Developers are encouraged to optimize the user experience for both platforms.
* **Dependency Management:** Developers can access npm components via the public npm repository, ensuring easy management of front-end dependencies.
* **Documentation:** Comprehensive documentation is provided to assist developers in leveraging the framework effectively.
  * [RainbowUI Introduction]https://docs.insuremo.com/common/doc_00000084)

  * [RainbowUI Document](https://rainbow-doc.insuremo.com/ui/sugar-doc/#)

* **Public registry setting**

    ```
    npm config set registry https://registry.npmjs.org/
    npm config set @insuremo:registry=https://public.insuremo.com/artifactory/api/npm/npm/
    npm config set always-auth false
    ```

    You may use a mirror site to speedup package installation, for example, npmmirror.com.

    ```
    npm config set registry https://registry.npmmirror.com/
    npm config set @insuremo:registry=https://public.insuremo.com/artifactory/api/npm/npm/
    npm config set always-auth false
    ```

#### Backend Development with App Framework

* **Technology Stack:** Applications should utilize JAVA, SpringBoot, and Liquibase for backend services.
* **Framework Options:**
  * **Managed App Framework:** This option includes regular updates from the platform, with controlled access via Maven. The source code is not available for modifications, ensuring stability and security.
  * **Open Source App Framework:** This version allows for irregular updates and provides access to the source code, enabling developers to fork and maintain their versions as needed.

* **Key Sections of Backend Service Development include**:

  * [App Development Overview](https://docs.insuremo.com/common/doc_00000003)
  * [Development Locally](https://docs.insuremo.com/common/doc_00000007)
  * **Database Script Management:** Best practices for managing database scripts with Liquibase. [Use Relational Database](https://docs.insuremo.com/common/doc_00000061)
  * **Global Transaction Handling:** Guidelines for implementing and managing global transactions to ensure data integrity. [Global Transaction Handling](https://docs.insuremo.com/common/doc_00000023)
  * **Batch Processing:** Strategies for developing and executing batch processing tasks efficiently. [Batch Scheduler](https://docs.insuremo.com/common/doc_00000010)
  * **Integration:** [Integration State](https://docs.insuremo.com/common/doc_00000034)
  * **API Registration:** Steps for registering and exposing APIs within the framework. [API Management And Gateway](https://docs.insuremo.com/common/doc_00000356)
  * **Security Features:** Best practices for implementing security measures within applications.[Sensitive Data Handling](https://docs.insuremo.com/common/doc_00000058)
  * **Performance Considerations:** Recommendations for optimizing performance and adjusting parameters for scalability. [Performance Checking](https://docs.insuremo.com/common/doc_00000046)

#### Application Deployment and Operations

Developers should follow best practices for deploying and managing applications, including performance monitoring, incident response strategies, and routine maintenance protocols to ensure operational efficiency and reliability.

##### Managed Mode

In the managed mode, applications are deployed in a dedicated workspace provided by the platform. This setup ensures a consistent environment, allowing developers to focus on building features without worrying about infrastructure management.

![Managed Mode](./image/app_dev_overview/managed_mode.png)

* **Deployment Process:** Developers upload their application code to the platform’s designated workspace, where it is automatically configured for optimal performance. The platform handles aspects such as scaling, load balancing, and resource allocation.
  
* **Access Points:** The platform provides a unified access point for end users, integrating various platform functionalities such as authentication, monitoring, and logging. This centralization simplifies user interaction with the application. [Log Dashboard](https://docs.insuremo.com/common/doc_00000379) and [Trace Monitoring](https://docs.insuremo.com/common/doc_00000372)

* **Compliance:** Applications must adhere to platform standards regarding logging, traceability, health checks, and metrics reporting. This ensures that applications are maintainable and operable within the broader ecosystem. [insureMO Log Standard](https://docs.insuremo.com/common/doc_00000362)

* **Support Services:** Developers can utilize the platform's CI/CD pipelines for automated deployments and updates. Monitoring tools are also provided to track application performance, detect anomalies, and facilitate troubleshooting. [DevOps](https://docs.insuremo.com/common/doc_00000298)

##### Independent Deployment

In independent deployment, applications are designed to operate with their own dedicated access points and infrastructure, giving developers more control over their environment.

![Independent Deploy](./image/app_dev_overview/independent_deploy.png)

* **Deployment Process:** Developers manage the deployment of their applications on their infrastructure. This could involve setting up servers, configuring load balancers, and ensuring network security. They can use containers or virtual machines according to their preferences.

* **Access Points:** Each application has its own access point, allowing for greater customization of user interfaces and interactions. This autonomy enables developers to implement tailored security measures and access controls.

* **API Interaction:** Applications in independent deployment can remotely call platform APIs for specific functionalities, allowing them to integrate with platform services without being tied to the managed environment.

* **Flexibility and Responsibility:** While this model offers flexibility in terms of technology choices and configurations, it also places the onus of maintenance, scaling, and resource management squarely on the developers. They are responsible for monitoring application performance and implementing best practices for reliability and security.

##### Key Differences

* **Infrastructure Management:** Managed mode abstracts infrastructure management, while independent deployment requires developers to handle all aspects of their environment.
* **Customization:** Independent deployment allows for deeper customization at the cost of added complexity, whereas managed mode provides streamlined operations with predefined standards.
* **Support and Compliance:** Managed mode benefits from built-in support and compliance with platform standards, whereas independent deployment offers flexibility but demands diligent adherence to best practices by the developers.

In summary, the choice between managed mode and independent deployment should align with the team's expertise, the application's requirements, and the desired level of control over the deployment environment.

<div class="docs-note"><span class="docs-admonitions-text">note</span>

This document may include links to external websites and third-party features for demonstration purposes only. These links and features do not constitute an endorsement or recommendation by us. We do not control and are not responsible for the content, services, or privacy practices of these third parties. Users are advised to review the respective terms and privacy policies independently.

</div>