Improve developer documentation

README.md

@@ -11,6 +11,8 @@ With Collage you can upgrade a web application of all sorts to either a micro fr
 For information about collage and its capabilities, please have a look at our [Official Documentation](https://sickag.github.io/collage/).
 
 ---
+## Developer Documentation
+For details about the architecture and structure of collage, please have a look at our [Developer Documentation](./src/DEVELOPER_DOCUMENTATION.md).
 
 ## Preview
 To create and embed micro frontends with collage you just need to add a few lines on top of your already existing Application:
@@ -55,4 +57,4 @@ const api = await expose({
 - Easy to use - Create a micro frontend with just a few lines of code.
 - Use a self explainatory api to describe your micro frontends and orchestrate them in complex arrangements effortlessly.
 - Built on web standards and only a few simple core concepts means that you never run into magic behaviour that ruins your day.
-- Easy to use - Simply wrap the expose() call to create custom functionality.
+- Easy to use - Simply wrap the expose() call to create custom functionality.

index.html

@@ -16,13 +16,15 @@ <h1>Collage Development Dashboard</h1>
 
     <section>
       <h2>Features</h2>
+      <a id="createcontext" href="/src/core/create-context/samples/" target="nav-target">Create Context</a>
+      <a id="embedding" href="/src/elements/samples/" target="nav-target">Embedding a Fragment</a>
       <a id="servicecalls" href="/src/core/services-plugin/service-functions/samples/" target="nav-target">Service Calls</a>
       <a id="modal" href="/src/core/services-plugin/service-functions/samples/modalArrangement.html" target="nav-target">Modal Service</a>
       <a id="directfunctions" href="/src/core/direct-functions-plugin/samples/" target="nav-target">Direct Functions</a>
       <a id="simpletopics" href="/src/core/topics-plugin/simple-topics/samples/" target="nav-target">Simple Topics</a>
       <a id="servicetopics" href="/src/core/topics-plugin/service-topics/samples/" target="nav-target">Service Topics</a>
       <a id="config" href="/src/core/config-plugin/samples/" target="nav-target">Config</a>
-      <a id="reloadBug" href="/src/core/handshake-plugin/samples/locationReloadArrangement.html" target="nav-target">Reload bug</a>
+      <!-- <a id="reloadBug" href="/src/core/handshake-plugin/samples/locationReloadArrangement.html" target="nav-target">Reload bug</a> -->
 
     </section>
     <section>

src/DEVELOPER_DOCUMENTATION.md

@@ -0,0 +1,119 @@
+# Developer Documentation
+
+Before starting to develop collage, please read the documentation about the collage [features](../docs/docs/features.md), [core concepts](../docs/docs/concepts.md) and [core api](../docs/docs/core-api.md).
+
+## Getting started
+
+```bash
+git clone https://github.com/SICKAG/collage.git
+cd collage
+npm install
+```
+
+Now you are ready for developing
+
+### Start the dev server
+
+You can start the dev server by running
+
+```bash
+npm run dev
+```
+
+This will start a dev server. You then can view and debug the example and integration tests defined in the sample folders of the plugins (src/core/)
+
+### Running the tests
+
+You can (and should) keep the unit test running in watch mode while developing
+
+```bash
+npm run test:watch
+```
+
+> Hint: you can keep the dev server and and the unit test running at the same time
+
+## What we are building upon:
+
+- typescript (see [typescript](https://www.typescriptlang.org/) and [tsconfig.json](../tsconfig.json))
+- vite for serving our examples and integration tests and bundling the library (see [vite](https://vitejs.dev) and [vite.config.js](../vite.config.js))
+- jest for unit tests (see [jest](https://jestjs.io) and [jest.config.js](../jest.config.js))
+- vuepress for building our user documentation (see [vuepress](https://vuepress) and [vuepress-config.mjs](../docs/vuepress-config.mjs))
+- github actions for ci/cd
+- penpal for the communication between fragments and arrangements (see [penpal](https://github.com/Aaronius/penpal#readme))
+
+## Structure of the Repository
+
+The structure of the repository is as follows.
+In each folder, you will find a documenting markdown file explaining the details of the respective part.
+
+```md
+collage/
+|-- .github/          // github actions configurations
+|-- docs/             // user documentation built with vuepress
+|-- e2e/              // our e2e tests
+|-- src/              // source code
+|   |-- core/         // core concepts of collage implemented as collage plugins
+|   |-- elements/     // custom elements for a convenient usage of collage
+|   |-- lib/          // internal library structure of collage
+|   |   |-- api/      // collage api 
+
+```
+
+- [core](./core/CORE_CONCEPTS.md)
+- [elements](./elements/README.md)
+- [lib](./lib/README.md)
+
+## Architecture
+
+Collage is build as a plugin library. Each basic feature is defined as a plugin. All default plugins are configured and bootstrapped together.
+
+How this is done, you can read in the documentation about the [internal structure of the collage library](./lib/README.md).
+
+In short:
+
+- all types, and everything needed to put collage and the plugins together can be found in lib.
+- everything that implements functionality for the user is a plugin and can be found in core.
+
+## Contributing
+
+Every contribution is welcome, as we want to make collage a vivid community project.
+
+At the moment we lack a system to enable plug ins dynamically, so each plugin must be built and bundled with the library. We are evaluating to change that in the future, so everybody could add functionality to collage.
+
+### Creating a new plugin/feature
+
+#### Workflow
+
+1. create the plugin
+   1. create a new folder in the src/core directory
+   1. create a plugin file as ts (orient at the core plugins)
+   1. create a samples folder for integration testing examples
+1. create tests
+   1. create e2e test for the new feature
+   1. create unit tests in the plugin folder
+1. create documentation
+   1. create a documentation file as md if necessary
+1. add the plugin to collage
+   1. import the plugin
+   1. add to the plugins array
+
+#### How a plugin is made
+
+With a plugin, you are able to enhance collage by new features.
+For an example of a minimal plugin, please have a look at the [create-context](./core/create-context/create-context.ts).
+
+In short, a valid plugin needs to export the default function `plugin` where it can pass an object, that uses the PluginFunctions to enhance collage by the new features (see [src/types.ts>PluginFunctions](./types.ts) and [collage-plugin](./lib/collage-plugin.ts)).
+
+```ts
+import plugin from '../../lib/collage-plugin';
+
+export default plugin({
+  enhanceExpose: async () => {
+    console.log('I send a message everytime expose() is called');
+  },
+});
+```
+
+## Core Concepts
+
+Read further in the [Core Concepts Documentation](./core/CORE_CONCEPTS.md)

src/core/CORE_CONCEPTS.md

@@ -0,0 +1,109 @@
+# Core Concepts
+
+The core concepts and their implementations as plugins build upon each other and each enhance collage by their specific features.
+
+1. The [collage-fragment](../elements/README.md) custom element.
+1. The [create-context](./create-context/CREATE_CONTEXT.md) plugin
+1. The [handshake](./handshake-plugin/HANDSHAKE.md) plugin
+1. The [direct functions](./direct-functions-plugin/DIRECT_FUNCTIONS.md) plugin
+1. The [services](./services-plugin/SERVICES.md) plugin
+1. The [topics](./topics-plugin/TOPICS.md) plugin
+
+### Notes
+
+How the connection between arrangement and fragment works:
+
+The connection is mediated by the custom element, since that is the point where we are in the parents code context but acually know about a specific child to connect.
+
+A successful connection then enhances the fragments context with methods from the arrangement.
+
+## Create Context
+The most basic concept in collage is that of a context. At it's base a context is simply the representation of a uniquly identified fragment and the connection to a potential parent.
+
+For a more detailled description of the handshake, see [Create Context plugin documentation](./create-context/CREATE_CONTEXT.md).
+
+
+## Handshake
+To set up the communication between a fragment and an arrangement, collage performs a handshake between them.
+
+For a more detailled description of the handshake, see [Handshake plugin documentation](./handshake-plugin/HANDSHAKE.md).
+
+## Service Functions
+Services are functions, an arrangement can provide to all the fragments (and their fragments).
+
+For a more detailled description of the service functions, see [Services plugin documentation](./services-plugin/SERVICES.md).
+
+## Direct Functions
+Direct Functions can be called on a fragment directly by its arrangement
+
+For a more detailled description of direct functions, see [Direct Functions plugin documentation](./direct-functions-plugin/DIRECT_FUNCTIONS.md).
+
+## Topics
+The Topics feature allows an easy way to subscribe to topics and publish new values to topics.
+
+For a more detailled description of the topics plugin, see [Topics plugin documentation](./topics-plugin/TOPICS.md).
+
+## Config
+With configurations an arrangement gets the possibility to configure an embedded fragment and overwrite the default configuration of it.
+
+For a more detailled description of the config plugin, see [Config plugin documentation](./config-plugin/CONFIG_PLUGIN.md).
+
+
+## Finalize Api
+
+The last module to be performed will trim the resulting context api to the fields that we intend a client to use. 
+
+Any internal state that may have been needed to communicate between plugin modules should not be visible in client context.
+
+
+
+## Fragment <-> Arrangement
+
+**In the fragment**
+
+1. collect stuff for my children
+2. collect my exposed functions (child functions)
+3. simple beacon request --> get simple beacon answer?
+4. `connectToParent` with my functions -> gain parent services
+5. add parent stuff to context
+6. send `collage-initialized` event
+7. all my fragments will initialize iframes
+  1. create iframe
+  2. send _what is your id?_ as post message
+  3. await answer
+  4. if answer: `connectToChild`
+
+**In the arrangement**
+
+1. setup a beacon
+2. When a question arrives -> check if we have a matching fragment element (id)
+3. initiate `connectToChild` with the iframe in that element
+4. send response
+
+```javascript
+const definition = {
+  services: {},
+  topics: {},
+  configuration: {},
+  functions: {},
+}
+
+const context = await expose(description)
+
+const arrangementContext = connectToArrangement(description, context)
+
+const combined = combineContexts(context, arrangementContext)
+
+createBeacon(combined, (question) => {
+  if (findFragmentInDOM(question)) {
+    connectToChild()
+    sendAnswer()
+  }
+})
+
+return combined
+```
+
+```html
+<collage-fragment context-id="1234-12344-1234">
+```