# What is it?

frontend-workstation is the master layout and scaffolding structure for hosting the Workstation Single Page Application (SPA).

It is designed to be as lean and lightweight as possible. The actual content pages are pulled on demand when the user navigates through the site.

The only thing frontend-workstation needs to know is which "module" it needs to fetch and render for any given url/path.

# How does it work?

Building big SPAs is hard. There are many considerations to take in.

The major ones are:

-   State management across pages.
-   Routing and navigational structure.
-   Memory consumption and garbage collection.
-   Error handling
-   Localization
-   Handle shared libraries
-   Authorization
-   Styling

frontend-workstation handles all of the above. Leaving each dynamically loaded module to only care about user features and not application level logic.

## Modules

Each module has it's own github repo and generally starts with `frontend-[name]`. A module has to follow strict rules in order to comply with the SPA standards.
And to ensure this, they are all using the `frontend-cli` tooling.

The framework rules:

-   Modules must default export their root react component.
-   Modules may only style themselves.
-   Modules may have their own POEditor project.
-   Modules should use libraries that are already part of the SPA.
-   Modules must use the `@orchard/frontend-cli` tooling.
-   Modules must install the `@orchard/frontend-workstation` dependency.

## Frontend CLI

In the heart of development and building the SPA is the `frontend-cli` tooling.
It handles configuration, webpack builds and localization in a uniform way.

## The Dynamic Module Loader (DML)

When the user navigates to a given url e.g. `/catalog`, the first thing that happens is a match against an internal routing registry. If there exists a route to `/catalog` where there is also a defined module for it, the DML is invoked.

The DML will try to fetch more information about the module to load. It does so by pulling a manifest from the CDN. The manifest lists all assets needed( javascript, stylesheets) required by the module.
[Example manifest](https://cdn.theorchard.io/frontend-catalog/manifest.json)

After each asset is downloaded, it initializes the main module bundle. The module is expected to export a root react component. This component is then finally rendered inside a container.