restructurt

source/architecture/core/event-system.md

@@ -0,0 +1,21 @@
+# Architecture of the Event system
+
+The event system handles data generated by the creation and usage of passes.
+It works asynchronously by producing the data as an event and providing it in a message queue.
+It then can be read by one or more consumers to be further processed, like being stored in a third-party system.
+
+```{todo}
+add a mermaid diagram to illustrate the flow
+```
+
+The event system in its core
+
+1. takes information from callback services or other producers,
+1. stores the information temporarily in a message queue
+1. information gets consumed and is further processed
+
+Examples of types of information handled:
+- applications for passes and updates to those applications (common identity pass/ service pass)
+- pass creation/ update from vendors via callbacks
+- handle data generated by MaSA, like a check-in to an event.
+

source/architecture/core/index.md

@@ -0,0 +1,39 @@
+# Architecture of the eduTAP Core
+
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+
+wallet-specific-api-libraries-and-support-services.md
+semantic-pass-api.md
+pass-management.md
+event-system.md
+
+```
+
+The eduTAP Core is a collection of components to create, issue, and manage passes.
+
+It provides generic components to be used and installed at the {term}`HEIs<HEI>`, but does not contain parts specific to the software and databases used at the institutions. Latter are part of the eduTAP {term}`MaSAs<MaSA>`.
+
+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 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.
+    It can be configured to define which {term}`pass classes <pass class>` are to be managed.
+
+
+```{figure} ../uml/core.svg
+:alt: Component diagram showing architectural overview.
+
+Core Overview.
+```

source/architecture/core/pass-management.md

@@ -0,0 +1,51 @@
+# Architecture of Pass Management
+
+Pass management is the task, of creating and designing passes and then offering those passes to potential users, here called tappers.
+
+There are different types of organizations intended to be using this service:
+- HEIs
+- Specific service providers like
+  - Student unions (cantinas, cafes, vending machines, housing/dorms, ...)
+  - Libraries
+  - Inter-institutional service providers, like educational sporting facilities
+
+Use cases in the domain of pass management are:
+
+- An admin creates (designs) new and manages existing pass classes.
+- A tapper applies for a pass, then
+  - manage the application cycle and reject or issue the pass (like for a common ID pass),
+  - immediate issuing of a pass (like for a service pass).
+- A tapper downloads their passes to their device.
+- A tapper manages their passes.
+- A manager manages the tappers' passes.
+- A manager sends notifications to whole pass classes or a single pass.
+
+```{figure} pass-management.png
+:alt: Use case diagram showing the pass management roles and actions.
+
+Pass management use-case.
+
+```
+- A *Tapper* is a person who uses the offers of the providers with their smartphone and the passports stored in it using the reader terminal.
+- A *Manager* - is a person who has the role of supporting the tapper with applications and passes.
+- An *Administrator* is a person who manages pass classes.
+
+The application is divided into two main, but interconnected areas:
+
+1. a back office for administrators and managers.
+1. a tapper portal for the holders of passes.
+
+Technically it consists of two web-application backends, each a RESTful API offering the functionality for the task.
+The reason is better scalability.
+While the back office is used only by a small group of staffers, the tapper portal is accessed by up to several 10 thousand tappers at one organization.
+Thus the tapper portal needs the ability to scale horizontally on a different level than the back office.
+
+Each, the back office and the tapper portal, has a management front-end provided as a JS application.
+
+Both are offered as white-label applications with the ability to change the logo or CSS by the organization installing the apps.
+
+Some organizations may decide to integrate the tapper portal part only into their existing portals.
+In this case, the RESTFul API alone can be used to fulfill the task.
+
+Both, the back office and tapper portal need a kiosk mode.
+A kiosk has an NFC device and offers direct interaction with the tapper's device to also write passes to the phone.

source/architecture/semanticmodel.md → source/architecture/core/semantic-pass-api.md

@@ -1,9 +1,9 @@
-# Semantic Pass Models
+# Architecture of the Semantic Pass API
 
 ## Overview
 
-Here we provide semantic pass models primarily vendor-neutral.
-There is no direct one-to-one mapping from semantic pass models to vendor-specific pass models, because of differences between different vendors with their proprietary pass models.
+Here we provide semantic pass schemas and possible definitions, primarily vendor-neutral.
+There is no direct one-to-one mapping from semantic pass definitions to vendor-specific pass models, because of differences between different vendors with their proprietary pass models.
 
 [mapping between existing vendor pass models](https://notificare.com/blog/2023/02/17/how-to-create-digital-passes-for-all/)
 
@@ -54,7 +54,7 @@ The differentiation into Pass Class and Pass Object as its done as Google is not
 Apple follows a different approach to habdle passes.
 Apple contains only passes stored in a `*.pkpass` file which is a .zip file with checksums and a manifest signed by certificates to make it manipulation-safe.
 
-However, to work efficiently with passes, internally at eduTAP we decided to introduce pass templates differentiate between them and and passes as well.
+However, to work efficiently with passes, internally at eduTAP we decided to introduce pass templates to distinguish between them and and passes as well.
 We have:
 
 - Pass Template: a pass definition that can be used to create a pass object by copy and modify.

source/architecture/core/wallet-specific-api-libraries-and-support-services.md

@@ -0,0 +1,51 @@
+# Architecture of Wallet specific API Libraries and support services
+
+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.
+
+It is planned to support the following vendors
+
+- [Apple](https://www.apple.com/wallet/)
+- [Google](https://wallet.google/)
+- HCE vendors ([NXP](https://www.nxp.com/products/rfid-nfc:RFID-NFC), [Legic](https://www.legic.com/partners-services/wallet-program))
+- [EU Digital Identity Wallet](https://eudiwalletconsortium.org/)
+- [openWallet Foundation](https://openwallet.foundation/)
+
+Each vendor works conceptional 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.
+
+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 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.
+There will be a Python package for each vendor, at first:
+
+- `edutap.wallet_google`
+- `edutap.wallet_apple`
+
+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.
+
+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.

source/architecture/index.md

@@ -24,9 +24,8 @@ maxdepth: 2
 caption: Contents
 ---
 
-core.md
+core/index.md
 servicedirectory.md
 masas.md
 infrastructure.md
-semanticmodel.md
 ```

source/glossary.md

@@ -115,4 +115,8 @@ Tapper
 Provider
     an organization who provides offers for {term}`tappers<Tapper>` on site using reading terminals and connected technology.
 
-`````
+MaSA
+    *Ma*ndant *S*pecific *A*pplication
+
+
+```