feat: add architecture doc (strimzi#10)

* feat: add architecture doc, first few sections

- add start of architecture documentation
- content to follow in additional commits

Contributes to: strimzi#6

Signed-off-by: Matthew Chirgwin <[email protected]>

* feat: add top level directory section

- adds doc re directory structure, and placeholder content in each
- re orders contents for a more logical ordering

Signed-off-by: Matthew Chirgwin <[email protected]>

* feat: add client code structure section

- adds client code structure section
- completes 'opinionated' architecture sections
- updates licence linting to not change .pptx files

Signed-off-by: Matthew Chirgwin <[email protected]>

* refactor: address review comments

- change pluralisation of directories and readmes
- general phrasing changes

Signed-off-by: Matthew Chirgwin <[email protected]>

Co-authored-by: Matthew Chirgwin <[email protected]>

README.md

@@ -34,6 +34,7 @@ If you run into any issues while working in this repo, please check out [the tro
 
 Further details around how this UI is implemented can be found below:
 
+- [Architecture](./docs/Architecture.md)
 - [Build](./docs/Build.md)
 - [Linting](./docs/Linting.md)
 

client/Bootstrap/README.md

@@ -0,0 +1,39 @@
+# Bootstrap
+
+This directory contains all code required to bootstrap the UI. This will include the build entry point `index.js` ([for further details, see build documentation](../../docs/Build.md)), `index.html` template which will ultimately be returned the to the user when the access the UI, as well as all the React components that set up initial UI state and represent UI level behaviours, such as Navigation or user management.
+
+While it's own directory, the code in this directory should be tested and developed in the same manner as a [`Panel`](../Panels/README.md) component, but additionally make use of user story end to end tests, which drive the whole UI to achieve the stated user goals.
+
+## Test approach
+
+To be defined in https://github.com/strimzi/strimzi-ui/issues/7
+
+## Expected files
+
+For a given Bootstrap component `Navigation`, the expected files are as follows:
+
+```
+Bootstrap/
+  index.js (*)
+  index.html
+  Navigation/
+    index.js (**)
+    README.md
+    View.js
+    Model.js
+    Styling.scss
+```
+
+Where:
+
+- index.js (\*) acts as the build (and thus client) entry point
+- index.html is the HTML template file which is used to
+- index.js (\*\*) acts as a barrel file, exporting all public elements of this component
+- README.md is the readme for this component, detailing design choices and usage
+- View.js is the view logic for this component
+- Model.js (_optional_) is the model (business) logic for this component
+- Styling.scss (_optional_) is the styling for this component
+
+## Components
+
+Components to be added here on implementation, with summary of purpose/usage and a link to it's README.

client/Contexts/README.md

@@ -0,0 +1,31 @@
+# Contexts
+
+This UI makes use of [React Context](https://reactjs.org/docs/context.html) for top level state management. This allows for data to be stored and accessed by any component without needing to prop drill values to that component. In addition, depending on use case, contexts can be used as a component or as a React Hook, allowing for integration of state where ever and however it is required. This directory contains all the custom React Context implementations used across this UI.
+
+It is expected that when used in production Context Provider(s) will be used by the code contained in the [`Bootstrap`](../Bootstrap/README.md) directory. Consumers of the state could be either other [`Bootstrap`](../Bootstrap/README.md) components, or [`Panel`](../Panels/README.md) or [`Group`](../Groups/README.md) components.
+
+## Test approach
+
+To be defined in https://github.com/strimzi/strimzi-ui/issues/7
+
+## Expected files
+
+For a given new Context `FeatureFlagContext`, the expected files are as follows:
+
+```
+Contexts/
+  index.js
+  FeatureFlagContext/
+    README.md
+    Context.js
+```
+
+Where:
+
+- index.js acts as a barrel file, exporting all public elements of this context/the contexts contained in the Context directory
+- README.md is the readme for this Context, detailing design choices and usage
+- Context.js is the implementation of this context
+
+## Available contexts
+
+Contexts to be added here on implementation, with summary of purpose/usage and a link to it's README.

client/Elements/README.md

@@ -0,0 +1,32 @@
+# Elements
+
+`Element` components are presentational React components: they take zero to many properties, and render content based on those properties. They should not contain or perform any business logic themselves, such as accessing state or making requests for data. They could however call callbacks provided to them to trigger these effects. By staying presentational, they thus become highly composable and reusable.
+
+## Test approach
+
+To be defined in https://github.com/strimzi/strimzi-ui/issues/7
+
+## Expected files
+
+For a given Element component `Heading`, the expected files are as follows:
+
+```
+Elements/
+  index.js
+  Heading/
+    index.js
+    README.md
+    View.js
+    Styling.scss
+```
+
+Where:
+
+- index.js acts as a barrel file, exporting all public elements of this component/the components in the Elements directory
+- README.md is the readme for this component, detailing design choices and usage
+- View.js is the view logic for this component
+- Styling.scss (_optional_) is the styling for this component
+
+## Components
+
+Components to be added here on implementation, with summary of purpose/usage and a link to it's README.

client/Groups/README.md

@@ -0,0 +1,34 @@
+# Groups
+
+`Group` components are one or more `Element` components combined and composed together to provide a larger piece of UI. They can own an manage their own state and business logic via a Model if required, and use then use that state (via properties) in the child `Element` components used in this `Group`. By doing this, the `Group` component can act as a layer of abstraction between `Element` components which build up the `Group`, and the `Panel` (and it's global state/data fetching logic for example) the `Group` is used in. This keeps the `Element` and `Group` components as composable as possible, while keeping `Panel` logic together.
+
+## Test approach
+
+To be defined in https://github.com/strimzi/strimzi-ui/issues/7
+
+## Expected files
+
+For a given Group component `HeadingWithToggle`, the expected files are as follows:
+
+```
+Groups/
+  index.js
+  HeadingWithToggle/
+    index.js
+    README.md
+    View.js
+    Model.js
+    Styling.scss
+```
+
+Where:
+
+- index.js acts as a barrel file, exporting all public elements of this component/the components in the Groups directory
+- README.md is the readme for this component, detailing design choices and usage
+- View.js is the view logic for this component
+- Model.js (_optional_) is the model (business) logic for this component
+- Styling.scss (_optional_) is the styling for this component
+
+## Components
+
+Components to be added here on implementation, with summary of purpose/usage and a link to it's README.

client/Hooks/README.md

@@ -0,0 +1,29 @@
+# Hooks
+
+This directory contains all re-usable custom [React Hooks](https://reactjs.org/docs/hooks-intro.html#motivation) implemented for use across this UI. Unlike Models, these hooks encapsulate re-usable/common logic views or models may want to utilise, such as translation capabilities.
+
+## Test approach
+
+To be defined in https://github.com/strimzi/strimzi-ui/issues/7
+
+## Expected files
+
+For a given Hook `useFoo`, the expected files are as follows:
+
+```
+Hooks/
+  index.js
+  useFoo/
+    README.md
+    Hook.js
+```
+
+Where:
+
+- index.js acts as a barrel file, exporting the hooks defined in the Hooks directory
+- README.md is the readme for this hook, detailing design choices and usage
+- Hook.js is the hook implementation
+
+## Implemented hooks
+
+Hooks to be added here on implementation, with summary of purpose/usage and a link to it's README.

client/Images/README.md

@@ -0,0 +1,3 @@
+# Images
+
+This directory contains all images used across the UI. All images are considered as public assets - ie no user authentication is required to retrieve them.

client/Panels/README.md

@@ -0,0 +1,34 @@
+# Panels
+
+A `Panel` component represents a top level element of a UI - the primary/significant capability of a page. A `Panel`s responsibility is not only to compose `Element` and `Group` components to implement the required UI, but to own and manage activities such as data fetching, state reduction, integration with the wider UI and so on. For example, a `Panel` would on mount make a request for and own the response for a piece of data, and while this request is happening, swap in and out `Group` and or `Element` components to represent the loading/error/success states.
+
+## Test approach
+
+To be defined in https://github.com/strimzi/strimzi-ui/issues/7
+
+## Expected files
+
+For a given Panel component `Topics`, the expected files are as follows:
+
+```
+Panels/
+  index.js
+  Topics/
+    index.js
+    README.md
+    View.js
+    Model.js
+    Styling.scss
+```
+
+Where:
+
+- index.js acts as a barrel file, exporting the public API of this component/component bundle.
+- README.md is the readme for this component, detailing design choices and usage
+- View.js is the view logic for this component
+- Model.js (_optional_) is the model (business) logic for this component
+- Styling.scss (_optional_) is the styling for this component
+
+## Components
+
+Components to be added here on implementation, with summary of purpose/usage and a link to it's README.

client/README.md

@@ -0,0 +1,11 @@
+# Client
+
+This directory contains all client code for the Strimzi UI - ie code which is sent to a user's browser. A summary of contents can be found below:
+
+- [Bootstrap](./Bootstrap/README.md) - code and React components which are responsible for bootstrapping the UI
+- [Contexts](./Contexts/README.md) - state management code
+- [Elements](./Elements/README.md) - presentational React components
+- [Groups](./Groups/README.md) - React components which are combine and compose `Element` components
+- [Hooks](./Hooks/README.md) - custom reusable React Hooks
+- [Images](./Images/README.md) - images used across the UI
+- [Panels](./Panels/README.md) - section/page level components