This work represents our contribution to the Fall 2022 Architectural Katas hosted by O'Reilly. We seek to develop a software architecture for the Hey, Blue! initiative. It's mission is establish connections among police officers and community members who sharing a common purpose. Hey, Blue! has been brought to live by John Verdi, a retired law enforcement officer from NYC and 9/11 first responder.
Our team IPT consists of Matthäus Heer (LinkedIn), Nicolas Mesot (LinkedIn) and Max Riedel (LinkedIn). We are IT Consultants with Innovation Process Technology AG 🚀 in Zurich, Switzerland. Our goal is to make technology valuable. Thus, we put our ❤️ into IT.
During 9/11 EcoSchool founder and 9/11 first responder John Verdi experienced the collaborative acts of heroism by first responders and civilians. That inspired him to start Hey, Blue!, an initiative to facilitate moments of meaningful connection between police officers and members of their community.
Hey, Blue! is used to incentivize police officers and civilians to meet and share their positive connection with other community members. The initiatives target is to have police officers across the United States connect with 5 civilians each day, which would lead to 1.2 billion connections each year. Both the officer and the civilian are granted points for their positive connection. Officers can donate their points to charities. Civilians and charities can redeem their points in exchange for goods or discounts from participating local businesses.
We grouped the requirements for the Hey, Blue! application into the following two sections.
The following overview exhibits all actors participating in the Hey, Blue! ecosystem with their main intentions and capabilities. More specifics can be found in the Functional requirements section as well as the Context section.
For a legend refer to the section Domain Design.
While the former explains the desired functionalities of the application, describing possible user interactions, the latter represents a set of technical guidelines the system has to adhere to.
In the following, we will describe what actors (can be a user, participant or system) might interact in what way with the Hey, Blue! system. For that matter, the diagram displays the main capabilities or intentions a user or system has to its disposal.
The actors are being divided into internal, i.e. actors which are internal to the Hey, Blue! ecosystem and external actors, e.g., civilians and officers using the application. That way we receive a clear picture who profits from this ecosystem and what the intends and desires of those actors might be.
Now that all the actors and intents in the system are well understood, it's time to map these requirements into domain model which defines a common terminology and crystallizes out lower level components of the domain landscape. These components are grouped into so-called capabilities which form the basis for the final software architecture based on microservices. We tackle this challenge by employing Domain Driven Design. This approach enables us to subdivide the overarching problem statement into meaningful sub-domains based on business requirements and come up with a scalable, modularized and extensible software architecture.
Event Storming is a technique to develop a common understanding of all involved stakeholders, that is, domain experts, managers and the development team, of the domain at hand.
Learn more about our approach in the Event Storming Subpage.
The following picture shows the final state of the Event Storming session. Note the overarching capabilities (green stickers) which we distilled out of the domain landscape which then became the foundational domain capabilities for our microservice architecture.
We used the Architecture Styles Worksheet from Mark Richards website to make an informed decision on the architecture style of Hey, Blue!. As shown in the matrix below and as stated in System Characteristics we identified Feasability (cost), Evolvability and Scalability as our main characteristics to base our decision on.
Though costs may be higher, we decided to go for a microservice architecture style with event-driven elements in it (see ADR01 Microservice Architecture and ADR02 Event-Driven Design). With this we can best guarantee that Hey, Blue! can scale and adapt accordingly to the users needs, and is so best setup for success. Monolithic options, which usually are cheaper to develop, won't be able to hold up with the pace in which a social network can evolve.
Based on the output of the Event Storming, we defined the following capabilities for each of which we developed a microservice architecture: Connection, Order, User, Report.
The following diagram gives a high-level overview of how the capabilities interact with each other. An in-depth explanation of how each capability works internally and what their responsibilities are, is shown in the section up next.
Connection Capability
This is the heart piece of the Hey, Blue! ecosystem enabling civilians and officers to connect. This includes the possibility for officers to enroll in the look-up for civilians such that civilians can find officers online, the actual virutal handshake itself along with the respective notifications, rewards and awarding of points. Handshakes can only happen in proximity and connections might be shared over social media. |
Reporting Capability
The reporting capability covers the service landscape enabling Hey, Blue! staff to generate reports and share them with media companies. |
Order Capability
The order capability describes the service landscape enabling Civilians or Charities to redeem their points. |
User Capability
This capability is responsible for maintaining user sessions, storing user data, registering new users and keeping track of connections between officers and civilians. |
For all of the above, if not stated otherwise in the diagram at hand, the symbols reflect the meaning as described in the following legend.
We used a domain-driven approach to define our service landscape for the Hey, Blue! ecosystem. With those capabilities at hand, we finally propose a cloud-native software solution that can cope with the requirements and is feasible to implement for an ambitious startup corporation. The design embraces DevOps, GitOps and Zero Trust principles as first class citizens. As an exemplary cloud vendor we chose Microsoft Azure, however the solution can easily be ported to other cloud platforms as described in ADR07 Azure as a Hyperscaler.
Please refer the system architecture document for further explanations.
This summary provides an overview of the ADRs we refer to in the appropriate sections above. An ADR includes the context, i.e. the problem statement, a solution space, a decision, rationale and the decisions consequences.
- 2022-10-31 ADR01 Microservice Architecture
- 2022-10-31 ADR02 Event-Driven Design
- 2022-10-31 ADR03 Points Redemption Framework
- 2022-10-31 ADR04 Dispatcher Architecture
- 2022-11-01 ADR05 Backend-for-Frontend Pattern
- 2022-11-06 ADR06 Read Replica Pattern
- 2022-11-08 ADR07 Azure as a Hyperscaler
- 2022-11-08 ADR08 GDPR Compliance
We would like to thank the team behind the O'Reilly Architectural Katas and the judges for their effort in making this instructive and fun event possible. Next, we would like to thank the team of Hey, Blue! for presenting such an interesting challenge with real-world usage and positive impact for society. Finally, we would like to thank our employer, Innovation Process Technology, for giving us the opportunity to participate in this challenge and working on our architectural skills. It's been one hell of a ride.
