chore(doc): document sinkbinding in the context of sources and Kamelets

docs/modules/ROOT/nav.adoc

@@ -27,6 +27,7 @@
 *** xref:architecture/cr/camel-catalog.adoc[CamelCatalog]
 ** xref:architecture/runtime.adoc[Runtime]
 ** xref:architecture/traits.adoc[Traits]
+** xref:architecture/sources.adoc[Sources]
 * Observability
 ** xref:observability/monitoring.adoc[Monitoring]
 * xref:traits:traits.adoc[Traits]

docs/modules/ROOT/pages/architecture/architecture.adoc

@@ -4,8 +4,12 @@
 
 image::architecture/camel-k.jpg[Overview]
 
-The *Camel K* platform is based on three concepts:
+The *Camel K* core platform is based on three concepts:
 
 1. The xref:architecture/operator.adoc[Operator] which is the intelligence that coordinates all the moving parts.
 2. The xref:architecture/runtime.adoc[Runtime] which provides the functionnality to run the integration.
 3. The xref:architecture/traits.adoc[Traits] through wich the behavior of the operator and the runtime can be customized.
+
+For information on how *Camel K* is able to provide *Sources* e.g. for the Knative platform:
+
+- The xref:architecture/sources.adoc[Sources] page describes how sources are internally materialized.

docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc

@@ -1,7 +1,7 @@
 [[camel-catalog]]
 = CamelCatalog
 
-The*CamelCatalog* is a static side resources that provides metadata related to the what it is included in the xref:architecture/runtime.adoc[Runtime] in term of Camel components, languages, dataformats and what capabilities are prvided.
+The *CamelCatalog* is a static side resources that provides metadata related to the what it is included in the xref:architecture/runtime.adoc[Runtime] in term of Camel components, languages, dataformats and what capabilities are prvided.
 
 [NOTE]
 ====

docs/modules/ROOT/pages/architecture/sources.adoc

@@ -0,0 +1,88 @@
+[[sources]]
+= Sources
+
+WARNING: This document describes features that will be
+*available in Camel K 1.2.x* (not released at the time of writing: August 08, 2020)
+
+One of the goals of Camel K is to provide connectors that can be easily installed on any Kubernetes cluster and
+used when needed to provide data to internal services or publish data outside, without requiring any in-depth knowledge about Apache Camel from the end-users.
+
+Knative Sources fall into this category, but in general, sources described here can be used with any underlying technology.
+
+NOTE: https://knative.dev/docs/eventing/samples/apache-camel-source/[Knative CamelSources] are a community effort to provide specific sources for Knative.
+What we describe in this document is a more general approach that is alternative to Knative CamelSources and aims to supersede them.
+
+== Sources Design
+
+The following diagram shows how sources are materialized from their elementary building blocks.
+
+image::architecture/camel-k-sources-diagram.png[Next-gen Sources diagram]
+
+=== Kamelets as Abtract Sources
+
+In the context of sources, *Kamelets* play the role of abstract sources that can be materialized once the user provides values for all
+mandatory parameters contained in the Kamelet specification.
+
+What follows is a simple Kamelet that can produce periodic events with a specified payload:
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: Kamelet
+metadata:
+  name: timer
+spec:
+  definition:
+    title: "Timer"
+    description: "Produces periodic events with a custom payload"
+    required:
+      - message
+    properties:
+      payload: # <1>
+        title: Payload
+        description: The message to generate as payload of each Cloudevent
+        type: string
+  # continues with the flow declaration
+  # ...
+----
+<1> The definition of the `payload` property
+
+The Kamelet contains the definition of all properties in JSON Schema format. In this example, there's only a single property named `payload`.
+
+A Kamelet does nothing when created on a cluster, but it can be used later to create sources, as explained in the remainder of this document.
+
+=== Integration: binding a Kamelet to a destination
+
+An integration can be used to bind a Kamelet to a destination, providing values for all the Kamelet parameters.
+
+For example, the following integration binds the `timer` Kamelet to the Knative *InMemoryChannel* named `mychannel`:
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Integration
+metadata:
+  name: timer-source
+spec:
+  flows:
+  - from:
+      uri: kamelet:timer # <1>
+      parameters:
+        payload: "Hello World" # <2>
+      steps:
+      - to: knative:channel/mychannel?apiVersion=messaging.knative.dev/v1beta1&kind=InMemoryChannel # <3>
+----
+<1> Reference to the Kamelet named `timer`
+<2> Value for the `payload` required property (and others, if present)
+<3> Destination of the generated events
+
+When binding a Kamelet to a single (fully specified) Knative destination, Camel K does not attempt to do any binding,
+instead it delegates the actual mapping to a Knative *SinkBinding* resource.
+
+The **SinkBinding** intercepts the creation of the Deployment containing the integration specification, to inject the
+exact coordinates of the destination (in the example, of the InMemoryChannel named `mychannel`).
+This mechanism works also if the integration is materialized into a Knative Serving Service or into a CronJob, not only if a
+standard Deployment is used.
+
+The SinkBinding resource is also interpreted at Knative level as a standard source, so the `kn` CLI is able to properly recognize
+it. UI tools based on Knative, e.g. the OpenShift console, should also be able to display it as a standard source.