From 2da15ba021092290b97c4731a12f57a7e7c141b9 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 26 Sep 2024 09:29:47 +0300 Subject: [PATCH] docs: added architecture documentation (#9256) * docs: added architecture documentation * update diagrams and text * address PR comments * sidebar + overview fixes --- .../architectural-modules/page.mdx | 5 +- .../architecture/overview/page.mdx | 58 +++++++++++++++++++ .../book/app/advanced-development/page.mdx | 2 +- www/apps/book/generated/edit-dates.mjs | 6 +- www/apps/book/next.config.mjs | 5 ++ www/apps/book/sidebar.mjs | 17 ++++-- 6 files changed, 82 insertions(+), 11 deletions(-) rename www/apps/book/app/{ => advanced-development/architecture}/architectural-modules/page.mdx (83%) create mode 100644 www/apps/book/app/advanced-development/architecture/overview/page.mdx diff --git a/www/apps/book/app/architectural-modules/page.mdx b/www/apps/book/app/advanced-development/architecture/architectural-modules/page.mdx similarity index 83% rename from www/apps/book/app/architectural-modules/page.mdx rename to www/apps/book/app/advanced-development/architecture/architectural-modules/page.mdx index 19d8fd3cf5..84ac04ca21 100644 --- a/www/apps/book/app/architectural-modules/page.mdx +++ b/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. diff --git a/www/apps/book/app/advanced-development/architecture/overview/page.mdx b/www/apps/book/app/advanced-development/architecture/overview/page.mdx new file mode 100644 index 0000000000..e754f9daca --- /dev/null +++ b/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) diff --git a/www/apps/book/app/advanced-development/page.mdx b/www/apps/book/app/advanced-development/page.mdx index 5db6c298b4..14c9a99784 100644 --- a/www/apps/book/app/advanced-development/page.mdx +++ b/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. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 9b3b3365d6..d82ca41f51 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/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" } \ No newline at end of file diff --git a/www/apps/book/next.config.mjs b/www/apps/book/next.config.mjs index c65a9e5087..6e84fe1cf8 100644 --- a/www/apps/book/next.config.mjs +++ b/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, + }, ] }, } diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index daaa143921..248cf35750 100644 --- a/www/apps/book/sidebar.mjs +++ b/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",