> For the complete documentation index, see [llms.txt](https://specs.govstack.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://specs.govstack.global/architecture/4-interoperability-architecture/4.2-functionality-design.md). # 4.2 Functionality Design Architecture defines how systems connect and operate. Functionality design defines what those systems actually do. For interoperable government services to work across institutions and vendors, business rules and service behaviour must be described in a way that both **policy experts and engineers understand the same way**. If the functional meaning of a service is unclear, technical interoperability alone does not produce good results. Functionality design therefore focuses on three practical goals: * describing the **domain and business rules** clearly * expressing **service behaviour and use cases** in a shared language * validating that implementations behave as expected through **automated tests** The approaches described below help ensure that functional behaviour remains consistent even when different vendors implement the same Building Block or service application. These methods are not mandatory but are strongly recommended for projects implementing GovStack approach. #### 4.2.1 Domain Driven Design (DDD) Domain Driven Design organizes software around the real-world domain it serves. Instead of structuring systems purely around technical layers, functionality is modeled around areas of government responsibility such as identity, licensing, civil registry or payments. The starting point is understanding the real processes and terminology and their integration points. These terms form a shared language used across documentation, APIs, data models and software implementation. When a term such as *registration*, *permit* or *citizen record* is used, it should mean the same thing across the entire system. Large domains are typically divided into smaller areas with clear responsibility. Each area manages its own rules and data, which helps reduce confusion and allows systems to evolve independently. Domain Driven Design usually relies on three practical concepts: * **Ubiquitous language** - shared terminology used consistently across teams and systems * **Bounded contexts** - clearly separated functional areas with defined responsibilities * **Domain events** - explicit representation of important real-world events such as a birth registration or business creation Using this approach helps ensure that Building Blocks reflect real government processes instead of arbitrary technical structures. *More:* [*https://en.wikipedia.org/wiki/Domain-driven\_design*](https://en.wikipedia.org/wiki/Domain-driven_design) #### 4.2.2 Behavior Driven Development (BDD) Behavior Driven Development describes how a system should behave from the user's perspective. Instead of focusing on technical implementation, the system is described through simple scenarios that explain how the service should respond to actions. A typical scenario describes three parts: ``` Given a citizen submits a birth registration When the civil registry validates the information Then a birth record is created ``` These scenarios describe observable behavior. They explain what must happen, not how the system is implemented internally. This allows policy experts, architects and engineers to discuss the same functional behavior using a common language (and shared language is key for interoperable services as well as development). These behavior scenarios serve as a bridge between service design and system implementation. They clarify the expected outcome of a service before development begins and provide a concrete "feature scenario" reference for implementation. In practice, these scenarios often represent common government service flows such as: * registering a birth or death * issuing a permit or license * updating an address or identity record By documenting behavior this way, teams can validate that different system implementations follow the same service logic. *More:* [*https://en.wikipedia.org/wiki/Behavior-driven\_development*](https://en.wikipedia.org/wiki/Behavior-driven_development) #### 4.2.3 Testing and Executable Specifications Functional descriptions should not remain only documentation. Tools such as Cucumber allow behavior scenarios written in the Gherkin language (see 4.2.2) to be executed as automated tests. Each step in the scenario is connected to test code that interacts with the system. When the tests are executed, the scenarios verify that the system behaves as described. This approach turns functional documentation into executable specifications. If the system behavior changes then scenarios immediately reveal the difference between expected and actual behavior. In GovStack implementations this approach is useful for validating interactions between components, both internally as well as in combination across multiple Building Blocks. Automated behavior tests can confirm that: * Building Block APIs behave as expected * workflows across multiple services produce the correct outcome * different implementations of the same Building Block follow the same rules (a government may have one web based user interface and another mobile user interface that are expected to provide the same value in a different environment). By connecting functional descriptions directly to automated testing, governments and vendors gain a way to verify that interoperable services behave consistently in the ecosystem. *More:* [*https://en.wikipedia.org/wiki/Cucumber\_(software)*](https://en.wikipedia.org/wiki/Cucumber_\(software\)) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://specs.govstack.global/architecture/4-interoperability-architecture/4.2-functionality-design.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.