Merge pull request #208 from taleodor/2025-11-new-flow-docs-update

Update documentation based on the latest TEA flow

Author: oej

api-flow/consumer.md

@@ -6,69 +6,66 @@ described in the [discovery document](/discovery/readme.md).
 
 ## API usage
 
-The standard TEI points to a product. A product is something sold, downloaded as an opensource project or aquired
-by other means. It contains one or multiple components.
-
-- __List of TEA Components__: Components are components of something that is part of a product.
-  Each Component has it's own versioning and it's own set of artifacts.
-- __List of TEA Releases__: Each component has a list of releases where each release has a timestamp and
-  a lifecycle enumeration. They are normally sorted by timestamps. The TEA API has no requirements of
-type of version string (semantic or any other scheme) - it's just an identifier set by the manufacturer.
+The standard TEI points to a product release. A product release is something sold, downloaded as an opensource project or aquired by other means. It contains one or multiple component releases.
+
+- __List of TEA Component Rleases__: Component releases are components of a product release.
+  Each Component release has its own versioning and its own set of artefacts, they have a timestamp and   a lifecycle enumeration. They are normally sorted by timestamps. The TEA API has no requirements of type of version string (semantic or any other scheme) - it's just an identifier set by the manufacturer.
 - __List of TEA Collections__: For each release, there is a list of TEA collections as indicated
   by release date and a version integer starting with collection version 1. 
-- __List of TEA Artifacts__: The collection is unique for a version and contains a list of artifacts.
-  This can be SBOM files, VEX, SCITT, IN-TOTO or other documents.  Note that a single artifact
-  can belong to multiple versionsof a Component and multiple Components.
-- __List of artifact formats__: An artifact can be published in multiple formats.
+- __List of TEA Artifacts__: The collection is unique for a version and contains a list of artefacts.
+  This can be SBOM files, VEX, SCITT, IN-TOTO or other documents.  Note that a single artefact
+  can belong to multiple Component or Product Releases.
+- __List of artefact formats__: An artefact can be published in multiple formats.
 
-The user has to know product TEI and version of each component (TEA Component) to find the list of
-artifacts for the used version.
+The user has to know product release TEI and in some cases version of each component (TEA 
+Component Release) to find the list of artefacts for the particular Product Release.
 
 ## API flow based on TEI discovery
 
 ```mermaid
 
 ---
-title: TEA consumer
+title: TEA consumer flow
 ---
-
 sequenceDiagram
     autonumber
-    actor user
-    participant discovery as TEA Discovery with TEI
-
-    participant tea_product as TEA Product
-    participant tea_component as TEA Component
-    participant tea_release as TEA Release
-    participant tea_collection as TEA Collection
-    participant tea_artifact as TEA Artefact
+    actor manufacturer as Manufacturer
+    actor user as TEA Client
 
+    participant discovery as TEA Discovery / TEA Server
+    participant tea_product_release as TEA Product Release
+    participant tea_component_release as TEA Component Release
 
-    user ->> discovery: Discovery using DNS
-    discovery ->> user: List of API servers
+    manufacturer ->> user: Provides TEI (Transparency Exchange Identifier)
 
-    user ->> tea_product: Finding all product parts (TEA Components) and facts about the product
-    tea_product ->> user: List of product parts
+    user ->> discovery: GET https://<domain>/.well-known/tea
+    discovery -->> user: TEA discovery document (API servers & endpoints)
 
-    user ->> tea_component: Finding information of a component
-    tea_component ->> user: List of component metadata
+    user ->> discovery: Call Discovery endpoint with TEI
+    discovery -->> user: Product Release reference(s)
 
-    user ->> tea_release: Finding a specific version/release
-    tea_release ->> user: List of releases and collection id for each release
-
-    user ->> tea_collection: Finding all artefacts for version in scope
-    tea_collection ->> user: List of artefacts and formats available for each artefact
-
-    user ->> tea_artifact: Request to download artifact
-    tea_artifact ->> user: Artifact
+    alt Multiple Product Releases returned
+        user ->> tea_product_release: Resolve Product Release(s)
+        tea_product_release -->> user: List of Component Releases
+        user ->> user: Identify Discriminating Component Releases
+        user ->> tea_component_release: Resolve Discriminating Component Releases
+        tea_component_release -->> user: Discriminating Component Release Details
+        user ->> user: Converge on a Single Product Release
+    end
 
+    user ->> tea_product_release: Resolve Product Release Details
+    tea_product_release -->> user: List of Component Releases
 
+    loop For each tea_component_release
+        user ->> tea_component_release: Obtain latest collections
+        tea_component_release -->> user: List of TEA Artifacts
+    end
 
 ```
 
 ## API flow based on direct access to API
 
-In this case, the client wants to search for a specific product using the API
+In this case, the client wants to search for a specific product release using the API
 
 ```mermaid
 
@@ -80,30 +77,26 @@ sequenceDiagram
     autonumber
     actor user
 
-    participant tea_product as TEA Product
-    participant tea_component as TEA Component
-    participant tea_release as TEA Release
+    participant tea_product_release as TEA Product Release
+    participant tea_component_release as TEA Component Release
     participant tea_collection as TEA Collection
-    participant tea_artifact as TEA Artefact
+    participant tea_artifact as TEA Artifact
 
 
-    user ->> tea_product: Search for product based on identifier (CPE, PURL, name)
-    tea_product ->> user: List of products
+    user ->> tea_product_release: Search for product releases based on identifier (CPE, PURL, name)
+    tea_product_release ->> user: List of product releases
 
-    user ->> tea_product: Finding all product parts (TEA Components) and facts about choosen product
-    tea_product ->> user: List of product parts
+    user ->> tea_product_release: Finding all product parts (TEA Component Releases) and facts about choosen product
+    tea_product_release ->> user: List of TEA Component Releases
 
-    user ->> tea_component: Finding information of a component
-    tea_component ->> user: List of component metadata
+    user ->> tea_component_release: Finding information of a component release
+    tea_component_release ->> user: List of releases and collection id for each release
 
-    user ->> tea_release: Finding a specific version/release
-    tea_release ->> user: List of releases and collection id for each release
-
-    user ->> tea_collection: Finding all artefacts for version in scope
-    tea_collection ->> user: List of artefacts and formats available for each artefact
+    user ->> tea_collection: Finding all TEA Artifacts for TEA Component Release
+    tea_collection ->> user: List of TEA Artifacts and formats available for each TEA Artifact
 
-    user ->> tea_artifact: Request to download artifact
-    tea_artifact ->> user: Artifact
+    user ->> tea_artifact: Request to download TEA artifact
+    tea_artifact ->> user: TEA Artifact
 
 ```
 
@@ -123,22 +116,22 @@ sequenceDiagram
     autonumber
     actor user
 
-    participant tea_product as TEA Product
     participant tea_component as TEA Component
-    participant tea_release as TEA Release
-    participant tea_collection as TEA Collection
-    participant tea_artifact as TEA Artefact
+    participant tea_component_release as TEA Component Release
+
+    user ->> tea_component: Finding a specific version/release
+    tea_component ->> user: List of releases and collection id for each release
 
-    user ->> tea_release: Finding a specific version/release
-    tea_release ->> user: List of releases and collection id for each release
+    user ->> tea_component_release: Details for discovered release
+    tea_component_release ->> user: Collection with artefact details for the release
 
 ```
 
 ## API flow based on cached data  - checking if a collection changed
 
 In this case a TEA client knows the release UUID, the collection UUID, and the
 collection version from previous queries. If the given version is not the same,
-another query is done to get reason for update and new collection list of artifacts.
+another query is done to get reason for update and new collection list of artefacts.
 
 
 ```mermaid
@@ -151,11 +144,7 @@ sequenceDiagram
     autonumber
     actor user
 
-    participant tea_product as TEA Product
-    participant tea_component as TEA Component
-    participant tea_release as TEA Release
     participant tea_collection as TEA Collection
-    participant tea_artifact as TEA Artefact
 
 
     user ->> tea_collection: Finding the current collection, including version

discovery/readme.md

@@ -14,23 +14,23 @@
 
 ## From product identifier to API endpoint
 
-TEA Discovery is the connection between a product identifier and the API endpoint.
-A "product" is something that the customer aquires or downloads - hardware and/or software.
+TEA Discovery is the connection between a product release identifier and the API endpoint.
+A "product release" is something that the customer aquires or downloads - hardware and/or software.
 
 It can be a bundle of many digital devices or software applications.
-A "product" normally also has an entry in a large corporation's asset inventory system.
+A "product release" normally also has an entry in a large corporation's asset inventory system.
 
-A product identifier is embedded in a URN where the identifier is one of many existing
+A product release identifier is embedded in a URN where the identifier is one of many existing
 identifiers or a random string - like an EAN or UPC bar code, UUID, product
 number or PURL.
 
 The goal is for a user to add this URN to the transparency platform (sometimes with an
-associated authentication token) and have the platform access the required artifacts
+associated authentication token) and have the platform access the required artefacts
 in a highly automated fashion.
 
 ## Advertising the TEI
 
-The TEI for a product can be communicated to the user in many ways.
+The TEI for a product release can be communicated to the user in many ways.
 
 - A QR code on a box
 - On the invoice or delivery note
@@ -41,16 +41,16 @@ is defined by the manufacturer and can normally not be derived from known inform
 
 ## TEA Discovery - defining an extensible identifier
 
-TEA discovery is the process where a user with a product identifier can discover and download
-artifacts automatically, with or without authentication. A globally unique identifier is
-required for a given product. This identifier is called the Transparency Exchange Identifier (TEI).
+TEA discovery is the process where a user with a product release identifier can discover and download
+artefacts automatically, with or without authentication. A globally unique identifier is
+required for a given product release. This identifier is called the Transparency Exchange Identifier (TEI).
 
 The TEI identifier is based on DNS, which assures a uniqueness per vendor (or open source project)
-and gives the vendor a name space to define product identifiers based on existing or new identifiers
-like EAN/UPC bar code, PURLs or other existing schemes. A given product may have multiple identifiers
+and gives the vendor a namespace to define product release identifiers based on existing or new identifiers
+like EAN/UPC bar code, PURLs or other existing schemes. A given product release may have multiple identifiers
 as long as they all resolve into the same destination.
 
-The vendor needs to make sure that the TEI is unique within the vendor's name space. There is no
+The vendor needs to make sure that the TEI is unique within the vendor's namespace. There is no
 intention to create any TEI registries.
 
 ## The TEI URN: An extensible identifier
@@ -60,9 +60,8 @@ identifiers like EAN codes, PURL and other identifiers. It is based on a DNS nam
 to global uniqueness without new registries.
 
 The TEI can be shown in the software itself, in shipping documentation, in web pages and app stores.
-TEI is unique for a product, not a version of a product.
 
-A TEI belongs to a single product. A product can have multiple TEIs - like one with a EAN/UPC
+A TEI belongs to a single product release. A product release can have multiple TEIs - like one with a EAN/UPC
 barcode and one with the vendor's product number.
 
 ### TEI syntax