updates to architecture core and other refinements

source/architecture/core.md

@@ -9,8 +9,9 @@ It contains the following main components:
 - Libraries to communicate with the vendor-specific wallet APIs, like with Google, Apple, or {term}`HCE` systems like NXP, Legic, and HID. In the future, other wallet providers are planned to be supported.
 - An abstract vendor-neutral library to support all libraries above on a simplified level by providing a unified API.
 - A scalable event-based system to distribute data emitted by wallet actions.
-- a callback handler to proxy events emitted by the wallet provider to the eduTAP system.
-  The events are emitted if a pass is saved or deleted in the holder's {term}`wallet`.
+- a callback handler to proxy events emitted by the Google wallet provider to the eduTAP system.
+  The events are emitted if a pass is saved or deleted in the holder's Google {term}`wallet`.
+- an Restful API service to store and retrieve Apple passes and templates. It emits events similar to the Google callback handler.
 - Front ends to manage and issue passes:
   - A "Pass Backoffice" to create/ update pass classes (including a generic "Pass Designer") and manage the lifecycle of pass objects,
   - A white label "Tapper Portal" (web and kiosk modes) to apply for passes and manage their passes.
@@ -23,9 +24,12 @@ It contains the following main components:
 Core Overview.
 
 ```
-## Wallet specific API Libraries
+## Wallet specific API Libraries and support services
 
-A set of libraries to be used by developers writing management software for passes to interact with the specific vendor REST APIs.
+A set of libraries to be used by developers writing management software for passes.
+Additionally, services are provided to be used by the libraries or the vendor specific systems.
+
+They interact either with the specific vendor REST APIs or provide the functionality.
 
 In eduTAP the APIs are meant to be used by the Pass Management Portal and the Pass User Portal.
 
@@ -37,25 +41,22 @@ It is planned to support the following vendors
 - [EU Digital Identity Wallet](https://eudiwalletconsortium.org/)
 - [openWallet Foundation](https://openwallet.foundation/)
 
-```{todo}
-- [ ] Add Links to the vendors wallet pages
-```
-```{todo}
-- [ ] Link the concepts.
-```
+Each vendor works conceptionally different.
+Thus the libraries are different in their structure and API.
 
-At first, we will implement APIs for Google and Apple. The next part focuses on this.
+At first, we will implement APIs for Google and Apple.
+The next part focuses on this.
 
-For both, pass objects and pass classes the API provides the following functionality:
+For both, passes (Google: wallet objects) and pass templates (Google: wallet classes) the eduTAP API provides the following functionality:
 - create,
 - read,
 - update,
 - notify (messaging)
 - manage the state (lifecycle),
 - list (with basic filters).
 
-There are predefined, vendor-specific {term}`stereotypes <stereotype>` and specific types of pass classes.
-The library defines models for all of these.
+There are predefined, vendor-specific {term}`stereotypes <stereotype>` and specific types of passes.
+The libraries are defining models for all of these.
 The models can be referenced by name on the above operations using a registry.
 
 First, those libraries will be implemented using Python.
@@ -64,11 +65,16 @@ There will be a Python package for each vendor, at first:
 - `edutap.wallet_google`
 - `edutap.wallet_apple`
 
-Both libraries follow the same structure and public API, as well as upcoming APIs.
+Both libraries follow the same basic structure and public API, as well as upcoming APIs.
 In the future, there might be also a JAVA-based (other languages welcome) implementation of those libraries.
 
-To communicate updates of passes to Apple devices we need to implement a web service to be contacted by the Apple wallet as a client.
-This is a special case and we will provide a FastAPI application with the library.
+While Google provides a RESTful API to manage passes, Apple uses an approach to provide passes as signed files, generated by the issuer.
+
+For Google we provide a callback handler to receive events from Google and pass them to the event system.
+
+To download and communicate updates of passes to Apple devices we implemented a web service to be contacted by the Apple devices application, such as browser, apps or wallet as a client.
+
+For both, callback handlers and pass-server we will provide a FastAPI applications aside with the libraries.
 
 ## Vendor-neutral Wallet Library
 

source/packages/edutap_wallet_google/tutorials.md

@@ -27,8 +27,6 @@ class_id = f"{os.environ.get('EDUTAP_WALLET_GOOGLE_ISSUER_ID')}.exampleclass01.e
 new_class = api.create(
     "GenericClass",
     {
-        # ids are always consisting of the issuer id as a prefix followed
-        # by a custom postfix, delimited by a dot.
         "id": class_id,
     },
 )
@@ -38,8 +36,7 @@ Now we create a simple Wallet Object based on the freshly created class.
 
 ```python
 
-# if you run the code more than once, you need to change the ID of the object,
-# like by incrementing the number part.
+# if you run the code more than once, you need to change the ID of the object
 object_id = f"{os.environ.get('EDUTAP_WALLET_GOOGLE_ISSUER_ID')}.exampleobject01.edutap_example"
 
 new_object = api.create(

source/packages/index.md

@@ -1,4 +1,6 @@
-# eduTAP Packages Documentation
+# Software Packages
+
+Documentation of the different eduTAP packages.
 
 ```{toctree}
 ---