Licensed to be used in conjunction with basebox, only.
basebox - User Needs, Software Requirements Specification and Architecture Description
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.
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
|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 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 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. 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.
|Open-Source Identity and Access Management. For details refer Keycloak.org.
|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 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.
|Any identifiable part of a computer program (IEC 62304, 3.2.5).
|Integrated collection of Software Items organized to accomplish a specific function or set of functions (IEC 62304, 3.2.7).
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:
|The User (or Customer) defines the Data Base.
|The user wants to establish a database for his purpose once in an effective manner to avoid huge development efforts.
|The system which shall enable the definition of the customer data base shall:
|Comprise a user-friendly and effective DB scheme definition format.
|Create SQL tables output for the creation of the DB and security specifications.
|Ensure user defined transactions.
|Allow the integration of 3rd party HTTP services (Microservices).
|The User (or Customer) operates the Data Base efficiently and effectively.
|The user wants to perform queries on the DB management system which was established for his needs as specified in [
|The user wants to perform queries and operations on the DB by using GraphQL.
|Those queries shall provide a response within less than 0.2 seconds.
|The system shall support concurrent queries.
|The customer wants that the operational system ensures the security of the system.
|The customer wants the operational system to ensure the privacy of the stored personal data according to the General Data Protection Regulation (GDPR).
|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:
|IEC 62304 Medical device software – Software life-cycle processes
|IEC 81001-5-1 Health software and health IT systems safety, effectiveness, and security — Part 5-1: Security — Activities in the product life cycle
|MDCG 2019-16 - Guidance on Cybersecurity for medical devices
|GDPR - General Data Protection Regulation
These user needs lead to a functional architecture for basebox which consists of the following two Software systems:
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.
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.
|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
[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:
|GraphQL Schema File
|[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)
|[DBDef.3] The Database Application Definition File shall contain:
|Compiled Application 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.
|[DBDef.5] The establishment of a customer data base shall be possible within less than a week.
|[DBDef.6] The compilation of the GraphQL Schema file in the Application File shall take less than 1 minute.
|[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.
|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
[DBOps.1] Support different GraphQL Clients:
|Identity Provider (IdP) for Authentication / Authorization
[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:
|OpenID Connect Provider (e.g., Keycloak, Auth0)
|Security (External Entity)
|broker (GraphQL API Server)
[DBOps.5] Allow for Concurrent DB Queries:
|actix web HTTPS server
|[DBOps.6] The operational system shall perform authentication checks for the customer Client(s).
[DBOps.7] Validate GraphQL queries:
|[DBOps.8] Verify the authorization for all access.
|Client Access Security
[DBOps.9] The user defined GraphQL Requests shall be executed by the following steps:
|Database Server: DB Proxy
[DBOps.10] Validation shall be performed for …
[DBOps.11] Operation Requests shall be transformed into SQL queries.
|[DBOps.11] The Data Base shall retrieve the data according to the SQL queries.
|[DBOps.13] The query result shall be transformed into a GraphQL Operation Response.
[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.
|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 are:
The relevant stakeholders
- confirm its correctness
- demand that the system must realize the documented requirement completely
- Consistent with system or user requirements
Its documentation permits only one valid interpretation.
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.
The statements within the requirement: * do not contradict each other * do not contradict other requirements, like higher level system requirements.
Its relevance and/or its stability have been determined and documented.
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.
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.
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.
Its content is easy to comprehend.
- Up to date
It reflects the status of the system and the system context.
It describes a single, coherent fact.
|Initial Release of this document.