6.3 Architecture

govstack-cfr-architecture 2.0.0

#1 Building Blocks must be Autonomous (REQUIRED IMMUTABLE) (previously 5.20)

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

#2 Communicate with other BBs only via API (REQUIRED REPLACEABLE) (previously 5.3)

Paraphrased from the Amazon API Mandate: https://api-university.com/blog/the-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.

4. It doesn’t matter what technology is used. HTTP, Corba, Pubsub, custom protocols — doesn’t matter. Technology choice (HTTP, Pub/Sub, gRPC, etc.) is flexible, but the API contract is immutable.

5. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.

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

#3 APIs must be Versioned (REQUIRED EXTENSIBLE) (previously 5.4)

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 https://semver.org/

#4 GET and PUT APIs must be Idempotent (REQUIRED EXTENSIBLE) (previously 5.13)

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 https://restfulapi.net/idempotent-rest-apis/ for more information.

#5 Follow TM Forum Specification REST API Design Guidelines Part 1 (REQUIRED EXTENSIBLE) (previously 5.1)

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 URIs 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 HTML, XML or as JSON—none of which are the server's internal representation.

• Resource manipulation through representations. When a client holds a representation of a resource, including any metadata 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 media type.

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

See: TM Forum REST API Design Guidelines

#7 Databases should not Include Business Logic (RECOMMENDED IMMUTABLE) (previously 5.17)

Triggers, stored procedures, and embedded business logic in databases are avoided.

#8 Design for Asynchronous First (RECOMMENDED EXTENSIBLE) (previously 5.22)

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.

#9 Use Stateless APIs to Enhance Scalability (RECOMMENDED EXTENSIBLE) (previously 5.14)

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.

#10 Include Transaction/Trace/Correlation IDs (RECOMMENDED EXTENSIBLE) (previously 5.15)

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.

#11 Use Web Hooks for Callbacks (RECOMMENDED REPLACEABLE) (previously 5.11)

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

#12 Use NTP Synchronization (RECOMMENDED REPLACEABLE) (previously 5.28)

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

#13 Cloud-native readiness is applied: applications are scriptable to deploy and recover, consist of independent instances, and support automated scaling and high availability. (RECOMMENDED EXTENSIBLE)

Applications support scripted deployment, recovery, independent instances, automated scaling, and high availability.

#14 User interface and service logic is logically separated and interact over APIs. (RECOMMENDED EXTENSIBLE)

UI and backend services interact strictly via APIs.

#15 Domain Driven Design (DDD) and microservices architectural principles guide the design and implementation of all new applications. (RECOMMENDED EXTENSIBLE)

New applications follow DDD concepts. Microservices encapsulate domain functionality and is independently deployable.

#16 Applications is resilient to external system failures. Failures in one dependency should only impact directly related use cases, not the entire application. (RECOMMENDED EXTENSIBLE)

Failures in one dependency cannot cascade to unrelated services. Applications implement retry, circuit breaker, and fallback mechanisms.

#17 Observability & Monitoring (RECOMMENDED EXTENSIBLE)

Building blocks expose metrics, health checks, and logging endpoints. They can be integrated with monitoring platforms (Prometheus, Grafana, ELK, OpenTelemetry).