Copyright © 2022- basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

basebox - User Needs, Software Requirements Specification and Architecture Description

Purpose

This document is used to establish the following specifications:

The User Needs for basebox,
Detailed Software Requirements,
And how the above specifications form the Functional Architecture.

The picture below describes how those specifications interrelate.

The followings aspects were kept in mind when this set of specifications were drafted:

Comply with good engineering practices and regulatory requirements from:
- ISO 13485, 7.2.1 Determination of requirements related to product, 7.3.3 Design and development inputs.
- IEC 62304, 5.2 Software requirements analysis, 5.3 Software Architectural design.
- IEEE Std 830-1998, 4.3 Characteristics of a good SRS (SW Requirements Spec.)
Software requirements and the architecture were developed incrementally, in parallel and in several iterations.
Software architecture and software requirements are aligned. Both refine and implement user needs.
The architecture shall provide the “Big Picture” of the product to be developed which is basebox. It defines which basic functionality is needed by creating functional components and their interfaces rather than explaining how those components shall be implemented.
The architecture shall provide the structural framework for further decomposition and refinement steps as typically done in detailed SW designs or modularization concepts of code.
Define names for the SW-structure and items (IEC 62304, 5.3) of the architecture which shall be used consistently during the design and development of basebox. The SW-items shall be characterized according to their purpose.
The specifications shall be descriptive enough to enable new developers and any 3rd party to understand the functional structure of basebox without further explanations. They shall also follow good practices as stated in IEEE Std 830-1998 IEEE Recommended Practice for Software Requirements.
The document shall support maintenance of basebox.
The architecture shall support the creation of a security threat model including the establishment of security controls.

Note

The architecture cannot state the safety classes of their software items as required by the IEC 62304, since basebox is an Off-The-Shelf (OTS) data base system which is agnostic to its medical use or integration into any Medical Device (refer to Intended Use)

Terms and Definitions

Term	Definition
Auth0	Secure access for everyone (customer, developer, etc.) but not just anyone (hackers). Auth0, is a commercial SaaS OpenID Connect provider. For details refer to: Auth0.com
Authorization	Authorization gives users rights and privileges after identifying, authenticating, and authorizing them. It secures sensitive resources in a system and protects individual users from unauthorized access to their accounts or information (notarize.com).
Identification and Authentication	Identification and Authentication (IA): the process of verifying the identity of a user, process, or device, using specific credentials (e.g., passwords, tokens, biometrics), as a prerequisite for granting access to resources in an IT system (NIST 800-82).
GraphQL	GraphQL is an open-source data query and manipulation language for APIs and a query runtime engine. GraphQL enables declarative data fetching where a client can specify exactly what data it needs from an API. Instead of multiple endpoints that return separate data, a GraphQL server exposes a single endpoint and responds with precisely the data a client asked for.[2] Because a GraphQL server can fetch from separate data sources and present the data in a unified graph, it isn't tied to any specific database or storage engine (excerpted from WIKIPEDIA]. For more specific details refer to: GraphQL.org.
Keycloak	Open-Source Identity and Access Management. For details refer Keycloak.org.
Microservices	A microservice is an executable “micro” server application that handles requests and sends responses. It can be provided by the user and allows the user to extend basebox functionality beyond the features provided by the Application Definition. The user can specify in the Application Definition if a certain operation shall be performed by a microservice. Usage of microservices introduces external risks that are beyond basebox’ control, as the microservice could basically do anything with the data it processes.
PostgreSQL	PostgreSQL is a powerful, open-source object-relational database system with over 35 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance. For details refer to: PostgreSQL.org.
Software Item	Any identifiable part of a computer program (IEC 62304, 3.2.5).
Software system	Integrated collection of Software Items organized to accomplish a specific function or set of functions (IEC 62304, 3.2.7).

User Needs

Three major issues for creating Digital Health solutions were observed in a variety of health delivery organizations which initiated the development of basebox:

Most Digital Health solutions started with time consuming struggles while establishing an effective and efficient DB operational environment.
The operations of the established databases were often faced with performance and security challenges.
The establishment of those Digital health solutions often ignored state-of-the-art Software development methodologies for Medical Device development.

Those major needs or goals lead to the following User Needs specifications:

UN.1

UN.1	The User (or Customer) defines the Data Base.
UN.1.1	The user wants to establish a database for his purpose once in an effective manner to avoid huge development efforts.
UN.1.2.1	The system which shall enable the definition of the customer data base shall:
UN.1.2.1.1	Comprise a user-friendly and effective DB scheme definition format.
UN.1.2.1.2	Create SQL tables output for the creation of the DB and security specifications.
UN.1.2.1.3	Ensure user defined transactions.
UN.1.2.1.4	Allow the integration of 3rd party HTTP services (Microservices).

UN.2

UN.2	The User (or Customer) operates the Data Base efficiently and effectively.
UN.2.1	The user wants to perform queries on the DB management system which was established for his needs as specified in [
UN.2.2	The user wants to perform queries and operations on the DB by using GraphQL.
UN.2.2.1	Those queries shall provide a response within less than 0.2 seconds.
UN.2.2.2	The system shall support concurrent queries.
UN.2.3	The customer wants that the operational system ensures the security of the system.
UN.2.4	The customer wants the operational system to ensure the privacy of the stored personal data according to the General Data Protection Regulation (GDPR).

UN.3

UN.3	The User (or Customer) wants a database system which considers good development and maintenance practices as appropriate for Medical Device Software. Good practice standards and guidance’s are:
UN.3.1	IEC 62304 Medical device software – Software life-cycle processes
UN.3.2	IEC 81001-5-1 Health software and health IT systems safety, effectiveness, and security — Part 5-1: Security — Activities in the product life cycle
UN.3.3	MDCG 2019-16 - Guidance on Cybersecurity for medical devices
UN.3.4	GDPR - General Data Protection Regulation

These user needs lead to a functional architecture for basebox which consists of the following two Software systems:

A: The Database Definition enables the creation of a SQL Data Base. This Software system (according to IEC 62304 nomenclature) is used to establish the application database scheme according to the needs of the customer within a few days. This system also provides security and consistency rules (restrictions) to ensure secure and frictionless operations of the customer defined data base.
B: The Operational Model is where the Customer Operates on the Data Base. It provides the routine operation functionality (queries) including security and privacy for the previously established data base.

Functional Architecture of basebox

The diagram below provides the details of the functional architecture of basebox. The following architectural elements are depicted in the diagram:

Environment: basebox (pink, yellow) vs. customer environment (grey, white)
Interfaces: Data Flow, Configuration Information Flow, User (Inter-)Actions
Software Items: Functional Modules, Configuration files, Database

Software Requirements Aligned with Functional Architecture

The Software requirements in the following two tables refine the User Needs and are aligned with the Functional Architecture of the two Software systems - Database Definition and Database Operation.

Database Definition
User Needs (UN)
UN.1.x - The User (or Customer) defines the Data Base. (refer to section User Needs for the detailed User Needs descriptions)
basebox Software Requirements	Architecture	SW/HW Item Characteristics
[DBDef.1] By using GraphQL in a basic editor the customer developer shall be able to establish a data base by creating a GraphQL Schema file which contains: Database Layout/Structure Identification an Authorization rules Database queries Operational rules Restrictions Microservices	GraphQL Schema File	Interface
[DBDef.2] A complier shall transform the DB definitions from [DBDef.1] in the corresponding outputs as defined in [DBDef.3].	basebox Schema Compiler (bbc)	Functional
[DBDef.3] The Database Application Definition File shall contain: SQL table definitions. Resliver definitions. SQL queries. SQL mutations. Maps of data structures. Compiled authorization rules.	Compiled Application Definition	DB Definition
[DBDef.4] An OTS database shall be used which represents state-of-the art of data base systems to implement the customer specific database according to the specifications in the Application Definition File.	PostgreSQL	DB Requirement
[DBDef.5] The establishment of a customer data base shall be possible within less than a week.	N/A	Performance
[DBDef.6] The compilation of the GraphQL Schema file in the Application File shall take less than 1 minute.	N/A	Performance
[DBDef.7] Performance requirements depend on the application. They start with a common virtual machine with 2 CPU cores, 10GB of hard disk space and 2GB of RAM.	N/A	Performance

Database Operation
User Needs (UN)
UN.2.x - The User (or Customer) operates the Data Base efficiently and effectively. (refer to section User Needs for the detailed User Needs descriptions)
basebox Software Requirements	Architecture	SW/HW Item Characteristics
[DBOps.1] Support different GraphQL Clients: Any Hardware (client), like a PC or cell phone, which supports GraphQL may be used as input device by Customer’s User to create a GraphQL Request. The clients shall support GraphQL Standard. [DBOps.2] The user shall ensure security for its Client. They shall be made aware of their security responsibilities.	Clients	Inteface, Security
Identity Provider (IdP) for Authentication / Authorization		SQ Subsystem
[DBOps.3] The state-of-the-art security services as required in [DBOps.2] shall be implemented with a best-in-class OTS service instead of implementing a proprietary solution. [DBOps.4] The OTS security service shall be comprising the following user and service controls: Identification of User. Authentication of User. Authorization of User (different user roles and their authorities / privileges). User Management (add, delete, and maintain user). Authentication techniques which ensure identity and authorization across the Operation Model.	OpenID Connect Provider (e.g., Keycloak, Auth0)	Security (External Entity)
broker (GraphQL API Server)		SW Subsystem
[DBOps.5] Allow for Concurrent DB Queries: Up to 500 Customer users shall be supported concurrently. The handling of concurrent queries shall not produce any delay greater than 0.5 sec…	actix web HTTPS server	Performance
[DBOps.6] The operational system shall perform authentication checks for the customer Client(s).	Client Authentication	Security
[DBOps.7] Validate GraphQL queries: Every Graph QL DB query shall be validated for syntactical and semantical correctness. The validation criteria are: Syntactical rules: the syntax must be compliant to GraphQL and to basebox-specific directives as laid out in the documentation. Semantical rules: the combination of directives used must be logically sane. GraphQL queries shall be decomposed to limit the complexity to prevent denial of service attacks via query complexity. Complexity of a query is defined as the number of fields it requests; complexity limitation is specified in number of fields. basebox’ default value is currently 25, but it is user configurable.	GraphQL Validation	Functional, Security
[DBOps.8] Verify the authorization for all access.	Client Access Security	Functional Interface
[DBOps.9] The user defined GraphQL Requests shall be executed by the following steps: Decompose GraphQL into operation requests and identifies the target service using the Application Definition. Select service (e.g. data base service, micro-services, etc.). Package operation responses into request response.	Request Processor	Functional, Interface
Database Server: DB Proxy		SQ Subsystem
[DBOps.10] Validation shall be performed for … Access token User permissions … before any [DBOps.11] Operation Requests shall be transformed into SQL queries.	Operation Handler	Functional, Security
[DBOps.11] The Data Base shall retrieve the data according to the SQL queries.	PostgreSQL	DB Functional
[DBOps.13] The query result shall be transformed into a GraphQL Operation Response.	Response Generator	Functional, Interface
Business Logic
[DBOps.14] The operational system shall pass operations to a Microservice as defined in the Application Definition. [DBOps.15] Users which define and integrate Micro Services shall be made aware of any security and performance risks they must consider during the definition and usage of their Micro Service.	Microservice	Interface, Security (External Entity)

Appendix A – Requirements Engineering Practices

The establishment of the basebox requirements follows the recommendations from the “IEEE Std 830-1998 Recommended Practice for Software Requirements” which can be considered being a good practice. A summary of the essentials of the IEEE recommendations is provided here and supplemented by some other characteristics for good practice.

Good Requirements

Good requirements are:

Correct: The relevant stakeholders
- confirm its correctness
- demand that the system must realize the documented requirement completely
- Consistent with system or user requirements
Unambiguous: Its documentation permits only one valid interpretation.
Complete: All significant requirements, whether relating to functionality, performance, design constraints, attributes, or external interfaces are identified. Contains a piece of information that is relevant for some stakeholder.
Consistent: The statements within the requirement: * do not contradict each other * do not contradict other requirements, like higher level system requirements.
Rated: Its relevance and/or its stability have been determined and documented.
Verifiable: The stakeholders can check whether the implemented system fulfils the documented requirement or not. A requirement is verifiable if, and only if, there exists some finite cost-effective process with which a person or machine can check that the software product meets the requirement.
Modifiable: An SRS is modifiable if, and only if, its structure and style are such that any changes to the requirements can be made easily, completely, and consistently while retaining the structure and style.
Traceable: An SRS is traceable if the origin of each of its requirements is clear and if it facilitates the referencing of each requirement in future development or enhancement documentation.
Comprehensible: Its content is easy to comprehend.
Up to date: It reflects the status of the system and the system context.
Atomic: It describes a single, coherent fact.

History

Vers.	Released	Who	Changes
1	23-Oct-2023	basebox	Initial Release of this document.