[#3558] Docs for Contributing and Defining Components #3574
Conversation
armanjindal
requested review from
chrismatix,
AitorAlgorta,
steffh,
ljupcovangelski,
sgarroum,
juan-sebastian and
AudreyKj
|
|
||
| ::: | ||
|
|
||
| `Airy Core` is fundamentally a collection of components. When you [install `Airy Core`](../getting-started/installation/introduction.md), you install a set of _core_ components which create the minimum infrastructure to install other components and begin using the platform. |
There was a problem hiding this comment.
Airy Core is not really how we market the open source. Let's just call it Airy and mention that it shipds with a few components out-of-the-box.
There was a problem hiding this comment.
Sounds good. Although there are a ton of references to Airy Core in the docs, so we might need a larger fix. For now I will refer to it as Airy.
| Airy is designed to support a plug-and-play architecture. Components are installed and run as pods in your cluster. Components can provide four kinds of functionality: | ||
|
|
||
| 1. Connector - i.e Rasa, DialogFlow | ||
| 2. Source - i.e., Facebook, WhatsApp, SMS |
There was a problem hiding this comment.
We decided to not differentiate between sources and connectors on a component level.
In the glossary docs I suggested the following definition for a connector which nicely brackets both use cases:
A connector is a type of component that authenticates with one or more third-party services in order to exchange data
This document should link to the glossary definitions that aren't here yet, unfortunately. @AitorAlgorta perhaps we can already add definitions for component and connector in this PR?
|
|
||
| ## The Component File Structure | ||
|
|
||
| Below is a model of the file stucture of a single component inside the [`airy-components`](https://github.com/airyhq/airy-/airy-components) repository. |
There was a problem hiding this comment.
I created the repository that we can use to link to correctly: https://github.com/airyhq/airy-components
| ``` | ||
| /airy-components | ||
| /[COMPONENT_NAME] | ||
| information.yaml |
There was a problem hiding this comment.
description.yaml seems a bit more apt. What do you think? 🤔
Also sharing this neat little app for generating these file graphs: https://tree.nathanfriend.io/
armanjindal
changed the title
| @@ -0,0 +1,13 @@ | |||
| A component is a Helm Chart that can be installed on an Airy Cluster in order to extend its functionality. | |||
There was a problem hiding this comment.
We do call components also the components which are part of Airy Core: api-admin, api-communication 🤔 Perhaps a collection of functionalities and resources? There some components which are part of Core and the others can be installed on top.
|
|
||
| :::note | ||
|
|
||
| A Component can provide multiple functions (e.g., Connector & UI or UI & API) but usually has a single primary function. You can find a more detailed description of a specific component in the `description.yaml` file of the component in our [airy-components](https://github.com/airyhq/airy-components) respository. |
There was a problem hiding this comment.
I agree that this is how we should do it (with the description.yaml file). However this is not there at the moment and the CI pipeline should be setup in place before we can write this.
There was a problem hiding this comment.
We will hold off on this detail in the definition and move it to the contributing components page. This is marked as under development, so will help to implement when we do this.
The purpose of this PR is to organize discussions around how we want to maintain and update components. I have tried to capture our internal discussion on this issue in this initial draft. This PR also includes an update to our definition of
Componentsin the glossary (#3294). Please amend/discuss/comment!The secondary purpose is to merge these docs before we implement the proposed change. This way, we can adopt a "docs-driven" development approach.
The primary change proposed is the creation of an external repository where the Helm package and information on components are stored. The benefits of this approach are:
description.yamlassociated with a connector file becomes the "source of truth" on components and can be standardized for the Control Center.