Cireson Platform Overview

Synopsis

The Cireson Platform started as an internal initiative to build a technology stack that would facilitate the production, and delivery of Cireson applications. Cireson Platform Applications are delivered using a Nuget based packaging format that is referred to as a Cireson Platform Extension or CPEX

Architectural Goals

The following list summarizes the main goals that the Cireson Platform Architecture strives to reach in order to aid in the delivery of Cireson Products.

  1. Provide a common runtime that can be installed in an on-premise, or in a cloud based environment.
  2. Ensures that -as much as possible- applications are compatible across Cireson Product Portfolios.
  3. Ensure a common means of interacting with, and customizing applications from a development perspective.
  4. Ensure applications are discoverable in the ecosystem.
  5. Ensure that applications can reuse functionality that is exposed by other CPEX applications, or CPEX Libraries.
  6. Adhere to industry standards and practices, and ensure tools and SDKs promote the use of best practices.
  7. Provide robust security mechanisms that are easy to develop for, and manage
  8. Provide robust and secure data access mechanisms both internally, and remotely (OData, REST)

Implementations

The following layer diagram shows the various standard components of the Cireson Platform. These components are available to CPEX Developers via the Cireson Platform SDK. Additionally because the platform can expose the CPEX data models as OData services, non-CPEX client applications can interact with the services using industry standard protocols, and tools. (Excel, Power BI, etc) Cireson Platform Layer Diagram

With great power...

The OData endpoints created by the Cireson Platform represent a very powerful set of features that are difficult to realize in a typical MVC application. This power does come with some strings attached however. #nerdalert :-) Like Asimov's 3 laws of robotics, the Cireson Platform is governed by a set of core rules that cannot, or should not be violated.
As you embark on your journey to build your application, it is helpful to remember these rules.

  1. Do not deliver data to a client that is not authorized to see the data.
  2. Do not deliver too much data on any given request.
  3. Do not expect the client to know something the server doesn't.

Do not deliver data to a client that is not authorized to see the data.

When you create a Cireson Data Model, you are instructing the Cireson Platform to create a Storage Model that can be persisted to the SQL Server, as well as an Entity Model that can be delivered to the OData api endpoint as a queryable EntitySet.

If you do not apply any authorization attributes (Authorize, or AuthorizeOData) to the model class, the platform will apply the following security constraints by default:

Users = Readonly Administrators = Full

Additionally, when creating a Function (Functions are accessed using the http GET verb) Users are allowed Execute Access Finally, the default permissions for an Action (Actions are accessed using the http POST verb) are Administrators have Execute Access

For applications that require higher order data governance, the Cireson Platform also allows for Entity-Level, and Property-Level style security, meaning your application can restrict Access to whole entities, or specific properties within an entity based on Roles.

Data auditing for Reads, Writes, Delete on an Entity, and Property level is also supported.

Do not deliver too much data on any given request.

By default, the Cireson Platform will allow 500 top level entities to be delivered to a client on a given query. A client can use the $skip and $top query functions to limit the data to a lower count, but the Platform will not allow that number to be exceeded.

A request can be made using the $expand function to include Navigation Properties and Navigation Collections that could increase the size of the resulting data. This should typically be avoided in favor of a lazy request to get additional data as needed.

Do not expect the client to know something the server doesn't.

When interacting with an OData Api, it is important that the features that are exposed by the api are expressed in the $metadata file. This allows a client to be able to understand and make appropriate requests to the api.

So instead of having a field in your model that is called Address, that accepts a string value for a freeflow formatted address. It may be a better design decision to create a separate Address model that has a City, State/Provence, Postal Code, Country, etc. The point is, you shouldn't expect the consumer of the api to understand how to parse an Address. This may not always be the case of course, but keep in mind that you want your Platform application to be as expressive as needed for your application domain.