general review: links, images, grammar, typos

ADRs/ADR001-microservice-style.md

@@ -1,9 +1,9 @@
 # ADR 001: Use the microservice architecture style with containerization
-Farmacy Food is a start up company and does not have a sizeable team of experienced developers available. The overarching
+Farmacy Food is a start-up company and does not have a sizeable team of experienced developers available. The overarching
 architecture style for the Farmacy Food system should be simple, easy to create, maintain and **evolve**. Finding 
 developers that can create and evolve the system, as well as tools and frameworks that support the system should not
 require heaps of money. In other words, Farmacy Food is not in a position to be an *early adopter*, and should hence adopt an established architecture style
-that suppors evolution.      
+that supports evolution.      
 
 ## Decision 
 We will use the microservice architecture style for backend services in the Farmacy Food system. 
@@ -37,9 +37,9 @@ would work just as well for the Farmacy Food system. It has the nice benefit of
 units called domain services, which are simpler to design and reduce the burden of packaging, deploying and overseeing 
 to a reasonably small number of units. We chose microservice over service-based for two main reasons:
   - Microservices are more suitable to containerization and hence cloud-deployment.
-  - We try to mimic the service-based style maintainability benefit at the development artifacts level via the heaxagonal architecture.
+  - We try to mimic the service-based style maintainability benefit at the development artifacts level via the hexagonal architecture.
   For example, a single git project that corresponds to a hexagonal architecture can yield a few microservices (i.e., docker 
-  images, our deploymet units). We then handle the increased burden of managing more fine grained *runtime* units 
+  images, our deployment units). We then handle the increased burden of managing more fine-grained *runtime* units 
   via **extensive automation**.  
 
 ## Status
@@ -56,9 +56,9 @@ microservice development. Although it's a startup, Farmacy Food should try to de
 a basic reference architecture (with room for evolution). "Governance" is an abominable word, especially for startups. 
 But what we're suggesting can be as simple as:
   - Have a clear representation of the reference architecture (we have a good start in our [hex architecture](../architecture/hexagonal-reference-architecture.md),
-  and [deployment architecture](../architecture/aws-deployment-architecture.md)). 
+  and [deployment architecture](../architecture/aws-deployment-view.md)). 
   - Make sure all devs know about and understand the reference architecture.
-  - Create a space (e.g., a slack channel) for occasionally discussing changes and evolution of the reference architecture. 
+  - Create a space (e.g., a Slack channel) for occasionally discussing changes and evolution of the reference architecture. 
   Later on, when Farmacy Food becomes a larger enterprise, it could be done in an "architecture guild".   
 - Farmacy Food needs a team of developers familiar with microservice development, [microservice patterns](https://microservices.io/),
  as well as with tools and frameworks, such as: 

ADRs/ADR002-payment-gateway.md

@@ -9,8 +9,8 @@ However, during a transition period, we will use the payment gateway in hosted m
 
 ## Rationale 
 Though a *hosted* payment gateway solution is simpler to roll out, it has some drawbacks:
-- in the case of the Web app, the user is directed to a separate web site to complete the payment (the payment gateway 
-provider web site). The user experience is not seamless thoughout.  
+- in the case of the Web app, the user is directed to a separate website to complete the payment (the payment gateway 
+provider website). The user experience is not seamless throughout.  
 - in the case of the native apps, the user is directed to a separate app.
 - transaction fees tend to be higher than in self-hosted mode.
 - the merchant still needs to be PCI DSS compliant. 

ADRs/ADR005-cqrs-pattern.md

@@ -7,12 +7,12 @@ whereas the design of reads (queries) has performance (response time) as a key r
 ## Decision 
 We will use the [CQRS pattern](https://udidahan.com/2009/12/09/clarified-cqrs/) applied to microservices with this design:  
 - an independently deployed service takes care queries. It reads data from a query view that is optimized for data reads.
-("Optimized" means using DB technologies and techniques that favor performance, such as: NoSQL, desnormalized view, memory cache, sharding, replication.)  
+("Optimized" means using DB technologies and techniques that favor performance, such as: NoSQL, denormalized view, memory cache, sharding, replication.)  
 - an independently deployed service takes care of commands. It may be a REST service that gets POST commands or a reactive service
 that subscribes to a pub-sub topic and gets messages that updates the master database for the scope of that service. 
 - a batch component (example: K8S cron job or logic activated by database-triggered events) synchronizes the data between 
 the master database and the query views. The frequency of data synchronization varies--it can be trigger-based, 
-every 5 minuts, every hour, ..., once a day, etc.   
+every 5 minutes, every hour, ..., once a day, etc.   
 
 In our design, we have used CQRS for:
 - Inventory

README.md

@@ -1,4 +1,4 @@
-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](https://www.farmacyfood.com/).
+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](https://www.farmacyfood.com/).
 
 Team contact: [[email protected]](mailto:[email protected])
 
@@ -91,7 +91,7 @@ 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.  
 
 <table>
-<tr><td align="center"><a href="architecture/hexagonal-reference-architecture.md">Hexagonal reference architeture view<br>
+<tr><td align="center"><a href="architecture/hexagonal-reference-architecture.md">Hexagonal reference architecture view<br>
 <img src="images/hexagonal-reference-architecture.jpg" width="200"></a></td></tr>
 </table>
 

architecture/aws-deployment-view.md

@@ -59,7 +59,7 @@ For example, the **Inventory Query View** database seen below will be configured
 #### Kafka (AWS MSK)
 - The [Amazon managed Kafka service](https://aws.amazon.com/msk/) (MSK) is a fully-managed Kafka broker cluster that 
   supports publish-subscribe channels (called topics).
-- Components that send messages (producers aka publishers) and receive messages (consumers aka subcribers) can be 
+- Components that send messages (producers aka publishers) and receive messages (consumers aka subscribers) can be 
 implemented using various languages and frameworks. For example, we can use the [spring cloud AWS](https://www.baeldung.com/spring-cloud-aws-messaging)
 framework.  
 - The various topics seen in the EDA architecture views shall be configured in the MSK cluster with minimum replication factor of 3.  
@@ -93,4 +93,4 @@ N/A
 - [Order - microservice and EDA view](order-microservice-eda-view.md)
 - [Catalog - microservice view](catalog-microservice-view.md)
 - [Replenisher - microservice and EDA view](replenish-microservice-eda-view.md) 
-- [Hexagonal reference architeture view](hexagonal-reference-architecture.md) 
+- [Hexagonal reference architecture view](hexagonal-reference-architecture.md) 

architecture/catalog-microservice-view.md

@@ -1,6 +1,6 @@
 # Catalog Microservice View 
 The scope is the various query/browsing operations that an app user can perform: browsing or searching for meals,
-browsing promotions and coupons, looking at subscrition plans, pick-up location finder. 
+browsing promotions and coupons, looking at subscription plans, pick-up location finder. 
 
 This is a microservice architecture. Key patterns used:
 - BFF
@@ -16,13 +16,13 @@ This is a microservice architecture. Key patterns used:
 #### Pick-up location finder
 - Has endpoints to list and search for pick-up locations near a given address or in a given region (city, state).
 - The database of pick-up locations is updated by another component (not shown in the diagram). (Being honest, in a 
-start up setting, it might as well be that for a while there won't be any UI for updating locations and this kind of 
+start-up setting, it might as well be that for a while there won't be any UI for updating locations and this kind of 
 data repository will be updated manually.)
 
-#### Google maps wrapper
-- Handles all interaction with the [Google maps external service](https://developers.google.com/maps/solutions/store-locator), 
+#### Google Maps wrapper
+- Handles all interaction with the [Google Maps external service](https://developers.google.com/maps/solutions/store-locator), 
 used for retrieving plotted maps with pick-up locations.
-- Contains all the specifics to interact with Google maps (API key, GeoJSON data transformation, etc.)
+- Contains all the specifics to interact with Google Maps (API key, GeoJSON data transformation, etc.)
 - Exposes a standardized interface for location finder functionality to the BFFs (and hence the frontends).  
 
 #### Google maps

architecture/ddd-context-map.md

@@ -39,7 +39,7 @@ main business challenge is of a logistics nature.
       ![Bounded context closer look](../images/ddd-context-map-bc-meal-catalog-close.png)
 
 ##### Inventory
-- Controls what meals are available in each smart fridge and vendlor location.
+- Controls what meals are available in each smart fridge and vendor location.
 - It's a core domain BC.
 
       ![Bounded context closer look](../images/ddd-context-map-bc-inventory-close.png)
@@ -123,7 +123,7 @@ main business challenge is of a logistics nature.
 - Maps and location finding services.
 
 ##### Identity
-- Authentication using third-party identitiy, such as Google or Facebook.
+- Authentication using third-party identity, such as Google or Facebook.
 
 ##### eDietitian
 - Expert system that would generate meal recommendations based on user preferences, health info, and history.
@@ -142,9 +142,9 @@ relationships between the designed BCs as partnerships.
 model is accepted/absorbed without translation by the _downstream_ (**`D`**) counterpart.
 - In our model, this relationship is used in three scenarios. The integration with the _Identity_
 subdomain, mostly because the solutions in this subdomain, e.g. OAuth, are typically widely known and accepted.
-The _eDietitian_ subdomain is expected to require some information to generate their decisions and it our system should 
+The _eDietitian_ subdomain is expected to require some information to generate their decisions and our system should 
 provide that data as needed. Lastly, given the *Customer Notification* BC is expected
-to be generic, some off-the-shelf tool would likely provide the means of integrating with our BCs with minimal effort.
+to be generic, some off-the-shelf tool would likely provide means for integration with our BCs with minimal effort.
 
 #### Anticorruption Layer - ACL (BC Relationship)
       ![ACL Relationship closer look](../images/ddd-context-map-relationship-acl.png)
@@ -189,13 +189,10 @@ we have also specified in the diagram the technical mechanisms used to integrate
 ## Related Views
 - [DDD Context Map to microservices mapping](ddd-context-map-to-microservices.md)
 - [Context Diagram](context-diagram.md)
-- [Hexagonal reference architeture view](hexagonal-reference-architecture.md)
+- [Hexagonal reference architecture view](hexagonal-reference-architecture.md)
 - [User Account Management - microservice view](user-account-mgmt-microservice-view.md)
 - [Catalog - microservice view](catalog-microservice-view.md)
 - [Order - microservice and EDA view](order-microservice-eda-view.md)
 - [Customer at Pick-up Location Microservice and EDA View](customer-pickup-microservice-eda-view.md)
 - [Replenisher - microservice and EDA view](replenish-microservice-eda-view.md)
-
-<!--
 - [AWS Deployment view](aws-deployment-view.md)
---> 

architecture/hexagonal-reference-architecture.md

@@ -8,7 +8,7 @@ The execution of an *inbound adapter* is activated by an external element. These
 is not technology specific and resides in the Application and Domain layers in the center. 
 
 *Outbound adapters* are used by the application to interact with other external elements: reading or writing to/from 
-databases), calling http services, publishing events to a message broker topic.
+databases, calling http services, publishing events to a message broker topic.
 
 The hexagons are layers and hence the hexagonal architecture is a layered architecture. In our hexagonal architecture, 
 the constraint is that *modules in an outer layer can use modules in any inner layer*. There's one exception: modules in the
@@ -26,8 +26,8 @@ dependencies in the application layer).
 - An *inbound* REST adapter exposes http endpoints and handles the requests from outside components.
 - If you create an inbound REST adapter using for example the Spring MVC framework, the REST adapter would typically 
 consist of one or more `@RestController` classes.
-- An *oubbound* REST adapter makes calls to http services. It typically offers an function interface that is called
-by the application and then translates that function call into an http request. 
+- An *outbound* REST adapter makes calls to http services. It typically offers a function interface that is called
+by the application and then translates that function call into a http request. 
 - You can use for example the Open Feign framework to implement an outbound REST adapter.   
 
 #### Application + Domain 
@@ -37,8 +37,8 @@ Transfer Objects) and returned to outside elements.
 
 #### Batch Adapter
 - Executes scheduled tasks typically following a cron table.
-- Typically, these tasks pool components like REST services or datasources. Their purpose can be, for example, syncrhonize 
-data between a master data store and its replicas, or call third-party systems to get updates on activate processing. 
+- Typically, these are tasks pool components like REST services or datasources. Their purpose can be, for example, to synchronize 
+data between a master data store and its replicas, or to call third-party systems to get updates or activate processes. 
 
 ## Behavior
 - N/A.

architecture/order-microservice-eda-view.md

@@ -25,13 +25,13 @@ coupon and recalculate the cost based on the discount.
 - When processing the final submit for the meal order, `Checkout` calls `Inventory query` for validating the order against 
   meal availability in the selected pick-up location (if one was chosen). If everything is OK, a domain event "Purchase Order Created" 
   is published. 
-- The purchase order is processed asynchronouly, as described in the [sequence diagram](#behavior) further down. 
+- The purchase order is processed asynchronously, as described in the [sequence diagram](#behavior) further down. 
 
 #### Payment
 - Will process the payment for a submitted purchase order. 
 - Uses a third-party payment gateway. To avoid coupling the logic to one specific payment gateway provider, the interaction
 is through a wrapper service. 
-- If the payment is sucessful, `Payment` publishes a Order Payment Confirmed event containing all order details and
+- If the payment is successful, `Payment` publishes an Order Payment Confirmed event containing all order details and
 payment status.  
 
 #### Payflow wrapper
@@ -53,7 +53,7 @@ payment status.
 - See [catalog in the Customer at Pick-up Location Microservice and EDA View](customer-pickup-microservice-eda-view.md).
 
 #### Customer notification
-- Reponsible for sending out notifications to the customers via one or more mechanisms: 
+- Responsible for sending out notifications to the customers via one or more mechanisms: 
     - email
     - app push notification
     - SMS  

requirements/functional-rqmts.md

@@ -118,4 +118,4 @@ the documents provided to all teams. You will find the _actors_ we identified, a
 <p><sup>1</sup> Native mobile app or web app.</p>
 <p><sup>2</sup> Farmacy Food representative responsible for replenishing the stock of meals in smart fridges and vendor kiosks.</p>
 <p><sup>3</sup> Operations correspond to API endpoints that we expect to see in the Smart Fridge cloud-based system.</p>
-<p><sup>4</sup> Credit or debit card, or order confirmation code to be presented at the smart fridge for pick up.</p>
+<p><sup>4</sup> Credit or debit card, or order confirmation code to be presented at the smart fridge for pickup.</p>

requirements/quality-attribute-rqmts.md

@@ -35,4 +35,4 @@ store, etc.) should be low (e.g., less than 3 person-days).
 - The different versions of the app should provide a user experience that appeals to the target user population. 
 - Using UX design techniques, and providing high levels of customization are goals.
 - The system should keep the user appraised via notifications (email, app push notification, SMS, whatsApp, or other) of 
-steps in fulfilling an order (order placed, payment confirmed, order available for pick up, etc.)
+steps in fulfilling an order (order placed, payment confirmed, order available for pickup, etc.)