>>>>> gd2md-html alert: ERRORs: 0; WARNINGs: 1; ALERTS: 4.
- See top comment block for details on ERRORs and WARNINGs.
- In the converted Markdown or HTML, search for inline alerts that start with >>>>> gd2md-html alert: for specific instances that need correction.
Links to alert messages:
alert1 alert2 alert3 alert4>>>>> PLEASE check and correct alert issues and delete this message and the inline alerts.
natPass
High Level Design Document
Version 0.1
2025/03/17
Introduction
natPass is a system for the retrieval of user information given a user ID, the comparison between user information and some list of specifications, and the printing of the user information onto a badge printer at the location where the user entered their ID.
This High-Level Design (HLD) document serves to document and describe the general mechanisms of and communications between systems comprising the natPass project. The HLD is critical in ensuring the ease of onboarding new developers, as well as serving as a reference for developers. In software development, two or more developers will design different solutions to the same problem – this document should serve to complete that work beforehand, unifying the work of a team. More than a reference, this document serves as a log of decisions and underlying rationale of the software architecture’s elements, relationships, and properties.
This document is particularly helpful in the layout of a system such as natPass, which requires the client device, the web client composed of its own layers, the backend which queues prints, the user databases, the badge printers themselves, interactions with other departments and units under NAT, such as natPortal, inventory management, events department; in summary, the natPass system with many modular and moving parts needs to be thought out beforehand, and needs to provide a high level overview to all persons involved in the natPass project.
Scope of this document
This document’s scope is to briefly describe the required devices, as well as the required software for each respective device. The whole system will be described at the highest level. The function of each component of the system which the natPass project is responsible for developing will be briefly detailed at the architecture level. Lower-level design will be described in documents describing lower-level functionality of their respective modules. Descriptions in this document provide a standard – but not inflexible model for development.
Table of Contents
[TOC]
List of Figures
List of Tables
Add space after paragraph
List of Acronyms/Abbreviations/Terminology
| API | Application Programming Interface |
| GUI | Graphical User Interface |
| nUID | nat Unique IDentifier; NAT implementation of UUIDv4. The encoding of the 64-bit data to 62 bits allows it to fit onto a smaller QR Code. |
| NAT | Name AwaiTing (new name soon?) |
| REST | REpresentational State Transfer; an architecture for designing APIs |
| USB | Universal Serial Bus |
- High-level Overview
Figure 1 is the highest-level abstract block diagram illustrating the high-level interactions between the components of natPass as well as interactions with external dependencies of natPass.
>>>>> gd2md-html alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>
Fig 1. Highest-level abstract diagram of natPass and services natPass interacts with. Development of the above components enclosed in the selection “natPass System” are the primary responsibility of the natPass team.
1. External Services
natPass relies on the external services natPortal and a database, both managed directly by NAT and its staff.
1.
natPortal
1. nUID
natPortal is NAT’s event and learning management system, acting as a public-facing central hub for all of NAT’s services. Each user of natPortal has a nUID, uniquely identifying the user. natPortal provides each user’s nUID as a QR code, which may be scanned at an event for purposes of identification. To natPass, the identification provided by the QR code retrieves the relevant user data, in addition to registration data (1.1.1.2).
2. Registration data
A natPortal user may register for an event by filling in a form on natPortal, providing registration data related to the event. The registration data, now stored in the database under an event-specific table, can be accessed by the nUID identifying that natPortal user.
2.
Databases natPass relies on some database to retrieve user data, retrieve event data, and compare user data to event data. Due to this simplicity, natPass is inherently highly adaptable to any API and storage. At present, NAT infrastructure relies on 3 sources of data:
3. PostgresQL
A database containing the data of natPortal users. Each user entry contains a relation to a list of events which the user has registered and enrolled in. natPortal relies on Strapi APIs to access data on the PostgresQL database.
This database’s server also includes a database for a Moodle instance (in development).
4. Baserow
A no-code relational database displaying form registration data as a spreadsheet, in addition to NAT administrative data. NAT prefers Baserow for its intuitive graphical interface, allowing less technical staff to modify and read data. natPortal relies on Baserow’s REST APIs to store users’ event registrations, but does not read user or registration data from Baserow [3].
5. Budibase
A no-code workflow automation platform which uses CouchDB (non-relational) natively. However, Budibase will be used as an interface to a MongoDB instance. Similar to Baserow, it allows a spreadsheet-view for data. Budibase has not yet been integrated with natPortal or any other NAT infrastructure. NAT will rely on Budibase’s provided form features to automate registrations, minimizing developer workload.
2.
Use Sequence and Architecture When the natPass web client successfully retrieves data from the database using the nUID, the comparison with the user data and event data is displayed to the natPass web client. If the data comparison satisfies the event requirements, the user of the natPass web client can request a badge print, which sends the badge data from the web client to the backend server. The backend server relays the badge data to a badge printing arrangement. The described sequence is illustrated below in Fig. 2.
>>>>> gd2md-html alert: inline image link here (to images/image3.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>
Fig 2. A sequence diagram of the user data check function and badge printing function. Note: “Authorized natPass user” would refer to a badge printing kiosk or event staff, or some agent otherwise permitted to view user data and initiate badge printing.
Note that in this current diagram, communications with the backend are completely synchronous. In future versions of natPass, communications will be asynchronous, returning the result of data requests and print requests to a callback, allowing the user to request multiple tasks and allow the natPass system to handle them simultaneously.
The natPass web client will be responsible for strictly display logic. The natPass web client will have no direct interaction with either the database APIs or the natPass printer arrangement. In consideration of information security, the natPass web client will only receive abstracted boolean checks from the natPass backend. In addition, the badge printer arrangement will only receive the minimal data required to print a badge.
natPass’ architecture most closely follows a loosely coupled message-driven architecture. The natPass system, without consideration of its interactions with natPortal, consists of three individual components. The purpose of having these components divided into three is to improve ease of modification and scalability by separating the database, logic [1.3], GUI [1.4], and printing [1.5], and reducing each component to its interactions, rather than mechanisms (i.e. external, rather than internal). The interactions between the components of the natPass system are described below.
>>>>> gd2md-html alert: inline image link here (to images/image4.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>
Fig. 3. A basic communication diagram of the natPass system without other NAT infrastructure such as natPortal.
3. Backend server
The backend server is the integration layer responsible for the logic and control of the whole natPass system.
Prior to and during the usage of natPass, printer controllers must be authorized and configured to securely receive data. In addition, users must use the web GUI to authenticate themselves, authorizing them to request user data and print jobs. The backend program handles both authorization cases with similar logic, as the persons setting up printer arrangements will usually be the same persons using the web GUI to request prints.
During the usage of natPass, the backend server performs the load balancing of print jobs by enqueuing requests and sending print commands to host machines. natPass’ backend server will receive print requests from the web client. When the backend server receives print requests from the web client, the backend server will enqueue print requests from the web client. natPass’ backend server will dequeue print requests once the print has been confirmed by host machine endpoints. The backend server reports the status of the print to the web client which made the request.
The backend server is responsible for:
3. Registering new printer devices
4. Authorizing printer devices to receive print jobs
5. Authorizing web client tokens for printing and fetching data
6. Enqueuing print jobs when requests are received
7. Dequeuing requests when print jobs are sent
8. Reporting the pending print job’s status to the web client
9. Making and caching requests to a database API for user, event, and registration data
For efficiency, data from the database will be cached on the natPass backend. Five options are proposed:
6. the check result is cached for that nUID (liable to event checks/event data/attendee data changing)
7. the check is performed on cached attendee and event data (liable to event data/attendee data changing)
8. the check is performed on newly requested attendee data and cached event data (liable to event data changing)
9. the check is performed on newly requested attendee data and newly requested event data
10. the database API performs its own checks on the user data with its own functions
Under the assumptions that:
11. NAT infrastructure, including databases and their APIs are presently subject to rapid change, therefore the design is unstable
12. Attendees, especially those who cannot enter due to failed registration checks, may register or modify their registration at the time of the event
13. Event requirements are not prone to change during an event
14. Event registration fields are not prone to change during an event
Caching will follow the proposition in 1.3.7.3, that the backend server will cache event data, but not attendee data. Upon stabilization of NAT database infrastructure, it is recommended that 1.3.7.6 be modified, and the approach follow the proposition in 1.3.7.5.
4. Web client
Using an nUID as a unique key, the web client requests and displays attendee registration data from the backend. The data associated with the nUID is compared with a stored checklist, like a test. The non-privacy-sensitive data and the boolean checklist results are displayed to the GUI. The user of the web client can then request to send the data to the backend server and initiate a print. The web client will continuously report the print’s status (pending, failed, success, etc.).
The web client should be strictly relegated to displaying the data returned from the backend. Sensitive attendee data should never be accessible by the web client.
The web client is responsible for:
10. Authenticating a user to the backend
11. Making data requests from the backend server
12. Making print requests to the backend server
13. Displaying eligibility of attendee based on checklist
14. Receiving and displaying requested print status
5. Printer arrangement
The printer arrangement and its associated software consists of some controller device (laptop, computer, or otherwise) connected to one or more label printers. The printer arrangement relies on the open source brother_ql-inventree Python library to send images to the label printer, and is therefore compatible with a limited set of models made by Brother [1]. Communications from the backend server do not go to the label printer directly, but to the controller device.
“Badge” and “Label” may be used interchangeably, however, within this document, “Badge” refers to the product of the label printer, while “label” functions to describe the type of printer, as well as the label tape fed to the label printer.
15. Controller device/Host Machine
The controller device or host machine, is an internet-capable machine running Linux, Windows, or macOS capable of interfacing with the printer device through a USB port.
Software running on the host machine will:
15. Identify connected printers including printer model and specifications
16. Register the controller device to the backend server
17. Subscribe to the label printer’s status topic
18. Report the printer arrangement’s status to the backend server
19. Receive badge print requests from the backend server
20. Create badge images from the request data, with respect to printer and specified label specifications
21. Send badge images to the printer
22. Deregister the controller device from the backend server on program termination
Software running on the host machine relies on Python 3.13 with the libraries:
23. pillow
24. Flask
25. brother_ql-inventree
26. pytest
Development will use the uv package manager. Releases will provide a uv Dockerfile for ease of deployment.
16. Label printer
The printer device is a Brother laser label printer. The brother_ql-inventree library’s README.md provides a list of compatible laser printers. Specifications of each model are provided in the brother_ql-inventree library [1, located at /brother_ql/models.py], as well as on the manufacturer’s support site [2]. The printer device requires access to a compatible power outlet, depending on the model’s region. The printer device is connected to the controller device through a USB-B cable capable of data transmission.
The printer device will:
27. Report its model to the controller device
28. Report its status including errors and pending print status to the controller device
29. Receive print request containing an image
30. Print and cut a label
In addition, the printer device requires these considerations regarding compatibility with labels fed to the printer:
1. By default, printer devices will print at 300 DPI. Some printers are capable of printing at 600 DPI. To use the higher quality option, the high-quality option must be specified by the controller.
2. By default, the printer cuts the label once the image is fully printed to the label. This can be disabled in the print command. Die-cut labels are pre-cut, so the image sent to the printer must be manually rearranged to fit the label’s constraints.
3. By default, the printer only uses the colour black. Some labels are capable of both black and red. If using a label capable of both black and red, the controller device must specify to the printer that the label is black/red.
2. Communications Communications between the web GUI and printer arrangements use secured HTTP proxied through NGINX on the remote server. At a larger scale, we recommend that communications between printer endpoints and the backend use gRPC. Communications with external APIs such as natPortal and the implemented databases containing registration data use REST APIs. Routes for each component are described in the prior section.
6.
-
Event Logging
As the central integration between data and model, the backend server will handle the bulk of logging. A thread separate from the main backend process will handle the storage of logs.
Due to the simplicity of the printer endpoint program, logs will only be stored when the program is explicitly configured to store logs. Stored logs may be accessed directly from the controller device for debugging.
Image generation logging will use the format:
LEVEL: DD/MM/YY Module Message
Endpoint activity logging will use the format:
RequestOrigin [DD/MM/YY HH:MM:SS] Message HttpStatus
References
[1] https://github.com/matmair/brother_ql-inventree
[2] https://support.brother.com/g/b/productseries.aspx?c=ca&lang=en&pcatid=37
[4] https://docs.budibase.com/docs/mongodb
Document Authentication
Reviewers
| Name | Role | Signature | Date |
Record of Document Changes
| Version | Date | Author(s) | Description of Changes |