docs: added architecture documentation (#9256)

* docs: added architecture documentation * update diagrams and text * address PR comments * sidebar + overview fixes
2024-09-26 09:29:47 +03:00
parent e096feb7d5
commit 2da15ba021
6 changed files with 82 additions and 11 deletions
@@ -0,0 +1,33 @@
+export const metadata = {
+  title: `${pageNumber} Architectural Modules`,
+}
+
+# {metadata.title}
+
+In this chapter, you’ll learn about architectural modules.
+
+## What is an Architectural Module?
+
+An architectural module implements features and mechanisms related to the Medusa application’s architecture and infrastructure.
+
+Since modules are interchangeable, you have more control over Medusa’s architecture. For example, you can choose to use Memcached for event handling instead of Redis.
+
+---
+
+## 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/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.
+
+---
+
+## Architectural Modules List
+
+Refer to the [Architectural Modules reference](!resources!/architectural-modules) for a list of Medusa’s architectural modules, available modules to install, and how to create an architectural module.
@@ -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)