# Business Case ### Business problem and proposed solution Retail store business is one of the most important ones in our economy. It offers a large variety of products to the end customers at different stores, at different prices, and attracts a large number of people every day. However, to improve the experience for the customers another very important thing could be implemented – food supply chain tracking. Such functionality would allow retail workers and end customers to track and trace food products in the supply chain so that any product can be traced back to its roots. There are many use cases around provenance for the food supply chain as it can help troubleshoot supply chain bottlenecks, forecast the shelf life of the fresh produce as its moving through the supply chain, and help pin-ointing the origin of the product in case of recalls. To implement this in real life, a blockchain-based solution is proposed. Using the enterprise-based blockchain Hyperledger Fabric it is possible to setup many organizations (such as farms, factories, distribution centers, stores) and constructs a reliable messaging channel that allows tracking any product at any stage from the orchard or sea to the store shelves. One such example is shown in the figure below. ![Logo](https://camo.githubusercontent.com/21b31b42790e98ac548ad88228ed39f3eb3e3e2e295e81d48b2184cc3489fe1f/68747470733a2f2f616c6578616e647265626172726f732e636f6d2f676c6f62616c2f68797065726c65646765722f50696374757265312e706e673f616c743d68797065726c65646765722d737570706c792d636861696e2d6469616772616d) ### Overall Solution and Architecture We designed a solution for a simple supply chain network aligned with business requirements, we are considering two organizations for this solution, Org1 is considered as farm and Org2 is a Consortium of manufacturing, distribution and retail units of a single organization. Data Flow starts from the farm where the initial products get produced and when the end product is sold off the shelves at retails stores. ![](/files/-MdvqXwxl5o3rUBhNLP0) ### ### Physical Asset in the Network * Food products (Apples, etc) ### Models The first stage of design for such a system is to define the model of the business domain. The central entity, in this case, is the product. The tables and figures below show the abstraction model for a generic product that will be used in the system. #### Model Description | Field | Type | Required | Description | | --------------------- | ------------------------- | -------- | --------------------------------------------------------------------------------- | | componentProductIds | Array | Yes | Collection of product IDs that are used as components for a given product | | id | String | Yes | A unique identifier of a product in the system | | barcode | String | Yes | Barcode | | name | String | Yes | Product name | | placeOfOrigin | String | Yes | Place of origin | | productionDate | String (as ISO 8601 date) | Yes | Date of product production (e.g., when the product was picked, caught, or cooked) | | expirationDate | String (as ISO 8601 date) | Yes | Date when product shelf life expires | | unitQuantity | Number | Yes | Product quantity in one unit (used together with unitQuantityType) | | unitQuantityType | String | Yes | Unit of measure for a product unit (e.g., kg, liter, oz etc.) | | batchQuantity | Number | No | Number of product units in a batch | | unitPrice | String | Yes | Price for a product unit (formatted with a currency symbol, e.g., “$10.00”) | | category | String | Yes | Product category | | variety | String | No | Product variety | | misc | Object | No | A dictionary of additional miscellaneous data about a product | | locationData.previous | Array | No | Collection of previous product locations | | locationData.current | ProductLocationEntry | Yes | Current product location | | location | String | Yes | Current location of a product (e.g., “Etobicoke, ON, Canada”) | | arrivalDate | String (as ISO 8601 date) | Yes | The arrival date of the product to a given location | #### Model Definition for the Asset ```javascript "product": { "componentProductIds": Array, "id": String, "barcode": String, "name": String, "placeofOrigin": String, "productionDate": String, "expirationDate": String, "unitQuanitity": Number, "unitQuantityType": String, "batchQuantity": Number, "unitPrice": String, "category": String, "variety": String, "misc": Object, "location": "previous": Array, "current": ProductLocationEntry } } "productLocationEntry":{ "location": String, "arrivalDate": String } ``` A sample instance of this model is shown in the figure below. In this case, it is apple jam. It is made of another product which is tracked in our system – apples, which has ID of “456”. The place of origin is Etobicoke, ON, Canada (a more specific location could be used as well). Unit quantity inside a single apple jam jar is 300 mg. Is it not part of any batch, so it’s tracked individually. The product has no specific variety, nor any additional miscellaneous information. The previous locations of this apple jam jar are Etobicoke and Brampton. And the current location is Walmart Supercentre - 900 Dufferin St, Toronto, ON. The date of each location is tracked as well. Based on this information, as well as based on previous product IDs which were used to produce a given product a customer can check the whole supply chain to see the place of origin of products used to produce it. At the same time, a store employee can use this information to troubleshoot supply chain bottlenecks. #### Sample Model Instance ```javascript { "product": { "component ProductIds": ["456"], "id": "789", "barcode": "4353453343", "name": "Apple jam", "placeoforigin": "Etobicoke, ON, Canada", "produceDate": "2021-06-24T18:25:43.511", "expirationDate": "2022-06-24T18:25:43.511z", "unitQuanitity": "300" "unitQuantityType": "mg", "batchQuantity": null, "unitPrice": "$5.00" "category": "Fruit jams", "variety": null, "misc": {}, "locationData": { "previous":[ { "location": "Etobicoke, ON, Canada", "arrivalDate": "2021-06-24T18:25:43.5112" }, { "location": "Brampton, ON, Canada", "arrivalDate": "2021-06-25T09:05:12.5112" } ], "current": { "location": "Walmart Supercentre 900 Dufferin St, Toronto, ON", "arrivalDate": "2021-06-30T18:00:58.511Z" } } } } ``` Based on the food supply chain shown initially and on the developed models a sample food supply chain is demonstrated in the figure below. Initially, apples are picked by the farmer and a corresponding product instance is created on the blockchain. Then they get transported to a new location as a whole batch. On this location (e.g., a factory) it gets processed into apple jam. A new product instance should be created to reflect this. The chain is created by saving the ID of the product it is made of (apples with ID “123”). Then the apple jam gets packaged into jars at the same facility and a new product instance is created as a result for each apple jam jar. Apple jam jars then get transported to the store. In the end, apple jam is sold to the end customer but it is not required by the system. #### Food Supply Chain Example ![Logo](https://camo.githubusercontent.com/affe9987b20c7f80098a39c9c8f44ba594c1a5713a804e42f1d57a620cc8b404/68747470733a2f2f616c6578616e647265626172726f732e636f6d2f676c6f62616c2f68797065726c65646765722f50696374757265342e706e673f616c743d68797065726c65646765722d666f6f642d737570706c792d636861696e2d6578616d706c65) ### Modelling contracts and transactions As a result of model creation and product flow analysis, the following chaincode operations have been identified as shown in the table below. #### Chain Code Operations | Method | Input | Output | Design | | ---------- | ------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------- | | Create | Product object / IDs of component products | None | Check required fields (id, component product IDs, name etc.) / Check permissions | | ShipTo | Product ID / New location | None | Check new location is not empty / Check permissions | | Get | Product ID | Product object | Check product ID is not empty / Check permissions | | GetHistory | Product ID | Product history object | Check product ID is not empty / Check permissions | Create operation is needed to create an instance of a product. A product can be a part of a batch, in which case the batchQuantity will not be null. Besides the product object itself, it accepts an array of component products which can be empty if there are no other products this product is made of. This operation returns nothing, and a couple of validation checks need to be done to make sure required fields are not empty and are in a valid format. ShipTo operation allows to mark a given product as shipped to another place, basically updating its internal location.previous and location.current properties. The new location should not be empty. Get operation returns a given product by its ID. ID should not be empty as well. GetHistory operation allows retrieving a given product together with its component (parent) products it is made of. The returned object corresponds to the structure shown in the figure below. #### Model Instance for Product History ```javascript { "product": { "component Products": Array, "id": String, "barcode": String, "name": String, "placeoforigin": String, "productionDate" String, "expirationDate": String, "unitQuanitity": Number, "unitQuantityType": String, "batchQuantity": Number, "unitPrice": String, "category": String, "variety": String, "misc": Object, "location": { "previous": Array, "current": String } } ``` The table below shows the user roles that can be used for each chaincode operation. The “product creator” role may pertain to users from farms who produce products. The “ShipProductTo” function should be available for “product creator” and “carrier” roles as both should be able to change the location of a product from a location to another. The “GetProduct” and “GetProductWithHistory” functions are available for all the roles in the system, including the “store employee” and “customer Web UI”. The latter role is intended to be used by the back end which provides data for the customer Web interface, where users can view product details and supply chain. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://rapchan.gitbook.io/hyperledger-food-supply-chain/the-business-case.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.