Create docs folder, add architecture assets

[esune]

Added a docs folder where we can store documentation resources.

I also added a couple of files resulting from the conversation I had with @bradhead this morning, that pick up on the idea I was mentioning of having a data contract enforced by an interface/abstract class, and leave the actual implementation details to each jurisdiction/entity that will be using the service to issue credentials of any kind. The xml file is a draw.io document that can be re-imported and updated, the svg file is a snapshot at the time of submission.

The proposed architecture has the benefit of being completely stateless (exception made for the information related to whether a credential has been issued or not, which is not really subject to privacy concerns), and removes the need to define ahead of time a specific API model between the VC controller and a data source (or potentially more than one) that is used to obtain the information that will be embedded in the credential.

The VC controller will rely on an interface + abstract class defining the APIs and objects that it will sue to perform its tasks. These APIs will include at least:

• a method to perform discovery of possible data sources, and obtain a list of providers that can be used to fetch data.
• a method to request the data source(s) for a list of records that could be used to compose a credential.
• a method to request the data source for details on specific records - based on input parameters - that returns an the object the VC controller expects in order to successfully build and issue a VC.

The implementation of the abstract class will be provided by each entity using the service, and plugged-in at runtime for their instance: options for this are automatic discovery of implementations or simply specifying the name of the class implementing the abstract class, and having the controller try to find and load such binary on startup. As an example, for our demo the abstract class will also act as the data source itself, loading data form a file or maybe even just providing hard-coded data. All of the business logic responsible for fetching the data from the data source(s), compiling an appropriate payload for the VC controller and implementing authentication/authorization procedures is delegated to the implementation, making it extremely flexible. In our idea, the JWT identifying the user would be passed along as a bearer token so that it can be provided to the data source (e.g.: Health Gateway) as a form of authentication and authorization to only scope requests to a specific user and their data.

Depending on how much information needs to be presented to the user, the frontend could be made smart enough to adapt to different data models, or just rewritten quickly for a new credential structure by using the APIs exposed by the VC controller. It will not hold any information identifying the user, it will instead be provided by the authentication method (Identity Provider, token provided with an invite: it is up to each deployment to specify and potentially implement their authentication structure as required).

The VC controller will only need to have a configurable list of CORS origins injected at runtime (config file, environment variable) that specifies which domains it will accept requests from, so that existing frontends on separate domains could use the exposed APIs.

I think this is a relatively detailed picture, but at the same time provides a simple approach with the minimal possible number of components that need to be defined ahead of time. It also allows - as already mentioned - to easily repurpose the same code to issue credentials that come from data sources we have not really thought of yet (flat file, REST, SOAP, RPC, direct db read, etc.).

[esune]

As an additional note: the proposed is a technical take on the architecture that does not conflict with the view that was designed initially: it just abstracts from having to fully implement and wire up a mock data service, providing instead a way of adapting the issuer to virtually any available data source.

[swcurran]

Agree @itchison .

[esune]

@itchison agreed, mine is a suggestion/recommendation on how we can obtain a system that is scalable and flexible. Definitely open to other suggestions that may be better suited to the problem, my diagram is just meant to propose a solution I see fit - not meant to be the ultimate, perfect solution.

I also agree with you that issuing a credential may be higher on the backlog than run time dependency injection, at the same time structuring things from the beginning so that they can be updated/tweaked without having to deal with major technical debt (e.g.: major refactoring and rewrite to be able to change the data source) is valuable when designing components that must be - by nature - reusable (unless this is a one use case, one jurisdiction solution).