Merge pull request #5 from NHSDigital/feature/CCM-5145-getting-started-docs

Add architecture documentation for bounded contexts

Author: m-houston

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,6 +15,7 @@
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would change existing functionality)
 - [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] Documentation
 
 ## Checklist
 

.tool-versions

@@ -2,6 +2,8 @@
 
 terraform 1.7.0
 pre-commit 3.6.0
+nodejs 18.18.2
+gitleaks 8.15.3
 
 # ==============================================================================
 # The section below is reserved for Docker image versions.

docs/architecture/Index.md

@@ -0,0 +1,40 @@
+---
+layout: default
+title: Architecture
+nav_order: 4
+has_children: true
+---
+
+Be aware of NHS organizational
+standards: [NHS Architecture Principles][nhsap] | [Software Engineering Quality Framework][seqf] |
+[Records Management Code of Practise][rmc]
+
+[nhsap]: https://digital.nhs.uk/about-nhs-digital/our-work/nhs-digital-architecture/principles#download-the-nhs-architecture-principles
+
+[seqf]: https://github.com/NHSDigital/software-engineering-quality-framework
+
+[rmc]:https://transform.england.nhs.uk/information-governance/guidance/records-management-code/
+
+## General principles for diagrams
+
+* Pages are structured using the [4+1 View of Architecture][Kruchten]
+  and flow from high level to broken down functionality.
+* Final "view" documentation is meant to represent the "current" view
+  of the system, not work in progress
+* Diagram checklist to help with consistency:
+  1. Diagrams flow from left to right, then top to bottom to allow
+     readability
+  2. 0.5 line and shape width
+  3. lines are recommended to have text (and preferably numbered)
+  4. provide context on which part of the system the diagram relates
+     to
+
+![img.png](assets/kruchten_4_1_model.png)
+
+[<figcaption>Architectural Blueprints—The “4+1” View Model of Software Architecture</figcaption>][Kruchten]
+
+[Kruchten]: https://ics.uci.edu/~michele/Teaching/INF117/Krutchten%204+1View%20SWArch.pdf
+
+* Physical
+  * [Sub-domains and bounded contexts](physical/sub-domains_and_bounded_contexts)
+  * [Initial account structure for new architecture](physical/initial_account_structure_for_new_architecture)

docs/architecture/assets/kruchten_4_1_model.png

@@ -0,0 +1,29 @@
+---
+layout: default
+title:  Initial account structure for new architecture
+parent: Architecture
+---
+
+* The initial accounts have been created reflect the structure we
+  intend to use for the new Web UI
+  * A top-level DNS sub-domain provides the mapping from the nhsnotify
+    DNS root to delegated DNS zones in each sub-domain account
+  * The Event Bus account provides a central location for events to be
+    published without the consuming services needing direct knowledge
+    of the source
+  * The Web Platform account provides the endpoint for the Web UI and
+    documentation. It delegates requests to the other micro-frontend (
+    MFE) services
+* Each MFE (micro-frontend) is implemented in its own sub-domain.
+  Initially these will be:
+  * CMS: Service documentation. This may be hosted on GitHub pages in
+    which case it may not have its own domain accounts
+  * Auth: Federated login identity provider which will provide tokens
+    for use across the other MFE services
+  * Template Manager: MVP template manager web UI
+* The existing system, while it consists of several conceptual
+  domains, is currently deployed to a single account
+  * As we refine the architecture we will extract sub-domains from the
+    core system and create new accounts to encapsulate them.
+
+![NHS Notify Domains](assets/Domains.drawio.png)

docs/architecture/physical/assets/Bounded_Context.drawio.png

@@ -0,0 +1,38 @@
+---
+layout: default
+title:  Sub-domains and bounded contexts
+parent: Architecture
+---
+
+[Bounded contexts][1] are a pattern used in DDD to model parts of a
+system which operate on a single consistent model of part of a
+business domain.
+
+[1]: https://martinfowler.com/bliki/BoundedContext.html
+
+For NHS Notify we are attempting to keep our architecture modular
+following DDD principles. As a starting point when creating new
+bounded contexts these are some suggestions for structuring the AWS
+accounts and components which are deployed within them.
+
+* By default, each sub-domain has its own AWS accounts
+  * `<sub-domain>-preprod` (AKA `dev`)
+  * `<sub-domain>-prod`
+* Each sub-domain will have a top-level GitHub repo which defines the
+  account-level infrastructure
+* Each sub-domain will have one or more bounded contexts
+  * Usually this revolves around some store of state
+  * Subscriptions for events which affect that state
+  * Handlers and processing for changes to state
+  * APIs for direct actions on the state
+  * Events published to reflect changes to the state
+  * Auditing and logging to wrap the service and provide observability
+* A sub-domain may contain one or more microservices
+  * Each microservice should be individually deployable with defined
+    contracts between services
+  * Each microservice should be contained in its own GitHub repo
+* Questions:
+  * Where are audit logs kept? Per sub-domain, or shared location in
+    isolated account?
+
+![Bounded Context Diagram](assets/Bounded_Context.drawio.png)