Persistence

Overview

Data is persisted in Alpyne as Items that are described by Templates. A Template of “Car” might describe the properties of the Car, such as the Make, Model, and Color. Items are instances of the Template, such as a specific Toyota Corolla.

graph LR
    Car["Car<br/>make: String<br/>model: String"]
    Corolla["Toyota Corolla<br/>(instance)"]
    Corolla -->|instance of| Car

prn::<appname>:template/<templatename>

In the Runtime, Items can be created, retrieved, queried, and updated using the Template.

Properties

Validations

State Machine

Permissions

Templates and Items are analogous to Tables and Rows in relational database terminology. In an Object-Oriented system the analogs would be Classes and Objects¹.

The platform assumes a limited amount when it comes to the quality of underlying data.

Why?

1. It is the nature of the data coming in — it may be historical, incomplete, or entered via inconsistent processes. It may span or move between systems.
2. Much of the data entered is sourced from or sent to external systems; systems where we do not control the nature or structure of the data.
3. In many cases “validity” of data is more contextual than structural. For example the data that is valid for a candidate, contractor, or intern may be quite different for the circumstance or customer.
4. Different customers may have different data validation needs; but we still want to leverage the same underlying definitions.
5. The permission model means we should always be working on a model where we adapt to the data available.

This leads to two key assumptions:

1. We are very tolerant of data that is missing. In fact, we rarely rely on data being present².
2. We rely on data validation that is contextual — i.e. a set of rules that can tell us if the data can be used in a given manner.

Structural Validation

Collections are still strongly typed. Even if that data may be missing, it is not possible to have a number in a string field.

We do not erase data. It would be rare, but a collection could redefine a field from string to number, referencing an entry that still has a string would result in undefined (The type would not be coerced). Switching the collection definition back would restore the original values.

Contextual Validation

Contextual validation provides rules for Collection items that validate the suitability of the item for a supplied context.

For example, we do not have “is this a valid employee?”. Instead we have “is this employee suitable for sending a slack to?”, and potentially a number of other fine-grained assertions.

Permissions

One of our principles is Explicit Permissions. A User Principal cannot see any collections unless they have been given permission to that principal. This also extends to each individual field and includes both read and write scenarios³.

To have permission to a collection, a grant must be provided. At design time, there are no known users. So grants operate on:

• Roles, to which users will be assigned.
• Relative principals, where the permission is relative from the underlying item (e.g. it comes from an ownerId field).
• Associate principals, where the permission is inferred from an association. This can be used for “manager-of”-style scenarios.

Combining Permissions

It is likely that a user has multiple roles that apply to a collection. For example, you may have both the user and admin role, both of which have grants.

In this case the permission available is the union of all grants. That is, if user is permitted access to field a and admin to b and c, a principal assigned to both roles would see a, b, and c.

Fine-Grained Permissions

Fine-Grained permissions provide full resolution of the permission rules. All items being communicated with a principal have the fine-grained permissions applied.

Coarse-Grained Permissions

One system challenge is providing performant access to data whilst still allowing for fine-grained access. These coarse rules provide a way of getting broad “query” access to the data.

1. All collection items need to “flatten” to a set of role and user identifiers. This represents any principal that can access the item, but without specifying individual fields.
2. All User Principals need to “flatten” to a set of roles and user identifiers.

To do a “coarse” pass, the collection can be queried with a “match any” which represents the union between these two sets.

Details

Details refer to main-detail relationships⁴. These are composition-style relationships in that the “detail” item has the same lifecycle as the parent.

Details can operate as regular Collections and have the same hooks and capabilities as Associations. They can have one-to-one or one-to-many cardinality, but not a many-to-many cardinality.

The simplest metaphor to describe this composition is: When the parent is conceptually⁵ deleted, the detail item is also. This is extremely contextual. However, some natural examples could be:

• An Invoice with detail Line Item.
• Individual approval items on an Expense Report.
• Events (such as an open, click, or read) on a Message Delivery.

Conversely, items that have independent lifecycles should be regular Associations rather than Details. Natural examples of this may be:

• An employee can be assigned to an Office Location. Removing that employee would not remove the Location.
• A car that is assigned to a Parking Space.

It is possible to associate a Detail to another Collection or Detail. For example, that Invoice “Line Item” could refer to a Product. These are considered regular associations.

Footnotes

1. In a Relational Database terminology, Templates and Items are analogous to Tables and Rows respectively. In an Object-Oriented system the analogs would be Classes and Objects. ↩

2. There are obvious exceptions such as identifiers or system meta-data. ↩

3. This is the general case. Another mechanism is via mutations and queries, which optionally may “role switch” to something like a superuser. ↩

4. These are called master-detail relationships in Salesforce. ↩

5. In practice this might not be a regular delete: it could include soft-removal, archive, or another mechanism; it’s just a means of explaining the concept. ↩