Merge pull request #158 from redhat-appstudio/resource-descriptions

Summarize entity roles, lifecycles, relationships

architecture/index.md

@@ -39,6 +39,61 @@ API resources in the second row (PipelineRun, Snapshot) should primarilly be tho
 data-plane resources. The system responds to user requests by creating and managing the lifecycle of
 these resources.
 
+- An [Application] represents a functionally coherent set of [Components] that should be built,
+  tested, and released together. The user provides and names their [Applications]. They are
+  generally long-lived and don't change much after they are created.
+- A [Component] represents a git branch on a git repository (and a particular context directory)
+  that should be used to build OCI artifacts from commits that appear there. A [Component] is owned
+  by an [Application]. The user provides and names their [Components] and specifies which git
+  repositories and branches define how the artifact is built.  The user may add, remove, or change
+  [Components] over the lifespan of an [Application].
+- A [Snapshot] represents a collection of particular OCI artifacts, mapped to [Components].
+  A [Snapshot] is owned by an [Application]. Generally, the [integration-service] produces new
+  [Snapshots] automatically in response to completed builds. It is also possible for
+  the user to construct and provide [Snapshots] to test or release deliberate combinations of
+  OCI artifacts. [Snapshots] are immutable. For a user to "modify" a [Snapshot], they need to create
+  a new [Snapshot] based on an old [Snapshot]. Old [Snapshots] are garbage collected if not bound to
+  other resources like a [SnapshotEnvironmentBinding] or a [Release].
+- An [IntegrationTestScenario] represents a test that should be run against new [Snapshots] that
+  belong to a particular [Application]. It is owned by an [Application]. The user provides
+  tekton pipelines that test their application and registers them with the system by creating
+  [IntegrationTestScenarios].
+- An [Environment] represents a destination that [application-service] and the [gitops-service] can
+  deploy to. Multiple [Applications] in the same workspace can deploy to the same
+  [Environment]. An [Environment] may be long lived (like the `development` [Environment] provided
+  by the system as part of the initialization of a user's workspace) or may be short-lived and
+  ephemeral (like the temporary [Environments] created by the [integration-service] as a part of its
+  test execution processes).
+- A [DeploymentTargetClaim] represents a request to provision a new deployment target. An
+  [Environment] is backed by a [DeploymentTargetClaim]. The [DeploymentTargetClaim] causes new
+  deployment targets to be provisioned which are represented by [DeploymentTargets] that get bound
+  to it. These are typically created and destroyed by the [integration-service] as a part of its
+  test execution processes.
+- A [SnapshotEnvironmentBinding] represents a request to deploy a particular set of OCI artifacts
+  (represented by a [Snapshot]) to a particular location (represented by an [Environment]).
+  A [SnapshotEnvironmentBinding] is owned by an [Application]. The [integration-service promotes
+  OCI artifacts] by updating the [SnapshotEnvironmentBinding] associated with an [Environment]. The
+  [SnapshotEnvironmentBinding] is generally long-lived.
+- A [ReleasePlan] represents a release pipeline that can be used to release a [Snapshot] to some
+  destination, depending on the implementation of the release pipeline. A [ReleasePlan] is owned by
+  an [Application]. It can operate in two modes, one which executes a "tenant" release pipeline in
+  the user's workspace, and another when used in conjunction with a [ReleasePlanAdmission] where it
+  executes a "managed" release pipeline in a separate privileged workspace owned by another team.
+  The [ReleasePlan] is generally long-lived.
+- A [ReleasePlanAdmission] represents an *acceptance* of release pipeline content from another
+  team's workspace into *this* workspace. It is used exclusively in conjunction with a [ReleasePlan]
+  to represent agreement on details about how to release [Snapshots] across workspace boundaries.
+  The [ReleasePlanAdmission] is generally long-lived.
+- A [Release] represents a request to release a particular set of OCI artifacts (represented by
+  a [Snapshot]) by particular means (represented by the release pipeline details in
+  a [ReleasePlan]). The creation of a [Release] causes [release-service] to create a release
+  PipelineRun in one or more workspaces depending on details in the associated [ReleasePlan] and
+  [ReleasePlanAdmission]. A [Release] can be created in one of two ways: if the [ReleasePlan] has an
+  *automated release* flag set to true, then [integration-service] will automatically create new
+  [Releases] for every [Snapshot] that successfully passes its post-merge testing. If that flag is
+  set to false, then the user is expected to create new a [Release] manually, associated with
+  [Snapshot] selected by the user manually.
+
 ## Service (Component) Context
 
 Each service that makes up AppStudio is further explained in its own document.
@@ -48,7 +103,7 @@ Each service that makes up AppStudio is further explained in its own document.
 - [Build Service](./build-service.md) - A workflow system that manages the build pipeline definition
   for users' Components.
 - [Image Controller](./image-controller.md) - A subsystem of the build-service that manages the
-  creation and access rights to container image repositories.
+  creation and access rights to OCI repositories.
 - [Java Rebuilds Service](./jvm-build-service.md) - A subsystem of the build-service that manages
   the rebuild of binary java jars pulled from maven central for an improved degree of provenance.
 - [Integration Service](./integration-service.md) - A workflow service that manages execution of
@@ -62,7 +117,7 @@ Each service that makes up AppStudio is further explained in its own document.
 - [Service Provider Integration](./service-provider-integration.md) - A foundational service
   providing user secret management to other services.
 - [Enterprise Contract](./enterprise-contract.md) - A specialized subsystem responsible for the
-  definition and enforcement of policies related to how container images are built and tested.
+  definition and enforcement of policies related to how OCI artifacts are built and tested.
 
 ## API References
 
@@ -75,3 +130,31 @@ Each service that makes up AppStudio is further explained in its own document.
 ### Naming Conventions
 
 - [Namespace Metadata](../ADR/adr-0010-namespace-metadata)
+
+[integration-service promotes OCI artifacts]: ../ADR/0016-integration-service-promotion-logic.md
+[application-service]: ./hybrid-application-service.md
+[gitops-service]: ./gitops-service.md
+[integration-service]: ./integration-service.md
+[release-service]: ./release-service.md
+[Application]: ../ref/application-environment-api.md#application
+[Applications]: ../ref/application-environment-api.md#application
+[Component]: ../ref/application-environment-api.md#component
+[Components]: ../ref/application-environment-api.md#component
+[Environment]: ../ref/application-environment-api.md#environment
+[Environments]: ../ref/application-environment-api.md#environment
+[Snapshot]: ../ref/application-environment-api.md#snapshot
+[Snapshots]: ../ref/application-environment-api.md#snapshot
+[SnapshotEnvironmentBinding]: ../ref/application-environment-api.md#snapshotenvironmentbinding
+[SnapshotEnvironmentBindings]: ../ref/application-environment-api.md#snapshotenvironmentbinding
+[DeploymentTarget]: ../ref/application-environment-api.md#deploymenttarget
+[DeploymentTargets]: ../ref/application-environment-api.md#deploymenttarget
+[DeploymentTargetClaim]: ../ref/application-environment-api.md#deploymenttargetclaim
+[DeploymentTargetClaims]: ../ref/application-environment-api.md#deploymenttargetclaim
+[Release]: ../ref/release-service.html#release
+[Releases]: ../ref/release-service.html#release
+[ReleasePlan]: ../ref/release-service.html#releaseplan
+[ReleasePlans]: ../ref/release-service.html#releaseplan
+[ReleasePlanAdmission]: ../ref/release-service.html#releaseplanadmission
+[ReleasePlanAdmissions]: ../ref/release-service.html#releaseplanadmission
+[IntegrationTestScenario]: ../ref/integration-service.html#integrationtestscenario
+[IntegrationTestScenarios]: ../ref/integration-service.html#integrationtestscenario