docs: added architecture documentation (#9256)

* docs: added architecture documentation

* update diagrams and text

* address PR comments

* sidebar + overview fixes

www/apps/book/app/advanced-development/architecture/architectural-modules/page.mdx

@@ -14,14 +14,15 @@ Since modules are interchangeable, you have more control over Medusa’s archite
 
 ---
 
-### Architectural Module Type
+## Architectural Module Types
 
 There are different architectural module types including:
 
-![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1716197340/Medusa%20Book/architectural-modules_bj9bb9.jpg)
+![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727095814/Medusa%20Book/architectural-modules_bj9bb9.jpg)
 
 - Cache Module: Defines the caching mechanism or logic to cache computational results.
 - Event Module: Integrates a pub/sub service to handle subscribing to and emitting events.
+- Workflow Engine Module: Integrates a service to store and track workflow executions and steps.
 - File Module: Integrates a storage service to handle uploading and managing files.
 - Notification Module: Integrates a third-party service or defines custom logic to send notifications to users and customers.
 

www/apps/book/app/advanced-development/architecture/overview/page.mdx

@@ -0,0 +1,58 @@
+export const metadata = {
+  title: `${pageNumber} Medusa's Architecture`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn about the architectural layers in Medusa.
+
+## HTTP, Workflow, and Module Layers
+
+Medusa is a headless commerce platform. So, storefronts, admin dashboards, and other clients consume Medusa's functionalities through its API routes.
+
+In a common Medusa application, requests go through four layers in the stack. In order of entry, those are:
+
+1. API Routes (HTTP): Our API Routes are the typical entry point.
+2. Workflows: API Routes consume workflows that hold the opinionated business logic of your application.
+3. Modules: Workflows use domain-specific modules for resource management.
+3. Data store: Modules query the underlying datastore, which is a PostgreSQL database in common cases.
+
+![Diagram illustrating the HTTP layer](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175296/Medusa%20Book/http-layer_sroafr.jpg)
+
+---
+
+## Database Layer
+
+The Medusa application injects into each module a connection to the configured PostgreSQL database.
+
+Modules use that connection to read and write data to the database.
+
+![Diagram illustrating the database layer](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175379/Medusa%20Book/db-layer_pi7tix.jpg)
+
+---
+
+## Service Integrations
+
+Third-party services are integrated through commerce and architectural modules.
+
+You also create custom third-party integrations through a custom module.
+
+### Commerce Modules
+
+Commerce modules integrate third-party services relevant for commerce or user-facing features. For example, you integrate Stripe through a payment module provider.
+
+![Diagram illustrating the commerce modules integration to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175357/Medusa%20Book/service-commerce_qcbdsl.jpg)
+
+### Architectural Modules
+
+Architectural modules integrate third-party services and systems for architectural features. For example, you integrate Redis as a pub/sub service to send events, or SendGrid to send notifications.
+
+![Diagram illustrating the architectural modules integration to third-party services and systems](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175342/Medusa%20Book/service-arch_ozvryw.jpg)
+
+---
+
+## Full Diagram of Medusa's Architecture
+
+The following diagram illustrates Medusa's architecture over the three layers.
+
+![Full diagram illustrating Medusa's architecture](https://res.cloudinary.com/dza7lstvk/image/upload/v1727174897/Medusa%20Book/architectural-diagram-full.jpg)

www/apps/book/app/advanced-development/page.mdx

@@ -6,7 +6,7 @@ export const metadata = {
 
 In the previous chapters, you got a brief introduction to Medusa’s basic concepts. However, to build a custom commerce application, you need a deeper understanding of how you utilize these concepts for your business use case.
 
-The next chapters dive deeper into each concept. By the end of these chapters, you’ll be able to:
+The next chapters dive deeper into each concept, and explores Medusa's architecture. By the end of these chapters, you’ll be able to:
 
 - Expose API routes with control over authentication.
 - Build sophisticated business logic in modules and manage links between them.

www/apps/book/generated/edit-dates.mjs

@@ -20,7 +20,6 @@ export const generatedEditDates = {
   "app/first-customizations/page.mdx": "2024-09-11T10:48:42.374Z",
   "app/debugging-and-testing/page.mdx": "2024-05-03T17:36:38+03:00",
   "app/basics/medusa-container/page.mdx": "2024-09-03T07:31:40.214Z",
-  "app/architectural-modules/page.mdx": "2024-07-04T17:26:03+03:00",
   "app/basics/project-directories-files/page.mdx": "2024-07-04T17:26:03+03:00",
   "app/basics/api-routes/page.mdx": "2024-09-11T10:48:31.777Z",
   "app/basics/modules-directory-structure/page.mdx": "2024-05-07T18:00:28+02:00",
@@ -103,7 +102,8 @@ export const generatedEditDates = {
   "app/customization/integrate-systems/service/page.mdx": "2024-09-12T12:39:12.831Z",
   "app/customization/next-steps/page.mdx": "2024-09-12T10:50:04.873Z",
   "app/customization/page.mdx": "2024-09-12T11:16:18.504Z",
-  "app/debugging-and-testing/instrumentation/page.mdx": "2024-09-17T08:53:15.910Z",
   "app/more-resources/cheatsheet/page.mdx": "2024-07-11T16:11:26.480Z",
-  "app/more-resources/examples/page.mdx": "2024-09-19T10:30:30.398Z"
+  "app/more-resources/examples/page.mdx": "2024-09-19T10:30:30.398Z",
+  "app/architecture/architectural-modules/page.mdx": "2024-09-23T12:51:04.520Z",
+  "app/architecture/overview/page.mdx": "2024-09-23T12:55:01.339Z"
 }

www/apps/book/next.config.mjs

@@ -139,6 +139,11 @@ const nextConfig = {
         destination: "/more-resources/cheatsheet",
         permanent: true,
       },
+      {
+        source: "/architectural-modules",
+        destination: "/advanced-development/architecture/architectural-modules",
+        permanent: true,
+      },
     ]
   },
 }

www/apps/book/sidebar.mjs

@@ -190,6 +190,18 @@ export const sidebar = numberSidebarItems(
       title: "Advanced Development",
       chapterTitle: "Advanced",
       children: [
+        {
+          type: "link",
+          title: "Architecture",
+          path: "/advanced-development/architecture/overview",
+          children: [
+            {
+              type: "link",
+              path: "/advanced-development/architecture/architectural-modules",
+              title: "Architectural Modules",
+            },
+          ],
+        },
         {
           type: "link",
           title: "API Routes",
@@ -485,11 +497,6 @@ export const sidebar = numberSidebarItems(
         },
       ],
     },
-    {
-      type: "link",
-      path: "/architectural-modules",
-      title: "Architectural Modules",
-    },
     {
       type: "link",
       path: "/debugging-and-testing",