/Myagis-Forests

2020 O'Reilly Software Architecture Kata

This is the GitHub repo for the solution created by team Miyagi's Little Forests for the 2020 O'Reilly Architectural Kata. It contains a proposed architecture for Farmacy Food.

Team contact: miyagisforests@gmail.com

Team members:

  • Antônio Carvalho
  • Eldon Coutinho
  • Paulo Merson

The three of us are developers in the IT department of the Brazilian Federal Court of Accounts (TCU). We help design and implement service-based solutions at TCU (from our homes in Brasília these days).

Here's our five-minute video presentation for the O'Reilly Architectural Kata.

miro board Check out our Miro Board containing all the diagrams below. You can also comment on it.

Questions? Comments? Interested in microservices? EDA? DDD? Architecture in general? Feel free to chime in!

Farmacy Food system

Requirements

This section contains the requirements, distilled from the provided document and
the interview with the PO, Kwaku Osei, but also with some assumptions we made. These requirements were the main drivers for the design decisions in this proposal.

Architecture

Here you find the documentation of the software architecture that we envision to address Farmacy Food's requirements.

As a starting point, there's a context diagram that gives an overview of the external elements that interact with what we called the Farmacy Food System, which is the scope of this software architecture.

Context Diagram

The main part of the software architecture is the set of five architecture views seen below. These views provide a runtime perspective of the system, that is, they show the components and connectors that have runtime presence and altogether correspond to the main capabilities provided by the Farmacy Food system. They follow the microservice and EDA architecture styles.

User Account Management - microservice view
 Catalog - microservice view
Order - microservice and EDA view
 		Customer at pick-up location - microservice and EDA view
Replenisher - microservice and EDA view

The following architecture view is a DDD Context Map. It shows how the Farmacy Food system is broken up into bounded contexts (BCs) and how they interact with each other.

DDD Context Map
 		DDD Context Map to microservices mapping

We believe the implementation of each BC can follow the hexagonal architecture. The following architecture describes how the code of each BC can be structured according to this architecture style.

Hexagonal reference architecture view

Finally, we have a deployment view that describes the runtime infrastructure for the components seen in the five runtime architecture views.

AWS deployment view

Our architecture views were documented following a lightweight view template available here.

ADRs

The linked ADRs below record the main architecture decisions regarding the proposed design, including their context and rationale.

Note: we used this ADR template. It is slightly different from the template presented by Neal during the first Kata session. The justification is in the README file of the ADR template repo.

Backlog

Pending design activities for a hypothetical future sprint. :^)

  • Better record the quality attribute requirements (aka non-functional requirements). Requires talking to Kwaku and other Farmacy Food stakeholders.
  • Add information in the AWS deployment architecture related to:
    • containerization and pod configuration
    • security settings
    • log consolidation
    • monitoring and tracing
  • Create architecture detailing the domain model at the tactical level. Examples of information in such views:
    • entities and VOs that form aggregates (or equivalent if not using DDD modeling)
    • domain events and event hierarchies
  • Write ADR for using an event-driven architecture for order processing.
  • Add the description of components that are missing in the element catalogs of the architecture views.

About the team Name

Miyagi's Little Forests is certainly an unusual name for a dev team. The name has both a pop culture and an academic reference:

  • Mr. Miyagi is the shy Karate master in the 1984 "The Karate Kid" film. In the movie, which inspired a generation of then teenagers including the members of this team, Mr. Miyagi teaches the young Daniel-san the ancient art of Karate. The teaching of this martial art is anchored on Katas. Hence the nuanced connection to our architecture challenge.
  • In a seminal 1976 paper, Frank DeRemer and Hans Kron described like this the concern that 15 years later would drive the advent of the software architecture field: "However, current languages discourage the accurate recording of the overall solution structure; they force us to write programs in which we are so preoccupied with the trees that we lose sight of the forest, as do the readers of our programs!" For long, we have used the ability to see the forest and not only the trees as a metaphor for thinking the software architecture.
  • In The Karate Kid, Miyagi and Daniel-san form a team and open a store called Miyagi's Little Trees. So, paying homage to the movie and embracing the architecture metaphor, we are team Miyagi's Little Forests.

Miyagi and Daniel-san