docs: docs update and overhaul #434
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
manekinekko marked this conversation as resolved.
Show resolved
Hide resolved
|
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,7 +8,32 @@ ms.topic: overview #Required | |
| ms.date: #Required; mm/dd/yyyy format. | ||
| --- | ||
|
|
||
| # 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. | ||
|
|
||
| [Additional details about what the Contoso Real Estate app is and what it does from a high-level – possibly has some images from the running app]. | ||
|
|
||
| ### Supported App Scenarios | ||
|
There was a problem hiding this comment. This is really nice to have for devs first viewing the repo. I see 8 scenarios in the diagram and scenarios docs (https://30daysof.github.io/contoso-real-estate/intro/) though but only 5 here. Do we want this overview to match up with the scenario docs? There was a problem hiding this comment. FYI, scenario 7 (Redis Caching) has been deprioritized and hasn't been implemented yet. |
||
|
|
||
| The following scenarios are part of the application sample | ||
|
|
||
| - [AI Chatbot integration (RAG Pattern)](./chatbot-integration-scenario.md) | ||
|
|
||
| - [Payments integration with Stripe](./payments-service-scenario.md) | ||
|
|
||
| - Real-time Notifications | ||
|
|
||
| - Portal application, a main portal entry point, featuring listings, favorites, user authentication and profile | ||
|
|
||
| - [Headless CMS and blog](./blog-scenario.md) | ||
|
|
||
| ## Developer guidelines | ||
|
|
||
| The page you're reading and other documentation in this folder, are a summary guide. The project has a standalone [Developer Guide](./packages/docs/website/README.md) defined under `packages/docs` and implemented as an interactive website using the [Docusaurus](https://docusaurus.io) platform. To learn more about it, [go here](./packages/docs/website/developer-guidelines.md). | ||
|
|
||
| # Contoso Rentals Overview | ||
|
|
||
| Contoso Corporation is a fictional but representative global manufacturing conglomerate with its headquarters in Paris. The company deployed Microsoft 365 for enterprise and addressed major design decisions and implementation details for networking, identity, Windows 10 Enterprise, Microsoft 365 Apps for enterprise, mobile device management, information protection, and security. | ||
|
|
||
|
|
@@ -24,7 +49,7 @@ The Contoso HR App is part of the Contoso platform and designed to serve interna | |
|
|
||
| ## App architecture | ||
|
|
||
| To support this app functionality, the Contoso engineering team decided to build the app with the following structure: | ||
manekinekko marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| - Web app with a custom domain | ||
| - UI for blog and portal front ends | ||
|
|
@@ -38,14 +63,12 @@ To support this app functionality, the Contoso engineering team decided to build | |
| - Monitoring | ||
| - Payments | ||
|
|
||
|  | ||
|
|
||
| ## Azure architecture | ||
|
|
||
| To build, deploy, manage, test, and monitor this web app, Contoso selected Azure. With the help of Azure architects, the following architecture was selected. | ||
|
|
||
|  | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
|
|
||
| The project has a [Developer Guide](./packages/docs/website/README.md) defined under `packages/docs` and implemented as an interactive website using the [Docusaurus](https://docusaurus.io) platform. | ||
|
|
||
| ### 1 | Preview Website | ||
|
|
||
| - Read the [website/README](./packages/docs/website/README.md) for more details on setting up and building this package. | ||
| - Use the following instructions for a quickstart. | ||
|
|
||
| ```bash | ||
| $ 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: | ||
|
|
||
| <p align="center"> | ||
| <img src="../assets/screenshots/contoso-docs-website-preview.png" width="100%" alt="Contoso Real Estate Developer Guide: Preview"/> | ||
| </p> | ||
|
|
||
| ### 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](https://docusaurus.io/docs/deployment) that works for most options - we've validated this for [Azure Static Web Apps](https://docusaurus.io/docs/deployment#deploying-to-azure-static-web-apps) and [GitHub Pages](https://docusaurus.io/docs/deployment#deploying-to-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](https://github.com/30DaysOf/contoso-real-estate) for a working example for reference | ||
| - Visit [this GitHub Pages endpoint](https://30daysof.github.io/contoso-real-estate/) 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](./packages/docs/website/README.md). | ||
| - Use the following instructions for a quickstart. | ||
|
|
||
| ```bash | ||
| $ 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](https://30daysof.github.io/contoso-real-estate/playwright-trace/) 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. | ||
|
|
||
| <p align="center"> | ||
| <img src="../assets/screenshots/contoso-docs-website-testreport.png" width="100%" alt="Contoso Real Estate Developer Guide: Test Report"/> | ||
| </p> |
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| # Contoso Real Estate App: Portal Package | ||
|
|
||
| **IMPORTANT: THIS REPOSITORY IS OPTIMIZED FOR CODESPACES AND TO WORK AS A SET OF COMPOSABLE APPS AND APIS. STANDALONE PACKAGE FUNCTIONALITY IS LIMITED AND MAY REQUIRE ADDITIONAL CONFIGURATION OR DEVELOPMENT** | ||
|
|
||
| This document will guide you through the prerequisites and commands necessary to setup and preview the portal project, locally on your computer. This document will guide you through the prerequisites and commands necessary to setup and preview the portal project, locally on your computer. | ||
|
|
||
| It will also instruct you how to deploy it to [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview), to publish it to the cloud, independently, using the [Azure Static Web Apps CLI](https://azure.github.io/static-web-apps-cli/). | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| **IMPORTANT: THIS SCENARIO IS TIGHTLY COUPLED WITH SCENARIO 1. SOME PARTS OF THIS APP MAY NOT WORK AS EXPECTED IF YOU DON'T FOLLOW THE INSTRUCTIONS IN SCENARIO 1.** | ||
|
|
||
| In order to start the development server for local development or locally browsing the portal site, the following technologies must be installed in your computer: | ||
|
|
||
| - [Node.js LTS](https://nodejs.org) | ||
| - [Azure Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local) | ||
| - [Azure Static Web Apps CLI](https://azure.github.io/static-web-apps-cli/) | ||
|
|
||
| ### Angular CLI | ||
|
|
||
| This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.3. | ||
|
|
||
| ## Steps to start the portal | ||
|
|
||
| 1. fork or clone the repository locally | ||
| 2. assuming you are in the folder containing `contoso-real-estate/packages/portal`, go to the terminal and run | ||
|
|
||
| ```bash | ||
| npm run clean:install | ||
| ``` | ||
|
|
||
| at the root level of the repository. This will install all dependencies for all scenarios. | ||
|
|
||
| This operation will also install the [Azure Static Web Apps CLI](https://azure.github.io/static-web-apps-cli/docs/intro). This tool includes a local dev server and emulator, to test the application and the corresponding API together, locally. | ||
|
|
||
| 3. assuming you are now in the `contoso-real-estate`, go to the terminal and run | ||
|
|
||
| ```bash | ||
| npm start | ||
| ``` | ||
|
|
||
| Follow the [Azure Static Web Apps CLI](https://azure.github.io/static-web-apps-cli/docs/cli/swa) prompts to complete the configuration. | ||
|
|
||
| Your default browser should open a new window with the application running. If you did not pass a port option, it should be running at [http://localhost:4280](http://localhost:4280) | ||
|
|
||
| 5. Go to `http://localhost:4280`. The application and the API should be running and functional. You should be able to see the homepage and the cards or teasers for the listings. You should be able to navigate to any of the listings detail page by clicking in any of the cards. | ||
|
|
||
| ## Troubleshooting the local setup | ||
|
|
||
| - Q: The application server starts up but I can't see the listings | ||
| - A: Go to `http://localhost:7071/api/listings` and make sure you see a JSON printed in the browser. | ||
|
|
||
| - Q: The application server starts up but I can't navigate to any of the listings detail pages | ||
| - A: Go to `http://localhost:7071/api/listings` and make sure you see a JSON printed in the browser | ||
|
|
||
| - Q: The application server starts up but I can't navigate to any of the listings detail pages | ||
| - A: Make sure you are accessing the portal served by the SWA CLI `http://localhost:4280` (and not the Angular CLI). | ||
|
|
||
| ## Deploying to Azure with the Azure Static Web Apps CLI | ||
|
|
||
| If you want to deploy to Azure using this tool, you will need an active subscription to [Azure](https://azure.microsoft.com/en-us/free/), to use any of the available regions listed [here](https://azure.github.io/static-web-apps-cli/docs/cli/env-vars) | ||
|
|
||
| 1. Assuming you are in the folder `contoso-real-estate/packages/portal` go to the terminal and run | ||
|
|
||
| ```bash | ||
| swa deploy | ||
| ``` | ||
|
|
||
| 2. Follow prompt instructions. | ||
|
|
||
| ## Troubleshooting the deployment | ||
|
|
||
| If the deployment fails | ||
|
|
||
| - **Check** if you exceeded the maximum quota for free apps. Check the limits and quotas for the free tier [here](https://learn.microsoft.com/en-us/azure/static-web-apps/quotas) | ||
| - **Check** that your subscription id and tenant id are correctly configured under `contoso-real-estate/packages/portal/.env` for variables | ||
|
|
||
| ```js | ||
| AZURE_SUBSCRIPTION_ID= | ||
| AZURE_TENANT_ID= | ||
| ``` | ||
|
|
||
| - **Change** the region target to an alternative region, if it's unavailable or saturated - select from regions listed [here](https://azure.github.io/static-web-apps-cli/docs/cli/env-vars) | ||
|
|
||
| ```js | ||
| AZURE_REGION_LOCATION= | ||
| ``` | ||
|
|
||
| - **Check** for a configuration file called `staticwebapp.config.json`, under `contoso-real-estate/packages/portal/src/assets/`. Make sure to add the following snippet: | ||
|
|
||
| ```json | ||
| { | ||
| // other config: { | ||
| // ... config | ||
| // }, | ||
| "platform": { | ||
| "apiRuntime": "node:16" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| - **Run** If your deployment still fails, run | ||
|
|
||
| ```bash | ||
| swa deploy verbose=silly | ||
| ``` | ||
|
|
||
| Copy the log and open an issue in our open-source [Azure Static Web Apps CLI repository](https://github.com/Azure/static-web-apps-cli). We will love to hear from you! | ||
|
|
||
| ### Portal scenario diagram | ||
|
|
||
| This scenario is represented by the following diagram | ||
|  | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # Contoso Real Estate App: Portal Package | ||
|
|
||
| **IMPORTANT: THIS REPOSITORY IS OPTIMIZED FOR CODESPACES AND TO WORK AS A SET OF COMPOSABLE APPS AND APIS. STANDALONE PACKAGE FUNCTIONALITY IS LIMITED AND MAY REQUIRE ADDITIONAL CONFIGURATION OR DEVELOPMENT** | ||
|
|
||
| This document will guide you through the prerequisites and commands necessary to setup and preview the real time notifications service. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| **IMPORTANT: THIS SCENARIO IS TIGHTLY COUPLED WITH SCENARIOS 1 and 2. SOME PARTS OF THIS APP MAY NOT WORK AS EXPECTED IF YOU DON'T FOLLOW THE INSTRUCTIONS IN SCENARIOS 1 and 2, corresponding to the Headless CMS and Blog features, and the portal app.** | ||
|
|
||
|
|
||
| ## Steps to enable the service | ||
|
|
||
| 1 - Create a Web PubSub For Socket.IO resource. | ||
| Click key tab in resource portal, copy connection string. | ||
|
|
||
| 2 - Rename .env.example under packages/realtime/ to .env. Then fill in copied connection string to variable WebPubSubConnectionString | ||
|
|
||
| 3 - Copy the endpoint part in connection string (e.g. https://<resource-name>.webpubsub.azure.com). And use it replace the default endpoint in packages/portal/src/app/shared/realtime.service.ts:L14 | ||
| Follow original README to go on. | ||
|
Comment on lines
+12
to
+20
There was a problem hiding this comment. FYI, these manual steps are temporarily required untill we add Bicep/azd support for Web PubSub. |
||
|
|
||
|
|
||
| ### Real-time notification service scenario diagram | ||
|
|
||
| This scenario is represented by the following diagram | ||
|  | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good addition. We'll try to get this moved into Training modules in the near future so the content is on a 1P resource and more discoverable.