Enterprise-grade Reference Architecture for JavaScript

This repository contains the reference architecture and components for building enterprise-grade modern composable frontends (or micro-frontends) and cloud-native applications. It is a collection of best practices, architecture patterns, and functional components that can be used to build and deploy modern JavaScript applications to Azure.

Table of Contents

You can navigate through the documentation using the table of contents below:

• Enterprise-grade Reference Architecture for JavaScript
  • Table of Contents
  • Architecture Diagram
  • Simplified Flow Diagram
  • Components
    • Frontend
    • Backend
    • DevOps
    • Developer tools
  • Development environment
  • Developer Guide (Website)
    • 1 | Preview Website
    • 2 | Deploy Website
    • 3 | Test Website
  • Usage costs
  • Project structure
  • Deploy to Azure
    • Prerequisites
    • Deploy to Azure
    • Configure CI-CD
    • Clean up resources
  • Want to help?

Architecture Diagram

Simplified Flow Diagram

flowchart TD
    %% 

    subgraph Internet
    Portal[https://portal.contoso.com]
    Blog[https://blog.contoso.com]
    CMS[https://cms.contoso.com]
    Stripe[https://stripe.contoso.com]
    API[https://api.contoso.com]
    end
    
    subgraph Azure API Management
    APIM(API Gateway)
    end
    
    subgraph Azure Static Web Apps
    SWA_Angular([Angular])
    end 

    subgraph Azure Functions
    Functions([Node.js])
    end 

    subgraph Azure Container Apps
    ACA_Next([Next.js])
    ACA_Strapi([Strapi])
    ACA_Stripe([Stripe])
    end 

    subgraph Database/Storage
    DB_PostresSQL[(PostgreSQL - Strapi)]
    DB_Mongo[(MongoDB - Portal)]
    Storage([Azure Blob Storage - CMS])
    end 

    Portal --> SWA_Angular -- "portal.contoso.com/api/**" --> APIM -- "portal.contoso.com/api/**" --> Functions
    
    Blog -- "blog.contoso.com" --> ACA_Next -. "Strapi API" .-> ACA_Strapi
    
    CMS -- "cms.contoso.com" --> ACA_Strapi
    ACA_Strapi -- "read/write" ----> DB_PostresSQL -- "read only" --> Functions
    ACA_Strapi -- "upload" --> Storage
    
    API --> APIM -- "api.contoso.com" --> Functions <-- "read/write" --> DB_Mongo

    Stripe ---> APIM -- "stripe.contoso.com" --> ACA_Stripe <-. "validate payment (through APIM)" .-> Functions
    
    %% Portal
    linkStyle 0 stroke:pink
    linkStyle 1 stroke:pink
    linkStyle 2 stroke:pink

    %% Blog
    linkStyle 3 stroke:blue
    linkStyle 4 stroke:blue
    linkStyle 5 stroke:blue
    
    %% CMS
    linkStyle 5 stroke:red
    linkStyle 6 stroke:red
    linkStyle 8 stroke:red
    
    linkStyle 7 stroke:lime
    linkStyle 9 stroke:lime
    linkStyle 10 stroke:lime
    linkStyle 11 stroke:lime

Components

Frontend

• Angular - The Portal application used to view and book listings.
• Next.js - The Blog application used to view and create blog posts.
• Playwright - The end-to-end testing of the Portal application.
• Azure Static Web Apps - The hosting of the Portal application.

Backend

• Strapi - The CMS application used to manage the data for the Portal and Blog applications.
• Stripe - The payment processing.
• Fastify - The API used that interfaces with the Stripe API and Portal application.
• Azure Functions - The API used to communicate with Portal application.
• MongoDB for Azure Cosmos DB - The database used to store the data for the Portal application.
• Azure Database for PostgreSQL - The database used to store the data for the CMS application.
• Azure Storage - The storage used to store the data for the CMS and Blog application.
• Azure Container Apps - The hosting of the Blog, Stripe and Strapi APIs.
• Azure Application Insights - Monitoring and accessing logs for the applications and APIs.

DevOps

• Azure CLI - Provisioning, managing and deploying the application to Azure.
• GitHub Actions - The CI/CD pipelines.
• Azure Developer CLI - The CI/CD pipelines.

Developer tools

• Visual Studio Code - The local IDE experience.
• GitHub Codespaces - The cloud IDE experience.
• Azure Static Web Apps CLI - Accelerates the process of building cloud apps on Azure.

Development environment

This project is optimized for use with GitHub Codespaces, a development environment hosted in the GitHub cloud. Here is how to get started:

1. Fork this repository.
2. Create a new GitHub Codespaces from your fork. This will automatically provision a new Codespaces with all the required dependencies preinstalled and configured.
3. Open the terminal and run npm install && npm start to start the development servers. Note: Codespaces will show a series of windows on the right side of the screen while starting all servers. This is normal and expected.
4. Once all dev servers have started, the following URLs will be available:

Note: The URLs above are just examples. The URLs will be different for your fork. The ports however will be the same.

Developer Guide (Website)

The project has a Developer Guide defined under packages/docs and implemented as an interactive website using the Docusaurus platform.

1 | Preview Website

• Read the website/README for more details on setting up and building this package.
• Use the following instructions for a quickstart.

$ cd packages/docs/website     # Set working directory
$ npm install                  # Install dependencies
$ npm run start                # Run dev server, launch preview
..
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

This should launch the browser to the landing page of the guide as shown below:

2 | Deploy Website

This repo is not configured for automated deployment of the website to a static site hosting service. However Docusaurus provides Deployment guidance that works for most options - we've validated this for Azure Static Web Apps and GitHub Pages.

If you want a hosted version of the guide, we recommend you maintain a personal fork and set it up for automated build-deploy with GitHub Actions. Then keep up-to-date with origin, for content.

• See this personal fork for a working example for reference
• Visit this GitHub Pages endpoint to see the associated live deployment.
• Note that this example may not always reflect the latest repo changes in content.

3 | Test Website

The website comes with its own Playwright testing harness with a separate configuration and a base test specification. Use it for test-driven documentation to validate the existence of routes and sections, and check content for accessibility compliance. Note - this test suite is separate from e2e testing setup for Contoso Real Estate application (located in packages/testing).

• Learn more about test setup in website/README.TESTING.md.
• Use the following instructions for a quickstart.

$ cd packages/docs/website     # Set working directory
$ npm install                  # Install dependencies
$ npm run test                 # Run dev server => launches browser to preview
$ npm run report               # View last HTML report => open browser to specified URL

Want to understand what the test report provides? You can explore this cached version of the report interactively (screenshot below) to dive into detailed traces. Note that the cached version will not reflect the latest codebase updates and is meant only as an example.

Usage costs

Github Codespaces usage is billed either to an organization or to the user creating it. There are limits to the number of concurrent codespaces you can create or run, so here are a few things to keep in mind:

• Personal accounts get a free monthly usage quota of 120 hours and 15GB storage - enough to explore this project!
• You can lookup current usage or set spending limits on your profile - to ensure you don't accidentally exceed your quota or budget.
• We recommend you delete codespaces you are not actively using, and configure default retention periods to maximize usage of your free quota and minimize costs for paid usage.

Project structure

The project is using npm workspaces. The project structure is as follows:

• packages/ - contains all the packages
  • api - contains the serverless Azure Functions API.
  • portal - contains the Angular web portal.
  • blog - contains the Next.js blog.
  • blog-cms - contains the Strapi CMS.
  • docs - contains the Developer Guide website
  • stripe - contains the Stripe webhook.
  • testing - contains the Playwright tests.

Deploy to Azure

Prerequisites

This project uses GitHub Codespaces as the main development environment. The following steps assume you are using GitHub Codespaces. If you are not using GitHub Codespaces, you can open the project in a Dev Container locally following the instructions here.

Deploy to Azure

This project uses Azure Developer CLI (azd) to provision infrastructure, package, and deploy the application to Azure. Running the following commands will get you started with deployment.

# Login to azd. Only required once per install.
azd auth login

# Use Flag if login does not work
azd auth login --use-device-code

# Provision infrastructure and the azd development environment
azd provision

# Package the app using the environment variables in .azure/env + deploy the code on Azure
azd deploy

The --use-device-code is used to log in by using a device code instead of a browser, this may resolve any browser issues while logging in. For more information on when & why to use flags, check here

If you encounter issues with the Azure Developer CLI, please open an issue here.

Important: It is mandatory to run these azd commands in this order. Provisioning first will create the azd development environment and outputs the .env file with the required environment variables. Packaging will package the application using some of the environment variables from the .env file.

Deployment region: Your deployment may fail if the region you selected is unavailable for provisioning specific resources. We recommend using westeurope as your target region since that has been currently validated for all services.

Configure CI-CD

Use the following command to configure the CI-CD pipelines:

azd pipeline config --auth-type client-credentials

Clean up resources

When you are done, you can delete all the Azure resources created with this template by running the following command:

azd down

Want to help?

Want to file a bug, contribute some code, or improve the documentation? Excellent! Read up on our guidelines for contributing and then check out one of our issues in the list: community-help.