Merge pull request #1446 from CDCgov/devex/1247-add_impact_sections_0…

…01-006

ADRs: Filling in impact sections for 001 - 006

adr/001-architecture-decision-records.md

@@ -17,30 +17,45 @@ ADRs are originally described by [Michael Nygard in an article](https://cognitec
 We want to record our architectural decisions so that...
 
 - New team members who join can see why we made the decisions we made.
+
+
 - The team can revise or revisit decisions with more confidence and context.
 
 ## Impact
 
-_The outcomes of the decision, both positive and negative. This section explains the impact of the decision, such as trade-offs, risks, and what needs to be done to implement it._
+The outcomes of the decision, both positive and negative. This section should explain the impact of the decision, such as trade-offs, risks, and what needs to be done to implement it.
 
 ### Positive
 
 - **Transparency**: ADRs make decision-making more transparent, helping current and future team members understand the rationale behind decisions.
+
+
 - **Historical Context**: They provide valuable historical context, aiding in future decision-making and avoiding repeated mistakes.
+
+
 - **Onboarding**: ADRs speed up the onboarding process by quickly familiarizing new team members with architectural decisions.
+
+
 - **Consistency**: A standardized format ensures consistent documentation, making records easier to maintain and reference.
 
 ### Negative
 
 - **Overhead**: Maintaining ADRs requires time and effort.
+
+
 - **Outdated Records**: If not regularly updated, ADRs can become outdated and misleading.
 
 ### Risks
 
 - **Incomplete Documentation**: Not all decisions may be documented, leading to gaps in the record.
+
+
 - **Misalignment**: ADRs may not always match the actual implementation, causing confusion.
 
 ## Related Issues
 
 - #1
 - #13
+- #1247
+
+### Please see [adr-guidelines.md](adr/adr-guidelines.md) before completing.

adr/002-java.md

@@ -4,7 +4,8 @@ Date: 2022-10-21
 
 ## Decision
 
-We will use Java 17 for the main trusted intermediary code.
+We will use Java 17 for the main intermediary code.
+
 This doesn't preclude us from using other languages for other services or applications.
 
 ## Status
@@ -13,10 +14,31 @@ Accepted.
 
 ## Context
 
-We decided to use a JVM based language because it has many third-party healthcare libraries and frameworks.
+We decided to use a Java Virtual Machine- (JVM) based language because it has many third-party healthcare libraries and frameworks that are pertinent to the project. 
 
 We decided on Java over Kotlin, Scala, and Groovy because more people know Java.
 
+## Impact
+
+### Positive
+
+- **Robust and Well-Maintained Libraries:** has robust libraries, like HAPI FHIR, which provide comprehensive support for creating, parsing, and validating FHIR resources. Libraries are well-maintained and widely used in the healthcare industry
+
+
+- **Powerful Data Processing:** ability to handle large-scale, multithreaded applications makes it suitable for processing large volumes of FHIR data in real-time, which is crucial in healthcare settings
+
+
+- **Compliant Security Features:** Java's security features, such as encryption and secure authentication mechanisms, help in building HIPAA-compliant FHIR applications.
+
+### Negative
+
+- **Verbose Code:** Code tends to be more verbose leading to longer development times and more boilerplate code.
+
+
+### Risks
+
+- **Limited Functional Expression:** Limited functional programming capabilities can make it harder to express certain data transformation logic that is common in FHIR processing, compared to languages with stronger functional programming support.
+
 ### Related Issues
 
 - #1

adr/003-gradle.md

@@ -4,21 +4,51 @@ Date: 2022-10-24
 
 ## Decision
 
-We will use the [Gradle build tool](https://gradle.org) for the main trusted intermediary code.
+We will use the [Gradle build tool](https://gradle.org) for the main intermediary code.
 
 ## Status
 
 Accepted.
 
 ## Context
 
-[Maven](https://maven.apache.org) is the other big option available to us.  Gradle was chosen over Maven because
-- it uses Groovy, an actual programming language, to configure the projects instead of XML, which has a rigidly defined schema.
-  This allows for better expressibility in how one configures their project.
+Other build tools were considered; [Maven](https://maven.apache.org) is the other big option available to us.  Gradle was chosen over Maven because
+- Gradle uses Groovy, an actual programming language, to configure the projects instead of XML (Extensible Markup Language), which has a rigidly defined schema.
+
+
+- Gradle allows for diversity in configuration of the project.
+
+
 - Gradle is faster with its job execution.
 
 
-### Related Issues
+## Impact
+
+### Positive
+
+- **Advanced Dependency Management** capabilities help streamline the integration of FHIR libraries, such as HAPI FHIR, and other required dependencies
+
+
+- **Highly Customizable Scripts:** Highly customizable build scripts allow for fine-tuned configuration.
+
+
+- **Reduced build times**
+
+
+- **CI/CD Automation:** integrates well with continuous integration and continuous deployment (CI/CD) pipelines, enabling automated testing
+
+### Negative
+
+- **Cumbersome Build Scripts:** Flexibility can lead to complex and verbose build scripts; Managing these scripts can become cumbersome.
+
+
+- **Configuration Incompatibility:** Custom configurations may not be fully compatible with certain versions of Java or FHIR libraries.
+
+### Risks
+
+- **Possible Slow Build Times** due to scripts and project size
+
+## Related Issues
 
 - #1
 - #13

adr/004-groovy-spock.md

@@ -4,24 +4,51 @@ Date: 2022-10-24
 
 ## Decision
 
-We will use the [Groovy programming language](http://groovy-lang.org) with the
-[Spock testing framework](https://spockframework.org) for our unit and end-to-end testing.
+We will use the [Groovy programming language](http://groovy-lang.org) with the [Spock testing framework](https://spockframework.org) for our unit and end-to-end testing.
 
 ## Status
 
 Accepted.
 
 ## Context
 
-Spock is a testing framework similar to [JUnit](https://junit.org/junit5/).  Some benefits of Spock include...
+Spock is a testing framework similar to [JUnit](https://junit.org/junit5/).  Some benefits of Spock include: 
+
 - Encourages BDD-style given/when/then testing.
+
 - Mocking is _super_ easy.  No need for a separate dependency like [Mockito](https://site.mockito.org).
+
 - Expressive assertion failures.  No need for a separate dependency like [Google Truth](https://truth.dev).
+
 - Adds a layer of flexibility and expressiveness to testing that you don't get with JUnit.
 
 Spock requires we use Groovy, another JVM-based language.
 
-### Related Issues
+## Impact
+
+### Positive
+
+- **Expressive and readable tests**
+
+
+- **Data-driven Testing:** supports data-driven testing which is useful for testing FHIR resources across a variety of scenarios with different data sets
+
+
+- **Integrates well with Java**
+
+### Negative
+
+- **Limited IDE Support:** writing and debugging tests can become cumbersome 
+
+### Risks
+
+- **Slower Test Execution:** Tests can potentially run slower compared to simpler JUnit tests, especially for larger test suites. 
+
+
+- **Dependency Management:** Managing Groovy dependencies alongside Java libraries may introduce complexity or compatibility issues in certain build environments.
+
+
+## Related Issues
 
 - #1
 - #13

adr/005-oea.md

@@ -0,0 +1,60 @@
+# 5. Option Enabling Architecture (OEA)
+
+Date: 2022-10-24
+
+## Decision
+
+We will use use OEA practices to inform how we add new features and refactor.
+
+## Status
+
+Accepted.
+
+## Context
+
+OEA is similar to [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html).
+There are a couple main concepts that we strive to maintain while also being pragmatic.
+
+1. Less important code depends on more important code.  For example, third-party dependencies such as ReST
+   frameworks, and database ORMs.  This allows for swapping out less important code without affecting the more
+   important code.
+
+
+2. Dependency inversion.  This allows the path of code execution not to follow the dependency path of
+   less important code depending on more important code.  For example, when business logic needs to call the
+   database.
+
+## Impact
+
+### Positive
+
+- **More flexible architecture**
+
+
+- **Risk mitigation** through delayed decision-making.
+
+
+- **Minimizes large-scale changes and overhauls**
+
+
+- **Better maintainability**
+
+### Negative
+
+- **Experience May Be Required:** requires more experience to implement successfully
+
+
+- **Increased initial development time**
+
+
+- **Increased Planning:** requires much more forethought prior to implementation
+
+### Risks
+
+- **Overengineering:** potential to overengineer by keeping too many options open
+- Deferred decision-making can lead to technical debt
+
+## Related Issues
+
+- #1
+- #13

adr/006-domain-plugin.md

@@ -4,22 +4,46 @@ Date: 2022-10-24
 
 ## Decision
 
-A plugin paradigm will be used for the different business domains of the trusted intermediary.  This improves
-modularity, separates concerns, and allows for flexibility in the future if it makes sense to extract this domain
-into a separate JAR, Gradle project, or even repository.
+A plugin paradigm (plugin-based architecture) will be used for the different business domains of the intermediary. This improves modularity, separates concerns, and allows for flexibility in the future if it makes sense to extract this domain into a separate JAR, Gradle project, or even repository.
 
 ## Status
 
 Accepted.
 
 ## Context
 
-The trusted intermediary useful for just one business domain.  There are multiple areas in healthcare where
-a trusted intermediary could be beneficial.  To that end, a plugin paradigm is used to register domain(s) with the
-larger trusted intermediary application.  This also allows the domain to develop and operate regardless how the
-trusted intermediary operates.  E.g. Is the trusted intermediary in a Jetty Java container hosted on a VM or is it
-hosted in Azure Functions?
+The intermediary currently serves a single business domain, but it has the potential to support multiple domains in healthcare where a intermediary is beneficial. To accommodate this, we will adopt a plugin-based architecture that allows new domains to be registered with the intermediary. This approach enables each domain to be developed and operated independently of the intermediary’s core system.
 
-### Related Issues
+This independence also applies to the intermediary’s deployment environment, whether the intermediary is running in a Jetty Java container on a VM, or hosted within Azure Functions, the plugin paradigm ensures that domain logic remains unaffected and adaptable to various operational contexts.
+
+## Impact
+
+### Positive
+
+- **Encapsulation of domain-specific logic** ensuring isolation of concerns; Core application logic remains unaffected.
+
+
+- **Reusability:** Plugins can be reused reducing duplication.
+
+
+- **Flexibility:** Domains can evolve independently and potentially be extracted into separate projects.
+
+
+- **Targeted Testing:** focused unit and integration testing
+
+
+### Negative 
+
+- **Increased Complexity:** Managing multiple plugins can increase architectural complexity over time, especially with the addition of features.
+
+- **Dependency Management Challenges:** Ensuring compatibility across multiple versions can become cumbersome.
+
+
+### Risks
+- **Maintenance Burden:** possible increased maintenance burden which can require more rigorous testing
+
+- **Fragmentation Risk:** increased possibility for inconsistencies across the system due to varying approaches
+
+## Related Issues
 
 - #13

adr/adr-guidelines.md

@@ -0,0 +1,19 @@
+# Architectural Decision Record Formatting Checklist
+Below is a formatting checklist with some guidelines that serves to help keep our ADRs looking clean and uniform.
+
+1. See [adr/001-architecture-decision-records.md](001-architecture-decision-records.md) for template and section guidelines/requirements.
+
+
+2. Review ‘Context’ section for grammar, typos, and clarity. ** **Keep in mind** ** readers may have less inside knowledge or experience with the project when reading these documents.
+
+
+2. **Bulleted Lists:** Full sentences get periods and first letter capitalized. Fragmented sentences have no period and aren’t capitalized.
+
+
+3. **Bulleted Lists:** Embolden bulleted titles with colons
+
+
+4. Make sure line spacing is appropriate give a full line of space between bullet points
+
+
+5. If you are unsure about something, ask!