6.3 Architecture

govstack-cfr architecture related requirements

govstack-cfr-architecture

Architecture cross-functional requirements define the structural constraints that every Building Block must satisfy to participate in a GovStack ecosystem. These requirements enforce autonomy, interface discipline and operational resilience - the properties that make independent Building Blocks composable without creating hidden dependencies between teams, agencies or vendors.

#1 Building Blocks are autonomous (REQUIRED IMMUTABLE AUDITABLE) (previously 5.20)

govstack-cfr-architecture#req-1

Each Building Block is capable of running independently, without requiring other Building Blocks or external data stores. It owns its data, manages its own lifecycle and does not depend on the availability of any peer to function. No shared databases, no shared file systems and no shared memory between Building Blocks. Autonomy enables independent deployment, independent scaling and independent team ownership.

#2 Communicate with other Building Blocks only via API (REQUIRED REPLACEABLE AUDITABLE) (previously 5.3)

govstack-cfr-architecture#req-2

Paraphrased from the Amazon API Mandate: https://api-university.com/blog/the-api-mandate/

1. All BBs 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, are designed from the ground up to be externalizable. That is to say, the team must plan and design the service so the interface is able to be exposed to developers in the outside world. No exceptions.

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

#3 APIs are versioned (RECOMMENDED EXTENSIBLE OBSERVABLE) (previously 5.4)

govstack-cfr-architecture#req-3

Every API uses semantic versioning (see https://semver.org/) to document changes. Breaking changes are deployed on a separate versioned endpoint (e.g. /api/v1 and /api/v2), so that existing consumers are not forced to change when a new version is released. The version identifier is present in the endpoint path or header contract.

#4 APIs are stateless (RECOMMENDED EXTENSIBLE AUDITABLE) (previously 5.14)

govstack-cfr-architecture#req-4

Each API call contains all of the data necessary to complete itself successfully. The server does not rely on stored session state from prior requests to process a new request. Any context needed - authentication tokens, resource identifiers, filters - is passed explicitly with every call.

#5 GET and PUT APIs are idempotent (RECOMMENDED EXTENSIBLE OBSERVABLE) (previously 5.13)

govstack-cfr-architecture#req-5

GET, PUT, HEAD, OPTIONS and TRACE operations return the same result when called multiple times with the same input. POST and DELETE are not expected to be idempotent because they change underlying data. Implementations ensure that repeated safe/idempotent calls produce identical outcomes without additional state mutations.

Reference: https://restfulapi.net/idempotent-rest-apis/

#6 Follows REST API Design Guidelines Part 1 (REQUIRED EXTENSIBLE AUDITABLE) (previously 5.1)

govstack-cfr-architecture#req-6

APIs follow the core principles of the TM Forum REST API Design Guidelines: no PII or session keys in URLs (use POST or request bodies for sensitive data), support for caching and retries, resource identification via URIs, separation between server-internal representation and client-facing representation, self-descriptive messages that include enough information for the receiver to know how to process them. See: TM Forum REST API Design Guidelines.

See: TM Forum REST API Design Guidelines

Some key principles from these design guidelines are as follows:

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

• 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.

#7 Follows REST API Design Guidelines Parts 2-7 (RECOMMENDED REPLACEABLE AUDITABLE) (previously 5.2)

govstack-cfr-architecture#req-7

APIs follow the extended TM Forum REST API Design Guidelines (parts 2 through 7) covering resource manipulation through representations, self-descriptive messages, error handling conventions and additional design rules. Deviations from these guidelines is documented and the replacement still provides a consistent API contract. See: TM Forum REST API Design Guidelines.

See: TM Forum REST API Design Guidelines

#8 User interface and service logic is logically separated (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-architecture#req-8

UI components and backend services interact strictly via APIs. The presentation layer does not contain business rules or direct data store access. The backend does not generate UI markup. This separation allows frontend and backend to evolve on independent release cycles and supports multiple client types against the same service layer.

#9 Databases do not include business logic (RECOMMENDED EXTENSIBLE AUDITABLE) (previously 5.17)

govstack-cfr-architecture#req-9

Triggers, stored procedures and embedded business logic in databases are avoided. All business logic resides in application code or orchestration components where it can be version-controlled, tested and deployed through standard pipelines. Keeping logic out of the database prevents hidden coupling between the data layer and business rules.

#10 Domain Driven Design (DDD) and microservices architectural principles guide the design of components (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-architecture#req-10

Building Blocks follow Domain Driven Design concepts. Each microservice encapsulates a bounded domain of functionality, owns its data and is independently deployable. Service boundaries align with business capabilities, not technical layers. A change to one domain does not require coordinated deployment of another domain.

#11 Designed for asynchronous first (RECOMMENDED EXTENSIBLE AUDITABLE) (previously 5.22)

govstack-cfr-architecture#req-11

Designs support occasional connectivity and low bandwidth by defaulting to asynchronous communication patterns. A Publish/Subscribe pattern can be used to propagate changes, allowing loosely-coupled solutions to be assembled without modifying existing APIs. Synchronous request/response is acceptable where latency requirements demand it, but the architecture does not assume that every downstream service is available at the moment a request is made.

#12 Application is resilient to external system failures (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-architecture#req-12

Failures in one dependency only impact directly related use cases - they do not cascade to the entire application or to unrelated services. Building Blocks implement retry logic, circuit breaker patterns and fallback mechanisms so that a slow or unavailable external system does not bring down the whole Building Block architecture.

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

govstack-cfr-architecture#req-13

Every transaction that crosses multiple services carries a correlation ID that is passed with every request and response in the chain. The correlation ID is generated at the entry point and propagated without modification through all downstream calls. This enables end-to-end tracing of a single operation across Building Block boundaries for debugging, performance analysis and audit purposes.

#14 Use Web Hooks for callbacks (RECOMMENDED REPLACEABLE OBSERVABLE) (previously 5.11)

govstack-cfr-architecture#req-14

When a Building Block needs to notify another system about an event or completion of an asynchronous operation, it uses webhooks - HTTP callbacks to a URL registered by the subscriber. Direct function calls or internal method invocations across Building Block boundaries are not permitted for callback functionality.

#15 Observability and monitoring functionality is implemented (RECOMMENDED EXTENSIBLE OBSERVABLE)

govstack-cfr-architecture#req-15

Building Blocks expose health check endpoints, metrics and logging interfaces that can be consumed by standard monitoring platforms (e.g. Prometheus, Grafana, ELK, OpenTelemetry). Health checks report the operational status of the Building Block and its critical dependencies. Without observability, operators cannot detect degradation, diagnose failures or plan capacity.

#16 Use NTP synchronization (RECOMMENDED REPLACEABLE AUDITABLE) (previously 5.28)

govstack-cfr-architecture#req-16

Where precise timestamps are required, Building Blocks leverage Network Time Protocol (NTP) or an equivalent time synchronization mechanism to align clocks across servers. Accurate time synchronization is necessary for correct ordering of events, reliable log correlation, valid security token expiration and consistent audit trails across distributed services.

#17 APIs follow a published deprecation lifecycle (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-architecture#req-17

When an API version or endpoint is scheduled for removal, the Building Block announces a deprecation timeline and communicates it to consumers through machine-readable signals (e.g. IETF RFC 8594 Sunset header or equivalent).

Deprecated endpoints continue to function for a defined transition period before removal. The deprecation policy and timeline is documented per API version.

Reference: IETF RFC 8594 (https://datatracker.ietf.org/doc/html/rfc8594).

#18 Consumers apply the tolerant reader pattern to received payloads (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-architecture#req-18

When a Building Block receives a payload (API response, event or message), it ignores fields it does not recognize rather than rejecting the entire payload. This allows producers to add new fields without breaking existing consumers and is a precondition for independent evolution of Building Blocks.

Implementations do not fail on unknown properties in JSON or XML payloads unless a strict validation mode is explicitly required by a functional requirement.

Reference: Postel's Law (RFC 761), Google AIP-203.

#19 Asynchronous messages and events follow a published schema (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-architecture#req-19

Every event or message exchanged asynchronously between Building Blocks has a defined and versioned schema that describes its structure, required fields and semantics. Schemas are published and accessible to all consumers before integration.

Changes to event schemas follow the same versioning discipline as synchronous APIs (see architecture requirement #3). Without published schemas, asynchronous channels become undocumented coupling between services.

Reference: CNCF CloudEvents (https://cloudevents.io/), AsyncAPI specification (https://www.asyncapi.com/).