Frontastic

Welcome to the Frontastic platform docs. You can find your way around the various topics through the navigation on the left or using the search on the top right. On this page we will give you a drill-down introduction into the Frontastic architecture and reference more detail explanations on the go.

So, if you are new to Frontastic, reading this document from start to finish and maybe opening some of the links for further reading may be a good strategy.

High Level View

Architecture Overview

Backstage is the SAAS component of Frontastic. This is the back-end where marketing managers create and administrate their front-end experiences without the need for techincal knowledge.

For developers Backstage offers facilities to upload Tastic specifications, custom app specifications, monitor and profile their code in production and more.

To get familiar with the terminology used by Backstage please refer to our explanation of Concepts.

The actual development takes place in Catwalk. Catwalk is an independent application that ships customer experience to end-users: It serves a single-page web-application.

Catwalk and Backstage are maintained as entirely decoupled applications which both potentially access a common set of APIs. These TODO: Data APIs are the main point where data is stored and business logic is handled. Frontastic itself does not store any data apart of its own configuration.

Catwalk is available in multiple instances where Production is the live site, Staging is a cloud hosted testing environment for technical and business people and Development is your local development environment. We aim to provide you a development environment which is very close to what happens in Production and Staging by using a Virtual Machine.

If you want to dig deeper into this, consider reading about the TODO: Frontastic Development Process and our Virtual Machine.

Tastics

Tastics are the central element of Frontastic. A Tastic represents a generic front-end building block which is implemented once by a developer and can then be placed anywhere on the page by non-technical people in Backstage. Catwalk is then responsible to plug together the resulting view using

  • the page definition from Backstage
  • the corresponding front-end code
  • and required data

Tastics in Backstage and Catwalk

A Tastic always consists of 2 parts: 1. Its JavaScript entry point which is a TODO: ReactJS (JSX) component that receives some special props. 2. A JSON file which defines which data the Tastic requires and how this should be configurable in Backstage. We call this JSON file the TODO: Tastic Schema.

In the image above, you can see that the Tastic Schema needs to reside in Backstage which is why you need to upload it to the TODO: Developer App in order to make it available for use by non-technical people.

Now the Tastic can be placed on any Page. For each such placed Tastics the configuration can be different but will always follow the developer's specification from the Tastic Schema. Once a Page is stored and made public in Backstage, it is automatically transferred to all relevant Catwalks. This includes your local development environment where you always have the most recent version of every Page available for testing.

If a web browser is now pointed to a URL on Catwalk where the configured Page should be served, Frontastic takes care to create an instance of the JSX component of the Tastic and automatically fills in the data that is defined by the Tastic Schema.

Therefore in the larges number of cases, you will not have to worry about how to get hold on the data you need in your front-end components but Frontastic will ship it to you (for free).

Request Flow / Single Page App

The back-end of Catwalk is responsible to handle the intial serving of the Single Page App code (SPA) as well as all subsequent data requests when the visitor changes the view.

Frontastic Request Flow

The process is similar for both cases:

  1. The browser requests a certain URL
  2. Frontastic will determine which Page should be displayed
  3. It then loads the data for all Tastics on that page as defined by the Tastic developer and configured by the Backstage user

This includes pure configuration values from Backstage but also fetching information from the attached API providers. Such information is defined and fetched in TODO: Streams.

  1. The collected Page structure information, configuration values and API data is transferred to the SPA in the browser
  2. Frontastic takes care to instanciate all the JSX components for every Tastic on the Page to display and provides it with the requested information
  3. Actions by the visitor will result in a new request with either complete or partial data update

On the very first request of a visitor there are a few more steps happening:

Instead of just returning the structure and data to the browser as JSON, a very slim HTML template is returned in addition. This will make the browser load the actual SPA code and take over the rendering in the browser. If required, TODO: Servers Side Rendering (SSR) will take place to pre-fill the HTML body for SEO and browser performance reasons.

Extension Points

The Frontastic platform does not only provide you with the described request flow for minimal effort development of Tastics but allows to be adjusted by extension points in various ways.

Frontastic Extension Points

Front-end

In the front-end you are free to work in your code as you like. Behind the JSX entry point of a Tastic you can break down the front-end experience into any number of React components as well as regular JavaScript files. Using SCSS you can apply adjust the standard styles or replace them by an entirely custom styling.

Frontastic uses TODO: Yarn to manage dependencies and you are free to require any dependencies from the NPM/Yarn universe as you need them. Of course, you can also load external JavaScript if this might be required.

On top of that, Frontastic provides you with a means of TODO: Component Injection (★, similar to dependency injection) which allows you to replace our standard ReactJS components selectively and fine-grained throughout the entire system .

We also allow you to hook TODO: custom reducers into our Redux store in order to react to events and data updates in Frontastic directly.

Back-end

In an ideal front-end world, you would not need to touch the back-end at all. While this can be reality for many Frontastic projects, there are many cases where you will need to adjust or extend the back-end functionality. Thefore we made the Frontastic back-end highly extensible in multiple ways:

The most used extension point is a API Lifecyle Decorator (★): With this you can hook into any of the API calls that Frontastic issues and manipulate the input or adjust/enhance the output. This allows you, for example, to change searches by adding more parameters, enhance product information through data from additional API service or to hook into cart value calculation as an item is added to the cart.

The Frontastic back-end flow starts in a TODO: Controller for the specifically called TODO: Route. This one prepares incoming data and orchestrates a TODO:Service Layer to perform desired actions or fetch requested information. Part of this are, for example, TODO: Field Handlers, TODO Stream Handlers and many more concepts. For highest flexibility you can implement own code on any of these levels.

Of course you can also place TODO: additional PHP code into the Frontastic back-end as long as it serves directly a front-end purpose and does not consume a high amount of additional resources. For the latter case we ask you to implement a custom API provider on a different host and implement only the communication with this one in Frontastic back-end. Of course you are also free to attach any other TODO: 3rd party service to Frontastic by that means.

Technology Stack

Our technology stack consists of community proven applications, tools, frameworks and components as shown in the following graphic:

Frontastic Technology Stack

In the front-end we mainly use ReactJS + React-Router. We use Redux to dispatch the required data globally in the app but try to avoid that you need to mess with it. For meta data and SEO requirements we have React-Helmet included.

For the development and build toolstack we use Yarn, Webpack, Babel and Storybook plus a variety of additional smaller tools on top of these.

In order to provide a common CLI experience accross all tools, to define a build pipeline, and use this also in TODO: Continuous Integration (CI), we are using Ant. Ansible is our tool of choice for provisioning any server environment and automating about everything around Frontastic.

On the server side we have Nginx (as web server) and Supervisord (for long running processes) in place. Both work mostly with PHP (cutting edge version) scripts.

Symfony 4.x and Doctrine form the basis for our back-end. Composer and PHPUnit are the most significant development tools here.