Marfeel Docs

# JSON architecture

Marfeel Platform extensibility, whenever possible, follows a configuration over code philosophy instead of a configuration in code approach.

Marfeel SDK offers a set of json files that allow developers to specify certain extensions to certain extension points and configure them.

The main reasons why Marfeel uses JSON files with a configuration over code approach are:

  • Multi channel strategy: Build applications once and run them as PWA, AMP, Native applications, Facebook Instant Articles or Apple News without multiple tools and code bases. Marfeel uses json configuration files as the unique source of truth and transpiles them to the appropriate platform-specific equivalent.

  • Predictable: Operational configurations changes are often requested over time as the business has changing requirements. Declarative configuration files describe a desired state and are adaptable within mere seconds without having to crawl through complex code bases looking for configuration in code. Marfeel code base is open for extension and closed for change following the OCP principle (opens new window).

  • Reliable & Safe: All Marfeel JSON files have a set of deterministic options and structure defined via JSON schemas (opens new window). At compile time each json file is validated against its schema ensuring the validity of the submitted data to prevent failures in production.

  • Zero code deployments: By definition, the configuration over code approach allows Marfeel to change a site's behaviour without effectively deploying new code to production, making the deployment process safer.

Marfeel doesn't store any configuration parameters in dynamic databases. All configurations and extensions used by a site are statically contained in its code git repository making portability, trackability and toolability first class citizens:

  • Portable environment: All customizations and parametrizations of a site are statically stored in the code repository allowing any developer to replicate the setup on a local environment.

  • Previewable: Any configuration can be previewed in a local dev environment or in deployed feature branches without affecting production code.

  • Trackable: Every change in JSON files is subject to a git-flow Pull Request process. The git repository provides full trackability on the history of changes via git log showing who did what and when.

# Toolability and Continuous deployment

The structured nature of JSON files allows Marfeel to create tools to operate them and make all configuration options available to non-tech users.

TIP

These tools are under the umbrella of MarfeelInsight and referred as MarfeelInsight UI editors or Leroy editors throughout the documentation.

Marfeel offers lots of different specialized Leroy editors through MarfeelInsight that allow users to manage their advertisement setup, their metrics providers, commenting systems, feature toggles, etc.

It's very important to emphasize that Leroy editors follow the same workflow a developer would follow to change a JSON file. Leroy editors contribute JSON changes via git commits on behalf of the user that is operating the editor in MarfeelInsight.

Changes applied to JSON files via a Leroy editor are eligible for a fast build process. When a changed is done to a JSON file via Leroy the build process is very deterministic and only the proper json-schema validations are performed on the changed file, skipping any other unnecessary step of the build pipeline.

# Leroy git-flow

sequenceDiagram

participant User
participant Leroy
participant Git as Git Repository
participant CD as CD System
participant Production

User->>Leroy:Changes via UI
Leroy->>Git:commit & push
Git-->>CD:Trigger build
CD->>Production:Deploy

# Developer git-flow

sequenceDiagram

participant Developer
participant Git as Git Repository
participant CD as CD System
participant Production

Developer->>Git:commit & push
Git-->>CD:Trigger build
CD->>Production:Deploy

# Convention over Configuration

Marfeel follows a Convention over configuration, aka coding by convention (opens new window) whereby a developer only needs to specify unconventional aspects of the application, thus decreasing the number of decisions that a developer using the framework is required to make.

Default values are provided by Marfeel via inheritance and some advanced json operators.

# Inheritance

Marfeel provides an inheritance mechanism that allows developers to create inheritance chains by extending a json file with a parent file.

parent.json:

{
  "field1":"value will be overriden",
  "field2":"value will be kept"
}

Child file:


 




{
  "extends":"parent.json",
  "field1":"new value",
  "field3":"child field"
}

Merge result:

{
  "field1":"new value",
  "field2":"value will be kept",
  "field3":"child field"
}

This inheritance mechanism is extensively used through Marfeel to infer intrinsic default platform values. i.e. A Tenant's features.json will intrinsically inherit from a parent Marfeel default features.json

Media Groups that have more than one tenant can also create a base common file that all tenants inherit from avoiding code duplication and redundancy trying to be more DRY (opens new window). For example, to extend the definition.json file from one site to another, the following line can be added with the right path:

"extends": "www.sampleurl.com/index/src/definition.json"

TIP

More JSON merging strategies are available at Marfeel. You can read about them in the JSON Extensions article.

← Providers →