1. MDriven Turnkey Architecture

MDriven Turnkey architecture helps you understand where your application runs, how data moves between browser, application, MDrivenServer, and database, and how to run the web application locally during development.

1. 1. Architecture at a glance

A Turnkey application has four physical tiers. Each tier has a distinct responsibility.

| Tier | Runs where | Responsibility | Example | |---|---|---|---| | 1. Turnkey JavaScript application | In the user's browser or app | Displays and edits the information exposed by a ViewModel. | A user changes a customer's phone number in a form. | | 2. Turnkey web application | ASP.NET MVC web application | Transforms business objects to ViewModels, executes application logic, maintains per-user state, and controls access. | The application determines whether the current user may edit that customer. | | 3. MDrivenServer | MDriven server environment | Performs object-relational mapping, coordinates client synchronization, and runs applicable server-side work. | The changed customer object is stored and other clients can receive the update. | | 4. Database | Database server | Provides persistent storage and SQL-based search. | The customer record is stored in a database table. |

> **Terminology:** A **ViewModel** is the information needed for a particular user perspective or task. It can provide UI hints, such as labels and editing widgets, but it is also used for non-UI information processing. A ViewModel can navigate the domain model as needed.

For example, an *Edit customer* ViewModel may contain a customer's name, phone number, and a list of orders. It exposes the information needed for that task rather than granting the browser unrestricted access to the whole domain model.

1. 1. Responsibilities by tier

1. 1. 1. Tier 1: Turnkey JavaScript application

Tier 1 is the client-side application that the user interacts with. It can display and update ViewModel properties, but it only works with the information made available through the designed ViewModels.

When the user performs an action or changes a value:

1. Tier 1 packages the change. 2. Tier 1 sends the change to Tier 2 for processing. 3. Tier 1 later asks Tier 2 for changes since its previous update request. 4. Tier 1 merges the returned diff-gram into its local ViewModel representation. 5. The AngularJS display framework receives the resulting subscription changes and refreshes the UI according to AngularJS rules.

A **diff-gram** is the set of ViewModel changes returned since the client last requested updates. For example, if another user changes a customer's status from `Prospect` to `Active`, the client can receive that changed value rather than reload its complete ViewModel.

1. 1. 1. Tier 2: Turnkey web application

Tier 2 is the traditional MDriven application tier. It is responsible for:

- Transforming business objects into ViewModels. - Subscribing to changes and making ViewModel changes available as diff-grams. - Executing logic on business objects. - Enforcing information security through per-user access control. - Maintaining a per-user state area for the ViewModels that user currently accesses. - Maintaining changes for each ViewModel. - Loading data from MDrivenServer when needed, including lazy loading and ViewModel-driven look-ahead loading. - Owning the transaction context for save operations, including commit and rollback. - Maintaining undo and redo queues for unsaved changes.

For example, a user may change an order's delivery address and add an order line before saving. Tier 2 can keep those changes in the user's transaction context, show their effects in the ViewModel, and either commit all changes or roll them back. The database is not updated until the save operation commits.

1. 1. 1. Tier 3: MDrivenServer

MDrivenServer performs object-relational mapping: it retrieves business objects from the database and stores changed business objects back to it. It also manages client synchronization so that multiple clients can efficiently receive updates made by other clients without a complete refresh of the business-object cache.

Server-side jobs can also run at this tier, including periodic work such as sending email or producing exports and imports.

For example, when User A saves an order, MDrivenServer stores the changed business objects and can make the relevant change available to User B's active client session.

1. 1. 1. Tier 4: Database

The database provides persistence services: durable storage and efficient SQL search.

For example, Tier 4 stores the data that represents customers, orders, and order lines. The higher tiers work with business objects and ViewModels; Tier 4 is responsible for storing and querying the underlying data.

1. 1. How a change travels through the architecture

Use this sequence to reason about where a behavior belongs.

1. **A user changes a ViewModel value in Tier 1.**

  Example: the user changes `Customer.PhoneNumber` in an edit form.

2. **Tier 1 posts the change to Tier 2.**

  The browser does not directly update the database.

3. **Tier 2 checks access and executes business-object logic.**

  Example: Tier 2 determines whether the user is allowed to edit the customer and applies the change in the user's transaction context.

4. **Tier 2 commits or rolls back the save operation.**

  A commit persists the valid set of changes; a rollback discards the unsaved changes in that transaction.

5. **Tier 2 and Tier 3 retrieve or store business objects as required.** 6. **Tier 3 uses Tier 4 for persistence.** 7. **Tier 1 receives later updates as diff-grams and updates its local ViewModel.**

This separation means that a UI can be changed or replaced without giving it direct database authority. The ViewModel remains the defined information boundary for the client.

1. 1. Communication paths

The communication direction and technologies described for the Turnkey architecture are:

| From | To | Communication | |---|---|---| | Tier 1: Turnkey JavaScript application | Tier 2: Turnkey web application | The client initiates communication through a WebApi HTTPS REST interface using jQuery Ajax calls. Data changes are posted as JSON over HTTPS. | | Tier 2: Turnkey web application | Tier 3: MDrivenServer | The web application uses the MDriven Datablock definition and WCF over HTTPS to send and retrieve data. | | Tier 3: MDrivenServer | Tier 4: Database | MDrivenServer uses the appropriate ADO driver for the selected database. |

The client initiates communication with the web application. Do not design browser code to bypass Tier 2 and access MDrivenServer or the database directly.

1. 1. Develop with a local Turnkey web application and cloud-hosted server

Use this arrangement when you have Visual Studio and want a faster edit-and-test loop for JavaScript or TypeScript while retaining the provisioned cloud MDrivenServer and database.

In this setup:

- **Local:** Tier 1 and Tier 2. - **Cloud:** Tier 3 and Tier 4.

1. 1. 1. Configure the MDrivenServer override

1. Open the `TurnkeyWebAppGeneric/App_Data` directory in your local Turnkey web application. 2. Create `MDrivenServerOverride.xml`. 3. Add the MDrivenServer endpoint for your Turnkey application:

```xml <?xml version="1.0" encoding="utf-8"?> <root>

 <MDrivenServerOverride>https://[YOUR_TURNKEY_APP].azurewebsites.net/__MDrivenServer</MDrivenServerOverride>

</root> ```

Replace `[YOUR_TURNKEY_APP]` with the name of your Turnkey application.

This override lets the locally running Turnkey web application use the persistence mapper exposed by the server environment.

1. 1. 1. Configure local Turnkey settings

1. In the same `TurnkeyWebAppGeneric/App_Data` directory, create `TurnkeySettings.xml`. 2. Add the application and authentication settings supplied for your Turnkey application:

```xml <?xml version="1.0" encoding="utf-8"?> <root>

 <ApplicationName>The Name Of the Turnkey app (shows in browser title)</ApplicationName>
 <MDrivenServerUser>a</MDrivenServerUser>
 <MDrivenServerPWD>pwd as found in LicenseAndTicket</MDrivenServerPWD>
 <MicrosoftAuthentication_ClientId>As found in license and ticket</MicrosoftAuthentication_ClientId>
 <MicrosoftAuthentication_ClientSecret>As found in license and ticket</MicrosoftAuthentication_ClientSecret>
 <FacebookAuthentication_ClientId>As found in license and ticket</FacebookAuthentication_ClientId>
 <FacebookAuthentication_ClientSecret>As found in license and ticket</FacebookAuthentication_ClientSecret>
 <GoogleAuthentication_ClientId>As found in license and ticket</GoogleAuthentication_ClientId>
 <GoogleAuthentication_ClientSecret>As found in license and ticket</GoogleAuthentication_ClientSecret>
 <LicenseToken>yourkey</LicenseToken>

</root> ```

3. Obtain the required values from the MDriven Portal, as provided for your application. 4. Run the local Turnkey web application from Visual Studio and verify that it reaches the configured MDrivenServer endpoint.

1. 1. 1. Protect local configuration

`TurnkeySettings.xml` contains passwords, client secrets, and a license token. Treat it as a secret:

- Do not commit real credentials to source control. - Do not share the file through unsecured channels. - Use only credentials issued for the relevant Turnkey application.

1. 1. Run MDrivenServer locally

You can also run Tier 3 locally. This arrangement is relevant when your organization needs an on-premises deployment and does not permit data to leave its environment.

In this setup, install an MDrivenServer instance and point `App_Data/MDrivenServerOverride.xml` to that local server instead of the cloud endpoint.

The described default database for MDrivenServer is SQL Server CE. You can change the database connection to an SQL Server you own, and a MySQL connection string is also supported.

Before choosing a fully local or production deployment, verify the supported MDrivenServer version, database configuration, connection string, and deployment requirements for your environment.

1. 1. Design implications and best practices

1. 1. 1. Keep client needs in ViewModels

Design each ViewModel around a task or perspective.

For example, use an *Approve invoice* ViewModel that exposes invoice details, approval state, and the available approval action. Do not expose unrelated accounting data only because it exists in the domain model.

This limits the information Tier 1 receives and makes the intended UI behavior clear.

1. 1. 1. Put business changes behind actions and server processing

Actions can change domain data or navigate the current view.

For example:

- A **domain action** can create an order line, change an attribute, or delete an object. - A **view navigation action** can move the user from an order list to an order-detail perspective.

Let Tier 2 process these actions so it can apply business logic, access control, transaction handling, undo, and redo consistently.

1. 1. 1. Design for multiple active users

Each active user has a domain-layer state area, and a user may have multiple active ViewModels. Other users can change the shared data at the same time.

For example, one user can review an order while another user updates it. Design the ViewModel and actions with the expectation that client updates may arrive through synchronization rather than only from the current user's own edits.

1. 1. 1. Use the deployment boundary deliberately

Use the semi-local setup when you need to work on the web application locally while using the existing server and database. Use a local MDrivenServer deployment when on-premises data requirements require it. In both cases, keep the tier responsibilities unchanged: browser code works through the Turnkey web application, and persistence remains behind MDrivenServer.

1. 1. Related documentation

- Documentation:MDriven Turnkey Series — Turnkey development tutorials and examples. - Build Enterprise Information Systems — Model-driven development workflow for enterprise information systems. - Documentation:MDriven Product Line — MDriven product overview. - Model-Driven Architecture — Model-driven development guidance.