Developed by Max Carlson, Kristo Vaher, Steve Conrad, Dr. P. S. Ramkumar, Uwe Washer, and Trevor Kensey

As with any software implementation, there are constraints and limitations in the GovStack approach that must be addressed. In any country context, there will be deficiencies that present challenges to any technology implementation. In the context of GovStack, the constraints and deficiencies that may be present must be considered at the outset of any project.

Here is a list of potential deficiencies that may be encountered with high-level descriptions:

Additionally, the Principles for Digital Development are especially relevant when designing for low resource setting. Refer to for information on these Principles.

Each building block specification SHOULD specify mitigations for these issues.

This document is intended to provide guidance for building block working groups and developers of products that will be integrated into a GovStack implementation. It also provides guidlines for implementers and system integrators who are deploying solutions that leverage the GovStack approach. It provides guidelines and principles that should be considered by all building blocks and cross-cutting requirements that must be considered for any GovStack project.

This will accelerate the collaborative development of best-of-breed digital public goods, enhancing efficiency and transparency across the world - especially in low-resource settings.

2.1 GovStack and the Building Blocks Approach

GovStack aims to provide a reference architecture for digital governance software to support sustainable development goals. Rooted in a "Whole-of-Government" approach, the GovStack Framework provides a methodology for leveraging common technology components and infrastructure to more easily create and deploy interoperable digital platforms which can address high-priority use cases across multiple sectors. The guidelines and requirements described in this document provide a framework for the development of digital building blocks oriented toward this goal.

2.2 Criteria for Building Blocks

The following provide criteria and definitions for Building Blocks, developed by organizations whose work is focused around achievement of the Sustainable Development Goals (SDGs).

SDG Digital Investment Framework

The , developed by the International Telecommunication Union (ITU) and the Digital Impact Alliance (DIAL), has formally defined criteria. Building blocks MUST meet the following criteria:

• Reusable software components

• Licensed as open source, proprietary, or freely available with Open Access to data

• Facilitates one or more generic Workflows

• Applicable to multiple SDG Use Cases across multiple sectors

Digital Public Goods Alliance (DPGA)

Additionally, the Digital Public Goods Alliance has created a . In this definition, a building block:

• Refers to software code, platforms, and applications that are interoperable, provide a basic digital service at scale, and can be reused for multiple use cases and contexts.

• Serves as a component of a larger system or stack.

• Can be used to facilitate the delivery of digital public services via functions, which may include registration, scheduling, ID authentication, payment, data administration, and messaging.

"Building blocks can be as simple as a common set of rules or protocols (for example email programs like Simple Mail Transfer Protocol - SMTP), or complex (for example an open-source health information system like the DPG, District Health Information Software - DHIS2)“

Characteristics of building blocks:

• Autonomous: building blocks provide a standalone, reusable service or set of services, they may be composed of many modules/microservices.

• Generic: building blocks are flexible across use cases and sectors.

• Interoperable: building blocks must be able to combine, connect, and interact with other building blocks.

• Iterative evolvability: building blocks can be improved even while being used as part of solutions.

Per the DPGA definition, to be considered a building block, solutions must meet the following technical requirements determined by the GovStack Initiative which includes:

1. Open API, Open API Specifications, Rest API

2. Packaged in a container

3. Include a information mediator where communication flows between services that are not co-located

2.3 Building Blocks

Building blocks are software modules that can be deployed and combined in a standardized manner. Each building block is capable of working independently, but they can be combined to do much more:

Building blocks are composable, interoperable software modules that can be used across a variety of use cases. They are standards-based, open source and designed for scale.

Each Building Block represents, as much as possible, the minimum required functionality (MVP) to do its job. This ensures each Building Block is usable and useful on its own, and easily extensible to support a variety of use cases.

A Building Block is composed of domain-driven microservices, modeled as closely as possible on existing roles and processes. This helps ensure each building block is as useful as possible in the real world.

Building Blocks exchange data using lightweight, human-readable data that can easily be extended where needed. Data models and APIs are described in a lightweight manner that’s human-readable, allowing them to be easily and quickly understood and validated.

2.3.1 Building Blocks and UI/UX

A building block may also be an application which provides re-usable interfaces:

1. An admin-only form builder which facilitates building user interfaces (e.g., select questions to be displayed in a maternal-and-child-health registration process)

2. User interfaces (i.e., forms) which can be used in lieu of individual end-user apps building their own forms (e.g. I’m building a new maternal and child health application; I’d like to use a registration screen flow that’s been pre-built in the registration building block as part of a larger, composed application.)

3. A public API which exposes the critical back-end services performed by this BB (adding a mom to a database; checking for a mom’s enrollment status in a program) to be used (as a microservice) by existing or new applications with legacy/bespoke needs (e.g., i’ve already got a maternal and child health app that the CHWs are using, and I want to send a webhook to the registration BB after a CHW clicks “submit” on our custom form.)

2.4 Cross-Building Block Communication

A building block is only so useful on its own. In practice, building blocks MUST be connected together in a secure, robust, trusted manner that facilitates distributed deployments and communications with existing services.

It is STRONGLY RECOMMENDED that a building block use an information mediator (as described below and in the ) for any communications across the internet. An Information Mediator is not required for communication between building blocks which are co-located. In this case, communication may occur using standard API calls.

2.4.1 Federation and Data Exchange Requirements

Each building block deployment SHOULD use an Information Mediator to federate and communicate with other data consumers and providers, particularly when communicating between services that are not co-located. This ensures the confidentiality, integrity, and interoperability between data exchange parties. An Information Mediator MUST provide the following capabilities:

• address management

• message routing

• access rights management

• organization-level authentication

Refer to the full description of the for more information.

2.4.2 Organizational Model

In order to effectively deploy a software solution using the Information Mediator, several policies and processes will need to be applied. This section briefly describes that organizational processes that must be in place.

First, a central operator will be identified and created. This organization will be responsible for the overall operation of the system, including operations and onboarding new members. Policies and contractual agreements for onboarding need to be created.

Trust services need to be set up internally or procured from third parties, including timestamp and certificate authorities. This provides the necessary infrastructure to support distributed deployments.

Finally, members can be onboarded and provided with access to the Information Mediator and methods to register the services that they provide as well as discover services that are available.

Once agreements are in place, members can deploy new services in a decentralized, distributed manner. Before deploying a new service, the central operator must be notified of any changes to access-rights, including organization and machine-level authentication before it can publish or consume data.

2.4.3 Technical Architecture

This section provides an overview of the technical processes and architecture that must be implemented once the organizational model has been created.

1. A Central Operator is responsible for maintaining a registry of members, the security policies for building blocks and other member instances, a list of trusted certification authorities and a list of trusted time-stamping authorities. The member registry and security policies MUST be exposed to the Information Mediator.

2. Certificate authorities are responsible for issuing and revoking certificates used for securing and ensuring the integrity of federated information systems. Certificate authorities MUST support the Online Certificate Status Protocol (OCSP) so that an Information Mediator can check certificate validity.

3. Time-stamping authorities securely facilitate time stamping of messages. Time stamping authorities MUST support batched time stamping.

2.5 Keywords and Definitions

Within this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in when, and only when, they appear in all capitals, as shown here.

2.5.1 Building Block-specific definitions

The following provides definitions for terms that are used by various building blocks.

Registration: Any approval/license/certificate issued by a public entity as a result of a request/declaration made by a user of the public service. The result of a “registration” is usually a number and/or a document (called certificate, license, permit, authorization, registration, clearance, approval, etc.)

Authentication: This is the technical process of establishing that the credentials (i.e. username, password, biometric etc.) provided by a party (user, system, other) is valid and that the party can be granted basic access to system resources with default access rights. Note that authorization also needs to be applied for a party to access protected resources.

Authorization: This is the technical process of establishing whether or not an authenticated party has rights to access a given protected resource. Access rights can typically be granted or revoked administratively on a read-only and/or read-write and/or execute basis through an administrative provisioning process. Permissions or rights defined for a party typically manifest in an access token that is granted at the time of authentication for the party. Hence the processes of authentication and authorization are intrinsically related.

Workflow Terminology: See more comprehensive descriptions of the workflow terminology in the .

• (Workflow) Activity - a single step in a workflow process.

• (Workflow) Process - a workflow process contains one or many activities.

• (Workflow) Instance - an instance of execution for a workflow process.

7.1 Unicode

Used for encoding text

7.2 ISO8601/UTC

While the following principles are relevant to many technology deployments, when leveraging the GovStack approach it is important to keep these principles in mind during all phases of design, development, and deployment.

4.1 Citizen-Centric

Design of systems should be rooted in the needs of the citizens/users of these platforms. A Citizen-centric technology will include the following attributes:

• Include more information about the lifecycle of building blocks and connecting to existing solutions, e.g. start with adapters, compliance (including testing), certification and beyond based on sandbox/prototyping work

• Explore connecting to existing services

• Expand standards based on those used in wave 1 and wave 2 working group specifications

It is vital that GovStack be able to connect to existing applications. Likewise, existing applications should be able to connect to and utilize GovStack resources as they see fit. This must be done without compromising the easy and secure interoperability provided by the GovStack system.

This section describes a phased approach that existing platforms may use to integrate into a GovStack implementation. These phases are as follows:

• Adaptors

• API Gateways

• Native GovStack implementation

This can be accomplished with Adapters that connect existing applications for use by GovStack and API Gateways that provide secure access to GovStack services for citizens and other applications, including existing applications.

6.1 Adapters

Adapters connect GovStack building blocks to existing applications. There are many possible flavors of adapter, e.g. HL7 2.5, HL7 3.0, FHIR, SAP SOAP, SQL and many others. Each flavor can be quickly configured to give GovStack access to existing resources.

An adapter is used to translate an existing API that is provided by the application into a format that is consistent with the API definitions that are defined in the Building Block specifications. Adapters are responsible for data and protocol translation, authentication, and filtering and aggregation logic. They publish an OpenAPI specification so they can be used by any building block.

Here we can see two adapters, one for patient records and another for a tax registry:

In this example, a registry adapter configured to map HL7 2.5 data connects an existing application’s patient record registry to a GovStack implementation. Another registry adapter providing SAP SOAP mapping connects an existing applications tax registry to GovStack. Both adapters provide services that are available for use by other building blocks.

If an existing application sends events, they should be exposed as web hooks in the adapter’s OpenAPI specification like other APIs. This allows any GovStack building block to be notified when the event occurs.

6.2 API Gateways

API gateways connect citizens and existing applications to GovStack Building Blocks. The API gateways map outbound API calls from the application into API calls that will be used and understood by the GovStack Building Blocks. Here, a public API gateway provides GovStack resources to citizens, while a private API gateway provides GovStack resources to existing applications:

In this example, a hospital information management system can use the Citizen ID/Authorization Building Block to authenticate a patient’s foundational ID. Likewise, citizens access government services via external mobile or web applications calling through a shared public API gateway.

Any number of API gateways can be added to expose various GovStack services to users or external applications, each of which have different security requirements on the information mediator and public internet/API Gateway sides.

6.3 Native GovStack Implementation

The highest level of integration involves existing products implementing APIs that can be directly consumed by other GovStack Building Blocks. The following diagram shows a complete GovStack deployment with API gateways for citizen access via web or mobile and for existing applications to be able to call GovStack APIs on demand. The workflow building block is used as an adapter, exposing existing applications as GovStack resources via OpenAPI:

Here, citizens and existing applications are provided API access for requests into GovStack via a common API Gateway, while the workflow Building Block adapter provides outgoing API access to existing applications from GovStack Building Blocks.

Building blocks are responsible for meeting all cross-cutting requirements or specifying why specific requirements do not apply. Govstack compliance and certification processes will validate these requirements.

5.1 Follow TM Forum Specification REST API Design Guidelines Part 1 (REQUIRED)

See: TM Forum REST API Design Guidelines

Some key principles from these design guidelines are as follows:

• APIs MUST not include Personally Identifiable Information (PII) or session keys in URLs - use POST or other methods for this

• MUST support caching/retries

• Resource identification in requests Individual resources are identified in requests, for example using in RESTful Web services. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server could send data from its database as , or as —none of which are the server's internal representation.

• Resource manipulation through representations. When a client holds a representation of a resource, including any attached, it has enough information to modify or delete the resource's state.

• Self-descriptive messages Each message includes enough information to describe how to process the message. For example, which parser to invoke can be specified by a .

5.2 Follow TM Forum Specification REST API Design Guidelines Parts 2-7 (RECOMMENDED)

See:

5.3 Communicate with other BBs only via API (REQUIRED)

Paraphrased from the Amazon API Mandate:

1. All BBs must expose their data and functionality through service interfaces (APIs).

2. Building Blocks communicate with each other through these interfaces.

3. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team’s data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.

Building blocks MUST NOT use shared databases, file systems or memory for data exchange with other building blocks.

5.4 APIs must be Versioned (REQUIRED)

Use semantic versioning when documenting changes to API definitions. Any breaking changes to APIs MUST use a different endpoint, as shown here: e.g. /api/v1 and /api/v2

See

5.5 Documentation must be Provided (REQUIRED)

Documentation on the installation and use of the Building Block MUST be provided. Where possible, this documentation SHOULD be stored alongside code in a repository. Documentation MAY be generated from code where applicable.

5.6 Provide an OpenAPI specification (REQUIRED)

Each building block’s service APIs MUST be defined and exposed using a standardized machine-readable language. External APIs are described using the OpenAPI 3.x specification. See the following resources for additional information:

5.7 Building blocks must be deployable as a container (REQUIRED)

• Each building block MUST be ready to be deployed as independent container images. Source code and build instructions SHOULD be committed to a public code repository where possible.

• A building block may be composed with Kubernetes or docker compose. All build files must be included alongside the source code.

5.8 Include all deployment scripts (RECOMMENDED)

When a building block requires deployment tools such as Kubernetes or Ansible, configuration and deployment scripts should be included in the building block repository. Use of this type of deployment configuration will make individual components of the building block independently scalable and make building blocks less monolithic and more efficient.

5.9 Comply with GDPR Principles (REQUIRED)

Building Blocks MUST conform to GDPR principles, including the right to be forgotten account deletion, and privacy requirements to protect the rights of individuals. Note that these requirements may vary by region, and building blocks must conform to regulatory requirements wherever they are deployed.

5.10 Include Support for Capturing Logging information (REQUIRED)

Building Blocks MUST have a mechanism for generating logging information. This may be as simple as using STDOUT and capturing through docker logs, or may use other log sinking technologies.

5.11 Use Web Hooks for Callbacks (REQUIRED)

When Building Blocks require callback functionality, they must use webhooks and not direct links to functions within the building block.

5.12 Enforce Transport Security (REQUIRED)

All Building Blocks MUST support secure HTTPS transport with TLS 1.3 and insecure cyphers disabled.

5.13 GET and PUT APIs must be Idempotent (REQUIRED)

GET and PUT APIs (as well as HEAD, OPTIONS, and TRACE) must be idempotent, returning the same value if called multiple times. POST and DELETE APIs will not be idempotent as they change the underlying data. Reference for more information.

5.14 Use Stateless APIs wherever Possible to Enhance Scalability (RECOMMENDED)

API calls SHOULD be able to be made independently of one another. Each API call should contains all of the data necessary to complete itself successfully.

5.15 Include Transaction/Trace/Correlation IDs (RECOMMENDED)

Transactions that cross multiple services SHOULD provide a correlation ID that is passed with every request and response. This allows for easier tracing and tracking of a specific transaction.

5.16 Include Clearly-Defined Key Rotation Policies (RECOMMENDED)

Some blocks may require the use of security keys. Those that do must have clearly defined key rotation policies to enhance security

5.17 Databases should not Include Business Logic (RECOMMENDED)

Database processing tools like triggers and stored procedures should be avoided.

5.18 Use only Unicode for Text (REQUIRED)

5.19 Use ISO8601/UTC for Timestamps (REQUIRED)

5.20 Building Blocks must be Autonomous (REQUIRED)

Each building block MUST be capable of running independently, without requiring other dependencies such as external data stores or other building blocks.

5.21 Use Secure Configuration (REQUIRED)

Configuration MUST be done using secure processes, such as environment variables or a secure secret store.

5.22 Design for Asynchronous First (RECOMMENDED)

Designs should support occasional connectivity/low bandwidth, and should allow for asynchronous communication between building blocks. A Publish/Subscribe design pattern can be used to handle changes, allowing loosely-coupled solutions to be assembled without changing existing APIs.

5.23 Use Standardized Data Formats for Interchange (REQUIRED)

JSON SHOULD be used for data models/services wherever possible. See . Where JSON exhange is not possible, building blocks must use other standard data formats (such as XML).

5.24 Use Existing Standards for Data Interchange, Where Available (RECOMMENDED)

If an existing standard is available, it should be used, e.g. DICOM/Hl7/FHIR for healthcare. TMForum has a large library of standardized APIs and data models that can be used.

Building blocks and building block solutions MUST leverage existing standards, especially those listed in the below.

5.25 Use I/O Sanitization (RECOMMENDED)

Building blocks SHOULD validate all incoming data to ensure that it conforms with the expected format and type. APIs should also sanitize incoming data, removing any unsafe characters or tokens.

5.26 Provide a Compliance Test Mock/Example Implementation (OPTIONAL)

A building block MAY provide a mock testing implementation of API functionality to show example endpoints and data payloads. See for additional information.

5.27 Building blocks should be Localizable (RECOMMENDED)

Where a building block has a human user interaction, it SHOULD be able to present information to the user in their local language. Building blocks should be designed to support multiple locales.

5.28 Use NTP Synchronization (RECOMMENDED)

Where precise timestamps are required, building blocks SHOULD leverage Network Time Protocol (NTP) to synchronize timestamps between servers.

Other Considerations

Software development best practices are recommended for all building blocks. The following guidelines should be followed as part of the software development process.

EOL SHOULD be at Least 5 Years

No languages, frameworks, or dependencies should be used in a building block where that component has an EOL of less than 5 years.

Preference for TIOBE Top 25 Languages

See

Where possible, building blocks SHOULD be written using commonly used languages to ensure ongoing maintenance and support are as easy as possible. Building blocks MAY leverage less common languages, such as shell scripting where needed.

Regular Security and Code Quality Audits SHOULD be Run

These should be run across the code base and dependencies, e.g. and/or .

SHOULD Include Unit and Integration Test Coverage

Building blocks should include tests that provide both unit and integration test coverage

SHOULD Follow Best Practices for Public Code

See and practices outlined here: