Architecture docs (#31)

* dev container matches repository name

* add mwa java diagram

* Prerequisites doc

* Add the CHANGES doc that describes changes from RWA

* Update README

* prod deployment doc updates

* Terraform refactoring

* prod deployment scripts and readme

* add contoso intro

* add description of requirement and design changes

* Update .gitignore

---------

Co-authored-by: Ken Schlobohm <[email protected]>

Author: nickdala

.devcontainer/devcontainer.json

@@ -1,5 +1,5 @@
 {
-	"name": "web-app-pattern-java",
+	"name": "modern-web-app-pattern-java",
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {

.gitignore

@@ -53,4 +53,8 @@ application-dev.properties
 
 # Azure CLI configuration
 az_ssh_config/
-ssh-config
+ssh-config
+
+# CAMS artifacts
+modern-java-web-email-processor-*.tar
+deployment-env

CHANGES.md

@@ -0,0 +1,22 @@
+# Modernization Journey of Contoso Fiber's CAMS Web App
+
+After migrating their Customer Account Management System (CAMS) to Azure, Contoso Fiber achieved their initial goals: a 99.9% SLO, optimized costs, and expanded reach. However, they recognized that leveraging Azure's cloud-native services would further improve agility, reliability, and scalability
+
+## Modern Web App pattern for Java
+Building on the prior [Reliable Web App pattern for Java](https://aka.ms/eap/rwa/java), which re-platformed CAMS in Azure with minimal code changes, Contoso now focuses on a Modern Web App Pattern to better utilize cloud-native capabilities. This phase involves:
+
+- Refactoring the Monolith: By using the strangler-fig pattern, Contoso is gradually transforming the monolithic CAMS into modular components, enhancing scalability.
+- Applying Queue-Based Load Leveling: This pattern optimizes performance by buffering external dependencies like email services, reducing load peaks.
+- Improving Security and Reliability: Isolating services allows Contoso to better secure components and contain any potential failures.
+
+This modernization lays a cloud-native foundation for CAMS, positioning Contoso Fiber for sustainable growth and adaptability.
+
+## New services
+
+* **Azure Container Apps** - The Modern Web App pattern reference sample uses Azure Container Apps to host a new email processing service that was separated from the web API as part of applying the [Strangler Fig pattern](https://learn.microsoft.com/azure/architecture/patterns/strangler-fig). Azure Container Apps is a fully managed serverless platform for running containerized apps. The reference sample uses Azure Container Apps because it provides managed container orchestration with support for automatic scale-in and scale-out based on a wide variety of rules using [KEDA](https://keda.sh/docs/2.13/) scalers. This allows the email processing service to automatically scale to zero when there is no work to be done and automatically scale up, as needed, based on the number of messages in the Service Bus queue.
+
+* **Azure Container Registry** - Because the Modern Web App pattern reference sample uses Azure Container Apps, it also uses Azure Container Registry to store the container images for the email processing service. Azure Container Registry allows you to build, store, and manage container images and artifacts in a private registry for all types of container deployments. Azure Container Registry supports the reference sample's SLO goals by being highly available thanks to its [geo-replication](https://learn.microsoft.com/azure/container-registry/container-registry-geo-replication#configure-geo-replication) feature.
+
+* **Azure Service Bus** - The Modern Web App pattern reference sample uses Azure Service Bus to enable message-based communication between the CAMS Application and the new email processing service. Using message-based communication allows improved reliability and performance by decoupling the CAMS application from the email processing service. Applying a [Queue-Based Load Leveling pattern](https://learn.microsoft.com/azure/architecture/patterns/queue-based-load-leveling) means that neither the CAMS application nor the email processing service will be affected by large numbers of email requests. The reference sample uses Azure Service Bus because it provides a fully managed, reliable, and secure messaging service that supports the reference sample's SLO goals.
+
+* **Azure App Configuration Feature Manager** - The Modern Web App pattern uses Azure App Configuration to store the CAMS application settings. Azure App Configuration is a managed service that provides a central place to manage application settings and feature flags.

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+## Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

README.md

@@ -2,18 +2,22 @@
 
 ## Introduction
 
-This repository contains a collection of patterns and best practices for building modern Java web applications. The patterns are designed to be used with the [Spring Framework](https://spring.io/) and [Azure](https://azure.microsoft.com/), but can be adapted to other frameworks and cloud providers.
+This repository provides a "real-world" application that implements the best practices and design patterns discussed in [Modern Web App pattern for Java](https://aka.ms/eap/mwa/java/doc). The patterns are designed to be used with the [Spring Framework](https://spring.io/) and [Azure](https://azure.microsoft.com/), but can be adapted to other frameworks and cloud providers.
 
+This project has [a companion article in the Azure Architecture Center](https://aka.ms/eap/mwa/java/doc) that describes design patterns and best practices. Here's an outline of the contents in this readme:
 
-## Prerequisites
+- [Architecture](#architecture)
+- [Workflow](#workflow)
+- [Steps to deploy the reference implementation](#steps-to-deploy-the-reference-implementation)
+- [Changes from Reliable Web App](./CHANGES.md)
+- [Additional links](#additional-links)
+- [Data Collection](#data-collection)
 
-- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
-- [Azure Dev CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd?tabs=winget-windows%2Cbrew-mac%2Cscript-linux&pivots=os-mac)
-- [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
-- [jq](https://stedolan.github.io/jq/download/)
-- [Java 17](https://adoptopenjdk.net/)
-- [Maven 3.9.1](https://maven.apache.org/download.cgi)
-- [Protoc](https://grpc.io/docs/protoc-installation/)
+## Architecture
+
+Contoso Fiber aligned to a hub and spoke network topology in the production deployment architecture to centralize common resources. This network topology provided cost savings, enhanced security, and facilitated network integration (platform and hybrid):
+
+![Architecture](./docs/assets/diagrams/modern-web-app-java.svg)
 
 ## Steps to deploy the reference implementation
 
@@ -59,7 +63,7 @@ Once the command palette is open, search for `Dev Containers: Rebuild and Reopen
 
 ![WSL Ubuntu](docs/assets/vscode-reopen-in-container-command.png)
 
-## Login to Azure
+### 3. Login to Azure
 
 Before deploying, you must be authenticated to Azure and have the appropriate subscription selected. Run the following command to authenticate:
 
@@ -95,7 +99,7 @@ If you have multiple tenants, you can use the following command to log into the
 azd auth login --tenant-id <tenant-id>
 ```
 
-## Create a new environment
+### 4. Create a new environment
 
 Next we provide the AZD tool with variables that it uses to create the deployment. The first thing we initialize is the AZD environment with a name.
 
@@ -123,23 +127,23 @@ Optional: Set the App Registration Service management reference:
 azd env set AZURE_SERVICE_MANAGEMENT_REFERENCE <service_management_reference>
 ```
 
-## Build the applications
+### 5. Build the applications
 
 Run the following command to build the applications:
 
 ```shell
 ./mvnw clean install
 ```
 
-## Create the Azure resources and deploy the code
+### 6. Create the Azure resources and deploy the code
 
 Run the following command to create the Azure resources and deploy the code (about 15-minutes to complete):
 
 ```shell
 azd up
 ```
 
-## Tear down the deployment
+### 7. Tear down the deployment
 
 Run the following command to tear down the deployment:
 
@@ -161,10 +165,26 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
+## Additional links
+
+- [Known issues](known-issues.md)
+- [Troubleshooting](troubleshooting.md)
+- [Pattern Simulations](demo.md)
+- [Developer Experience](developer-experience.md)
+- [Calculating SLA](sla-calculation.md)
+- [Find additional resources](additional-resources.md)
+- [Report security concerns](SECURITY.md)
+- [Find Support](SUPPORT.md)
+- [Contributing](CONTRIBUTING.md)
+
 ## Trademarks
 
 This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
 trademarks or logos is subject to and must follow 
 [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
 Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
 Any use of third-party trademarks or logos are subject to those third-party's policies.
+
+## Data Collection
+
+The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkId=521839. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

additional-resources.md

@@ -0,0 +1,32 @@
+# Starting your modernization journey
+
+In this guide, we've shared how Contoso Fiber modernized their Customer Account Management System (CAMS) by leveraging Azure's cloud-native capabilities, addressing scalability, reliability, and cost optimization. Contoso made these changes to break free from limitations of their monolithic setup, allowing for easier scaling and more efficient handling of fluctuating demand. These strategies, drawn from Azure resources and best practices, illustrate a modernization path that other businesses can follow to achieve similar benefits.
+
+This section highlights those key resources, providing a deeper dive into Azure’s architecture and modernization techniques that empower other projects to succeed with cloud-native solutions.
+
+## Additional sources for Azure Best Practices
+
+Use the following resources to learn more about Microsoft's best practices and recommendations for building solutions on Azure.
+
+For further guidance on how to build Azure solutions that align with Microsoft's best practices and recommendations
+
+- [Cloud Adoption Framework](https://learn.microsoft.com/azure/cloud-adoption-framework/overview) - Helps an organization prepare and execute their strategy to build solutions on Azure.
+- [Azure Architecture Center fundamentals](https://learn.microsoft.com/azure/architecture/guide/) - Provides a library of content that presents a structured approach for designing applications on Azure that are scalable, secure, resilient, and highly available.
+- [Well Architected Framework](https://learn.microsoft.com/azure/architecture/framework/) - Describes the best practices and design principles that should be applied when designing Azure solutions that align with Microsoft's recommended best practices.
+- [Azure Architectures](https://learn.microsoft.com/azure/architecture/browse/) - Provides architecture diagrams and technology descriptions for reference architectures, real world examples of cloud architectures, and solution ideas for common workloads on Azure.
+
+## Additional sources for Azure Migration
+
+The following tools and resources can help you with migrating on-prem resources to Azure.
+
+- [Azure Migrate](https://learn.microsoft.com/azure/migrate/migrate-services-overview) - Azure Migrate provides a simplified migration, modernization, and optimization service for Azure that handles assessment, migration of web apps, SQL server, and Virtual Machines.
+- [Azure Database Migration Guides](https://learn.microsoft.com/data-migration/) - Provides resources for different database types, and different tools designed for your migration scenario.
+- [Azure App Service Landing Zone Accelerator](https://learn.microsoft.com/azure/cloud-adoption-framework/scenarios/app-platform/app-services/landing-zone-accelerator) - Deployment architecture guidance for hardening and scaling Azure App Service deployments.
+- [Register an application](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app) - Quickstart: Register an application with the Microsoft identity platform.
+- [Application authentication certificate credentials](https://learn.microsoft.com/entra/identity-platform/certificate-credentials) - Microsoft identity platform application authentication certificate credentials.
+
+## References
+
+- [Well-Architected Framework](https://docs.microsoft.com/azure/architecture/framework/)
+- [12 Factor Application](https://12factor.net/)
+- [Retry Pattern](https://docs.microsoft.com/azure/architecture/patterns/retry)